diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 3b965cd..08880a2 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -37,7 +37,7 @@ repos: hooks: - id: run-tests name: Run pytest before push - entry: pytest + entry: uv run pytest language: system stages: [pre-push] pass_filenames: false diff --git a/docs/archive/refactor-sdd-workflow-prompts.md b/docs/archive/refactor-sdd-workflow-prompts.md new file mode 100644 index 0000000..66564b6 --- /dev/null +++ b/docs/archive/refactor-sdd-workflow-prompts.md @@ -0,0 +1,141 @@ +# Spec-Driven Development Workflow Refactoring + +The main goal here is to improve the workflow while maintaining its simplicity. One of the main points of the workflow is to keep it simple and easy to use - that is what differentiates it from other workflows like Taskmaster, GitHub SpecKit, Kiro, etc. + +Additional goals: + +- The workflow should be accessible to newcomers +- Configuration should be barebones since different tools support different customizations. Any customization of the workflow should be handled within the prompts. + +## Best Practices to document + +1. Start each workflow command in a fresh conversation to avoid context confusion and overloading +2. Provide clear instructions on what to expect from the AI and what to expect from the user + +## Improvements + +### Improve prompt clarity and structure based on research findings + +Based on prompt engineering best practices for spec-driven development, the workflow should provide more guidance to newcomers without requiring constant reference to the README. Each prompt should guide users through the flow with clear context and next steps. + +**Prompt Structure Improvements:** + +- Use explicit role-based prompting ("You are a senior developer implementing...") +- Add chain-of-thought reasoning steps to prevent premature task generation +- Include negative constraints to prevent common failure modes +- Add output format templates with concrete examples +- Implement progressive disclosure - reveal complexity gradually + +**General pattern for all prompts:** + +- Each prompt should start with "You are here in the workflow" context +- End with "What comes next" guidance +- Include progress indicators where applicable + +#### Specific Prompt Enhancements + +**generate-spec.md:** + +- Add scope size validation prompts with the Bad/Good examples +- Add clear guidance on "What happens next" section after spec creation, including when to move to task generation and how to do it + +**generate-task-list-from-spec.md:** + +- Add explanation of why parent tasks are generated first +- Add guidance on how to evaluate top-level tasks against the spec +- Enhance the "Generate sub tasks" interaction with clearer context +- Add "DO NOT generate sub-tasks until explicitly requested" constraint +- Add clear guidance on "What happens next" section after task generation, including when to move to task implementation and how to do it + +**manage-tasks.md:** + +- Instruct the AI to present checkpoint options prominently at the start of this prompt +- Add a brief overview of what this prompt does and how it progresses through tasks +- Add clear guidance on "What happens next" section after task implementation, including when to move to validation and how to do it +- Add explicit commit enforcement protocol after each parent task completion to ensure consistent git history. Commits should be created, at minimum, for each parent task completion. +- Add proof artifact generation and validation steps to ensure they are created during task implementation and invocation of the `/manage-tasks` command + +**validate-spec-implementation.md:** + +- Add brief "When to use this prompt" context (after completing all tasks in a spec) +- Update Auto-Discovery Protocol to look in `./docs/specs/` instead of `/tasks/` + +### Scope size recommendation as part of initial spec creation + +The intent here is to detect when a spec is too large and should be split into multiple specs. The workflow is currently focused with the expected output of the workflow to be code changes of a relatively small scope. + +Similarly, the workflow should attempt to evaluate when a spec is too small and could probably be "vibe-coded" instead of going through the entire workflow. + +#### Bad Examples (scope too large) + +- Rewriting an entire application architecture or framework +- Migrating a complete database system to a new technology +- Refactoring multiple interconnected modules simultaneously +- Implementing a full authentication system from scratch +- Building a complete microservices architecture +- Creating an entire admin dashboard with all features +- Redesigning the entire UI/UX of an application +- Implementing a comprehensive reporting system with all widgets + +#### Bad Examples (scope too small) + +- Adding a single console.log statement for debugging +- Changing the color of a button in CSS +- Adding a missing import statement +- Fixing a simple off-by-one error in a loop +- Updating documentation for an existing function + +#### Good Examples (scope just right) + +- Adding a new CLI flag with validation and help text +- Implementing a single API endpoint with request/response validation +- Refactoring one module while maintaining backward compatibility +- Adding a new component with integration to existing state management +- Creating a single database migration with rollback capability +- Implementing one user story with complete end-to-end flow + +> Note: these examples should be incorporated into the documentation for this workflow. + +### Optional input for defining when the AI should ask the user for input/continue + +This would allow the user to specify how the AI should manage the implementation in `/manage-tasks`. Basically there are three options: + +- Ask for input/continue after each sub task (1.1, 1.2, 1.3) +- Ask for input/continue after each task (1.0, 2.0, 3.0) +- Ask for input/continue after each spec + +If the user does not specify one of these options up invocation of the `/manage-tasks` command, then the AI should ask the user which option they would like to use for this invocation. The prompt should instruct the AI to use any option that was previously specified by the user in the current conversation. + +### Centralize spec/tasks/proofs location + +All specs, tasks, and proofs should be stored in `./docs/specs`. Simple directory structure: + +```text +./docs/specs/ +├── 01-spec-feature-name + ├── 01-spec-feature-name.md + ├── 01-tasks-feature-name.md + └── 01-proofs/ + ├── 01-01-proofs.md + ├── 01-02-proofs.md + ├── 01-03-proofs.md +├── 02-spec-another-feature + ├── 02-spec-another-feature.md + ├── 02-tasks-another-feature.md + └── 02-proofs/ + ├── 02-01-proofs.md + ├── 02-02-proofs.md + ├── 02-03-proofs.md +``` + +**Key Principles:** + +- **Spec-based organization**: Each spec gets its own directory with related files +- **Co-located artifacts**: Proofs are organized by task number within each spec +- **Team-managed lifecycle**: Teams determine when to archive specs, tasks, and proofs as they see fit +- **Clear traceability**: Easy to see which proofs belong to which tasks and specs +- **Consistent naming**: Proof artifacts follow single Markdown file pattern `[spec]-[task]-proofs.md` containing all evidence as Markdown code blocks + +### Simplify numbering system + +The numbering system should have a single leading zero based on 01, 02, 03, etc. Having 3 leading zeros is not necessary and makes it more difficult to navigate the files. diff --git a/prompts/generate-spec.md b/prompts/generate-spec.md index 1b93dca..3418e76 100644 --- a/prompts/generate-spec.md +++ b/prompts/generate-spec.md @@ -1,6 +1,6 @@ --- name: generate-spec -description: "Generate a Specification (Spec) for a feature" +description: "Generate a Specification (Spec) for a feature with enhanced workflow guidance and scope validation" tags: - planning - specification @@ -10,65 +10,286 @@ meta: allowed-tools: Glob, Grep, LS, Read, Edit, MultiEdit, Write, WebFetch, WebSearch --- -## Generate Specification +# Generate Specification + +## You are here in the workflow + +We are at the **beginning** of the Spec-Driven Development Workflow. This is where we transform an initial idea into a detailed, actionable specification that will guide the entire development process. + +### Workflow Integration + +This spec serves as the **planning blueprint** for the entire SDD workflow: + +**Value Chain Flow:** + +- **Idea → Spec**: Transforms initial concept into structured requirements +- **Spec → Tasks**: Provides foundation for implementation planning +- **Tasks → Implementation**: Guides structured development approach +- **Implementation → Validation**: Spec serves as acceptance criteria + +**Critical Dependencies:** + +- **User Stories** become the basis for task demo criteria +- **Functional Requirements** drive implementation task breakdown +- **Technical Considerations** inform architecture and dependency decisions +- **Demoable Units** become parent task boundaries in task generation + +**What Breaks the Chain:** + +- Vague user stories → unclear demo criteria and task boundaries +- Missing functional requirements → gaps in implementation coverage +- Inadequate technical considerations → architectural conflicts during implementation +- Oversized specs → unmanageable task breakdown and loss of incremental progress + +## Your Role + +You are a **Senior Product Manager and Technical Lead** with extensive experience in software specification development. Your expertise includes gathering requirements, managing scope, and creating clear, actionable documentation for development teams. ## Goal -To guide an AI assistant in creating a detailed Specification (Spec) in Markdown format, based on an initial user prompt. The Spec should be clear, actionable, and suitable for a junior developer to understand and implement the feature. +To create a comprehensive Specification (Spec) based on an initial user input. This spec will serve as the single source of truth for a feature. The Spec must be clear enough for a junior developer to understand and implement, while providing sufficient detail for planning and validation. + +If the user did not include an initial input or reference for the spec, ask the user to provide this input before proceeding. + +## Process Overview + +Follow this exact sequence: + +1. **Initial Scope Assessment** - Evaluate if the feature is appropriately sized for this workflow +2. **Clarifying Questions** - Gather detailed requirements through structured inquiry +3. **Context Assessment** - Review existing codebase for relevant patterns and constraints (optional) +4. **Spec Generation** - Create the detailed specification document +5. **Review and Refine** - Validate completeness and clarity with the user + +## Step 1: Initial Scope Assessment + +Before asking questions, evaluate whether this feature request is appropriately sized for this spec-driven workflow. + +**Chain-of-thought reasoning:** + +- Consider the complexity and scope of the requested feature +- Compare against the following examples +- If scope is too large, suggest breaking into smaller specs +- If scope is too small, suggest direct implementation without formal spec + +**Scope Examples:** + +**Too Large (split into multiple specs):** + +- Rewriting an entire application architecture or framework +- Migrating a complete database system to a new technology +- Refactoring multiple interconnected modules simultaneously +- Implementing a full authentication system from scratch +- Building a complete microservices architecture +- Creating an entire admin dashboard with all features +- Redesigning the entire UI/UX of an application +- Implementing a comprehensive reporting system with all widgets + +**Too Small (vibe-code directly):** + +- Adding a single console.log statement for debugging +- Changing the color of a button in CSS +- Adding a missing import statement +- Fixing a simple off-by-one error in a loop +- Updating documentation for an existing function + +**Just Right (perfect for this workflow):** + +- Adding a new CLI flag with validation and help text +- Implementing a single API endpoint with request/response validation +- Refactoring one module while maintaining backward compatibility +- Adding a new component with integration to existing state management +- Creating a single database migration with rollback capability +- Implementing one user story with complete end-to-end flow + +If the scope appears inappropriate, inform the user and suggest alternatives before proceeding. + +## Step 2: Clarifying Questions + +Ask clarifying questions to gather sufficient detail. **Always provide numbered or lettered options** to allow the user to make selections easily by responding with *"1A, 2B, 3C"*, etc. Focus on understanding the "what" and "why" rather than the "how." + +Adapt your questions based on the user's input. Use the following common areas to guide your questions: + +**Core Understanding:** + +- What problem does this solve and for whom? +- What specific functionality does this feature provide? + +**Success & Boundaries:** + +- How will we know it's working correctly? +- What should this NOT do? +- Are there edge cases we should explicitly include or exclude? + +**Design & Technical:** + +- Any existing design mockups or UI guidelines to follow? +- Are there any technical constraints or integration requirements? + +**Demo & Proof:** + +- How will we demonstrate this feature works? +- What proof artifacts will we need (URLs, CLI output, screenshots)? + +**Progressive Disclosure:** Start with Core Understanding, then expand based on feature complexity and user responses. + +## Step 3: Context Assessment (Optional) + +If the feature involves existing systems, briefly review the codebase and existing docs to understand: + +- Current architecture patterns and conventions +- Relevant existing components or features +- Integration constraints or dependencies +- Files that might need modification or extension +- **Repository Standards and Patterns**: Identify existing coding standards, architectural patterns, and development practices from: + - Project documentation (README.md, CONTRIBUTING.md, docs/) + - Configuration files (package.json, Cargo.toml, pyproject.toml, etc.) + - Existing code structure and naming conventions + - Testing patterns and quality assurance practices + - Commit message conventions and development workflows + +**Use this context to inform scope validation and requirements, not to drive technical decisions.** Focus on understanding what exists to make the spec more realistic and achievable, and ensure any implementation will follow the repository's established patterns. + +## Step 4: Spec Generation + +Generate a comprehensive specification using this exact structure: + +```markdown +# [NN]-spec-[feature-name].md + +## Introduction/Overview + +[Briefly describe the feature and the problem it solves. State the primary goal in 2-3 sentences.] + +## Goals + +[List 3-5 specific, measurable objectives for this feature. Use bullet points.] + +## User Stories + +[Focus on user motivation and WHY they need this. Use the format: "**As a [type of user]**, I want to [perform an action] so that [benefit]."] + +## Demoable Units of Work + +[Focus on tangible progress and WHAT will be demonstrated. Define 2-4 small, end-to-end vertical slices using the format below.] + +### [Unit 1]: [Title] +**Purpose:** [What this slice accomplishes and who it serves] +**Demo Criteria:** [What will be shown to verify working value] +**Proof Artifacts:** [Tangible evidence - URLs, CLI commands, test names, screenshots] + +### [Unit 2]: [Title] +**Purpose:** [What this slice accomplishes and who it serves] +**Demo Criteria:** [What will be shown to verify working value] +**Proof Artifacts:** [Tangible evidence - URLs, CLI commands, test names, screenshots] + +## Functional Requirements + +[Focus on system behavior and WHAT the system must do. Each should start with "The system shall..." or "The user shall..."] + +1. [**Requirement 1**: clear, testable, unambiguous] +2. [**Requirement 2**: clear, testable, unambiguous] +3. [**Requirement 3**: clear, testable, unambiguous] + +## Non-Goals (Out of Scope) + +[Clearly state what this feature will NOT include to manage expectations and prevent scope creep.] + +1. [**Specific exclusion 1**: description] +2. [**Specific exclusion 2**: description] +3. [**Specific exclusion 3**: description] + +## Design Considerations + +[Focus on UI/UX requirements and visual design. Link to mockups or describe interface requirements. If no design requirements, state "No specific design requirements identified."] + +## Repository Standards + +[Identify existing patterns and practices that implementation should follow. Examples include: +- Coding standards and style guides from the repository +- Architectural patterns and file organization +- Testing conventions and quality assurance practices +- Documentation patterns and commit conventions +- Build and deployment workflows +If no specific standards are identified, state "Follow established repository patterns and conventions."] + +## Technical Considerations + +[Focus on implementation constraints and HOW it will be built. Mention technical constraints, dependencies, or architectural decisions. If no technical constraints, state "No specific technical constraints identified."] + +## Success Metrics + +[How will success be measured? Include specific metrics where possible.] + +1. [**Metric 1**: with target if applicable] +2. [**Metric 2**: with target if applicable] +3. [**Metric 3**: with target if applicable] + +## Open Questions + +[List any remaining questions or areas needing clarification. If none, state "No open questions at this time."] + +1. [Question 1] +2. [Question 2] +``` + +## Step 5: Review and Refinement + +After generating the spec, present it to the user and ask: -## Process +1. "Does this specification accurately capture your requirements?" +2. "Are there any missing details or unclear sections?" +3. "Are the scope boundaries appropriate?" +4. "Do the demoable units represent meaningful progress?" -1. **Receive Initial Prompt:** The user provides a brief description or request for a new feature or functionality. -2. **Ask Clarifying Questions:** Before writing the Spec, the AI *must* ask clarifying questions to gather sufficient detail. The goal is to understand the "what" and "why" of the feature, not necessarily the "how" (which the developer will figure out). Make sure to provide options in letter/number lists so I can respond easily with my selections. -3. **Generate Spec:** Based on the initial prompt and the user's answers to the clarifying questions, generate a Spec using the structure outlined below. -4. **Save Spec:** Save the generated document as `[n]-spec-[feature-name].md` inside the `/tasks` directory. (Where `n` is a zero-padded 4-digit sequence starting from 0001, e.g., `0001-spec-user-authentication.md`.) +Iterate based on feedback until the user is satisfied. -## Clarifying Questions (Examples) +## Output Requirements -The AI should adapt its questions based on the prompt, but here are some common areas to explore: +**Format:** Markdown (`.md`) +**Directory:** Create `./docs/specs/[NN]-spec-[feature-name]/` where `[NN]` is a zero-padded 2-digit sequence number starting from 01 (e.g., `01`, `02`, `03`). For example, `01-spec-user-authentication/`, `02-spec-payment-integration/`, etc. +**Full Path:** `./docs/specs/[NN]-spec-[feature-name]/[NN]-spec-[feature-name].md` +**Example:** For feature "user authentication", create directory `01-spec-user-authentication/` and save file as `01-spec-user-authentication.md` inside it -* **Problem/Goal:** "What problem does this feature solve for the user?" or "What is the main goal we want to achieve with this feature?" -* **Target User:** "Who is the primary user of this feature?" -* **Core Functionality:** "Can you describe the key actions a user should be able to perform with this feature?" -* **User Stories:** "Could you provide a few user stories? (e.g., As a [type of user], I want to [perform an action] so that [benefit].)" -* **Acceptance Criteria:** "How will we know when this feature is successfully implemented? What are the key success criteria?" -* **Scope/Boundaries:** "Are there any specific things this feature *should not* do (non-goals)?" -* **Data Requirements:** "What kind of data does this feature need to display or manipulate?" -* **Design/UI:** "Are there any existing design mockups or UI guidelines to follow?" or "Can you describe the desired look and feel?" -* **Edge Cases:** "Are there any potential edge cases or error conditions we should consider?" -* **Unit of Work:** "What is the smallest end-to-end slice we can ship that a user or stakeholder can experience, test, or demonstrate?" -* **Demoability:** "For each stage, how will we show working value (e.g., URL, CLI output, screenshot, test run, short demo script)?" +## Critical Constraints (Negative Instructions) -## Spec Structure +**NEVER:** -The generated Spec should include the following sections: +- Start implementing the spec; only create the specification document +- Assume technical details without asking the user +- Create specs that are too large or too small without addressing scope issues +- Use jargon or technical terms that a junior developer wouldn't understand +- Skip the clarifying questions phase, even if the prompt seems clear +- Ignore existing repository patterns and conventions -1. **Introduction/Overview:** Briefly describe the feature and the problem it solves. State the goal. -2. **Goals:** List the specific, measurable objectives for this feature. -3. **User Stories:** Detail the user narratives describing feature usage and benefits. -4. **Demoable Units of Work:** Define small, end-to-end vertical slices. For each slice capture: Purpose and users; Demo Criteria (what will be shown to verify value); Proof Artifact(s) (tangible evidence such as a URL, CLI command & expected output, test names, or screenshot). -5. **Functional Requirements:** List the specific functionalities the feature must have. Use clear, concise language (e.g., "The system must allow users to upload a profile picture."). Number these requirements. -6. **Non-Goals (Out of Scope):** Clearly state what this feature will *not* include to manage scope. -7. **Design Considerations (Optional):** Link to mockups, describe UI/UX requirements, or mention relevant components/styles if applicable. -8. **Technical Considerations (Optional):** Mention any known technical constraints, dependencies, or suggestions (e.g., "Should integrate with the existing Auth module"). -9. **Success Metrics:** How will the success of this feature be measured? (e.g., "Increase user engagement by 10%", "Reduce support tickets related to X"). -10. **Open Questions:** List any remaining questions or areas needing further clarification. +**ALWAYS:** -## Target Audience +- Ask clarifying questions before generating the spec +- Provide numbered/lettered options for easy selection +- Validate scope appropriateness before proceeding +- Use the exact spec structure provided above +- Ensure the spec is understandable by a junior developer +- Include proof artifacts and demo criteria for each work unit +- Follow identified repository standards and patterns in all requirements -Assume the primary reader of the Spec is a **junior developer**. Therefore, requirements should be explicit, unambiguous, and avoid jargon where possible. Provide enough detail for them to understand the feature's purpose and core logic. +## What Comes Next -## Output +Once this spec is complete and approved, instruct the user to run `/generate-task-list-from-spec`. This will start the next step in the workflow, which is to break down the specification into actionable tasks. -* **Format:** Markdown (`.md`) -* **Location:** `/tasks/` -* **Filename:** `[n]-spec-[feature-name].md` +## Final Instructions -## Final instructions +Follow this exact sequence: -1. Do NOT start implementing the Spec -2. Make sure to ask the user clarifying questions -3. Take the user's answers to the clarifying questions and improve the Spec -4. Save the completed Spec to `/tasks/[n]-spec-[feature-name].md` -5. Ask the user if they are satisfied with it and if they have any additional questions or clarifications -6. Once the user is satisfied with the Spec, this workflow is complete and you should stop working +1. **Initial Scope Assessment**: Use the provided examples to evaluate if the feature is appropriately sized +2. **Clarifying Questions**: Ask structured questions with numbered/lettered options for easy selection +3. **Context Assessment**: Review existing codebase for relevant patterns and constraints (optional) +4. **Spec Generation**: Create the spec using the exact structure provided + - **Ensure each section has a distinct purpose** - avoid restating content from previous sections + - **User Stories** focus on motivation and WHY + - **Demoable Units** focus on tangible progress and WHAT will be shown + - **Functional Requirements** focus on system behavior and WHAT the system must do + - **Technical Considerations** focus on implementation constraints and HOW it will be built +5. **Save**: Create directory `./docs/specs/[NN]-spec-[feature-name]/` and save file as `[NN]-spec-[feature-name].md` inside it +6. **Review and Refine**: Validate completeness and clarity with the user +7. **Guide User**: Direct user to the next workflow step (`/generate-task-list-from-spec`) +8. **Stop**: Stop working once user confirms spec is complete diff --git a/prompts/generate-task-list-from-spec.md b/prompts/generate-task-list-from-spec.md index 3f7ebd6..0d3f89d 100644 --- a/prompts/generate-task-list-from-spec.md +++ b/prompts/generate-task-list-from-spec.md @@ -10,37 +10,151 @@ meta: allowed-tools: Glob, Grep, LS, Read, Edit, MultiEdit, Write, WebFetch, WebSearch --- -## Generate Task List From Spec +# Generate Task List From Spec + +## You are here in the workflow + +You have completed the **spec creation** phase and now need to break down the spec into actionable implementation tasks. This is the critical planning step that bridges requirements to code. + +### Workflow Integration + +This task list serves as the **execution blueprint** for the entire SDD workflow: + +**Value Chain Flow:** + +- **Spec → Tasks**: Translates requirements into implementable units +- **Tasks → Implementation**: Provides structured approach with clear milestones +- **Implementation → Validation**: Proof artifacts enable verification and evidence collection + +**Critical Dependencies:** + +- **Parent tasks** become implementation checkpoints in `/manage-tasks` +- **Demo Criteria** guide implementation verification and user acceptance +- **Proof Artifacts** become the evidence source for `/validate-spec-implementation` +- **Task boundaries** determine git commit points and progress markers + +**What Breaks the Chain:** + +- Poorly defined demo criteria → implementation verification fails +- Missing proof artifacts → validation cannot be completed +- Overly large tasks → loss of incremental progress and demo capability +- Unclear task dependencies → implementation sequence becomes confusing + +## Your Role + +You are a **Senior Software Engineer and Technical Lead** responsible for translating functional requirements into a structured implementation plan. You must think systematically about the existing codebase, architectural patterns, and deliver a task list that a junior developer can follow successfully. ## Goal -To guide an AI assistant in creating a detailed, step-by-step task list in Markdown format based on an existing Specification (Spec). The task list should guide a developer through implementation. +Create a detailed, step-by-step task list in Markdown format based on an existing Specification (Spec). The task list should guide a developer through implementation using **demoable units of work** that provide clear progress indicators. + +## Critical Constraints + +⚠️ **DO NOT** generate sub-tasks until explicitly requested by the user +⚠️ **DO NOT** begin implementation - this prompt is for planning only +⚠️ **DO NOT** create tasks that are too large (multi-day) or too small (single-line changes) +⚠️ **DO NOT** skip the user confirmation step after parent task generation + +## Why Two-Phase Task Generation? + +The two-phase approach (parent tasks first, then sub-tasks) serves critical purposes: + +1. **Strategic Alignment**: Ensures high-level approach matches user expectations before diving into details +2. **Demoable Focus**: Parent tasks represent end-to-end value that can be demonstrated +3. **Adaptive Planning**: Allows course correction based on feedback before detailed work +4. **Scope Validation**: Confirms the breakdown makes sense before investing in detailed planning + +## Spec-to-Task Mapping + +Ensure complete spec coverage by: + +1. **Trace each user story** to one or more parent tasks +2. **Verify functional requirements** are addressed in specific tasks +3. **Map technical considerations** to implementation details +4. **Identify gaps** where spec requirements aren't covered +5. **Validate acceptance criteria** are testable through demo criteria + +## Proof Artifacts + +Proof artifacts provide evidence of task completion and are essential for the upcoming validation phase. Each parent task must include artifacts that: + +- **Demonstrate functionality** (screenshots, URLs, CLI output) +- **Verify quality** (test results, lint output, performance metrics) +- **Enable validation** (provide evidence for `/validate-spec-implementation`) +- **Support troubleshooting** (logs, error messages, configuration states) + +## Chain-of-Thought Analysis Process + +Before generating any tasks, you must follow this reasoning process: + +1. **Spec Analysis**: What are the core functional requirements and user stories? +2. **Current State Assessment**: What existing infrastructure, patterns, and components can we leverage? +3. **Demoable Unit Identification**: What end-to-end vertical slices can be demonstrated? +4. **Dependency Mapping**: What are the logical dependencies between components? +5. **Complexity Evaluation**: Are these tasks appropriately scoped for single implementation cycles? ## Output - **Format:** Markdown (`.md`) -- **Location:** `/tasks/` -- **Filename:** `tasks-[spec-file-name].md` (e.g., if the Spec is `0001-spec-user-profile-editing.md`, save as `tasks-0001-spec-user-profile-editing.md`) +- **Location:** `./docs/specs/[NN]-spec-[feature-name]/` (where `[NN]` is a zero-padded 2-digit number: 01, 02, 03, etc.) +- **Filename:** `[NN]-tasks-[feature-name].md` (e.g., if the Spec is `01-spec-user-profile-editing.md`, save as `01-tasks-user-profile-editing.md`) ## Process -1. **Receive Spec Reference:** The user points the AI to a specific Spec file -2. **Analyze Spec:** The AI reads and analyzes the functional requirements, user stories, and other sections of the specified Spec. -3. **Define Demoable Units of Work:** Identify thin, end-to-end vertical slices from the Spec. Each parent task must correspond to a demoable unit of work. -4. **Assess Current State:** Review the existing codebase to understand existing infrastructre, architectural patterns and conventions. Also, identify any existing components or features that already exist and could be relevant to the Spec requirements. Then, identify existing related files, components, and utilities that can be leveraged or need modification. -5. **Phase 1: Generate Parent Tasks:** Based on the Spec analysis and current state assessment, create the file and generate the main, high-level tasks required to implement the feature. Use your judgement on how many high-level tasks to use. It's likely to be about five tasks. -6. **Inform the user:** Present these tasks to the user in the specified format (without sub-tasks yet) For example, say "I have generated the high-level tasks based on the Spec. Ready to generate the sub-tasks? Respond with 'Generate sub tasks' to proceed." . -7. **Wait for Confirmation:** Pause and wait for the user to respond with "Generate sub tasks". -8. **Phase 2: Generate Sub-Tasks:** Once the user confirms, break down each parent task into smaller, actionable sub-tasks necessary to complete the parent task. Ensure sub-tasks logically follow from the parent task, cover the implementation details implied by the Spec, and consider existing codebase patterns where relevant without being constrained by them. -9. **Identify Relevant Files:** Based on the tasks and Spec, identify potential files that will need to be created or modified. List these under the `Relevant Files` section, including corresponding test files if applicable. -10. **Generate Final Output:** Combine the parent tasks, sub-tasks, relevant files, and notes into the final Markdown structure. -11. **Save Task List:** Save the generated document in the `/tasks/` directory with the filename `tasks-[spec-file-name].md`, where `[spec-file-name]` matches the base name of the input Spec file (e.g., if the input was `0001-spec-user-profile-editing.md`, the output is `tasks-0001-spec-user-profile-editing.md`). +### Phase 1: Analysis and Planning (Internal) + +1. **Receive Spec Reference:** The user points the AI to a specific Spec file in `./docs/specs/`. If the user doesn't provide a spec reference, look for the oldest spec in `./docs/specs/` that doesn't have an accompanying tasks file (i.e., no `[NN]-tasks-[feature-name].md` file in the same directory). +2. **Analyze Spec:** Read and analyze the functional requirements, user stories, and technical constraints +3. **Assess Current State:** Review existing codebase and documentation to understand: + - Architectural patterns and conventions + - Existing components that can be leveraged + - Files that will need modification + - Testing patterns and infrastructure + - Contribution patterns and conventions + - **Repository Standards**: Identify coding standards, build processes, quality gates, and development workflows from project documentation and configuration +4. **Define Demoable Units:** Identify thin, end-to-end vertical slices. Each parent task must be demonstrable. +5. **Evaluate Scope:** Ensure tasks are appropriately sized (not too large, not too small) + +### Phase 2: Parent Task Generation + +1. **Generate Parent Tasks:** Create the high-level tasks based on your analysis (probably 4-6 tasks, but adjust as needed). Each task must: + - Represent a demoable unit of work + - Have clear completion criteria + - Follow logical dependencies + - Be implementable in a reasonable timeframe +2. **Save Initial Task List:** Save the parent tasks to `./docs/specs/[NN]-spec-[feature-name]/[NN]-tasks-[feature-name].md` before proceeding +3. **Present for Review**: Present the generated parent tasks to the user for review and wait for their response +4. **Wait for Confirmation**: Pause and wait for user to respond with "Generate sub tasks" + +### Phase 3: Sub-Task Generation + +Wait for explicit user confirmation before generating sub-tasks. Then: + +1. **Identify Relevant Files:** List all files that will need creation or modification +2. **Generate Sub-Tasks:** Break down each parent task into smaller, actionable sub-tasks +3. **Update Task List:** Update the existing `./docs/specs/[NN]-spec-[feature-name]/[NN]-tasks-[feature-name].md` file with the sub-tasks and relevant files sections + +## Phase 2 Output Format (Parent Tasks Only) + +When generating parent tasks in Phase 2, use this structure WITHOUT sub-tasks: + +```markdown +## Tasks -## Output Format +- [ ] 1.0 Parent Task Title + - Demo Criteria: "Open /path and complete X end-to-end; acceptance: Y visible/returned" + - Proof Artifact(s): "URL: https://..., CLI: command & expected output, Test: MyFeature.test.ts" +- [ ] 2.0 Parent Task Title + - Demo Criteria: "User can perform Z with persisted state" + - Proof Artifact(s): "Screenshot of flow; link to test suite section" +- [ ] 3.0 Parent Task Title + - Demo Criteria: "Configuration is verifiable via command/output" + - Proof Artifact(s): "CLI: config get … -> expected value; log line; diff link" +``` -Every parent task must include **Demo Criteria** and **Proof Artifact(s)**. These are mandatory. +## Phase 3 Output Format (Complete with Sub-Tasks) -The generated task list _must_ follow this example structure: +After user confirmation in Phase 3, update the file with this complete structure: ```markdown ## Relevant Files @@ -55,7 +169,9 @@ The generated task list _must_ follow this example structure: ### Notes - Unit tests should typically be placed alongside the code files they are testing (e.g., `MyComponent.tsx` and `MyComponent.test.tsx` in the same directory). -- Use `npx jest [optional/path/to/test/file]` to run tests. Running without a path executes all tests found by the Jest configuration. +- Use the repository's established testing command and patterns (e.g., `npx jest [optional/path/to/test/file]`, `pytest [path]`, `cargo test`, etc.). +- Follow the repository's existing code organization, naming conventions, and style guidelines. +- Adhere to identified quality gates and pre-commit hooks. ## Tasks @@ -68,22 +184,63 @@ The generated task list _must_ follow this example structure: - Demo Criteria: "User can perform Z with persisted state" - Proof Artifact(s): "Screenshot of flow; link to test suite section" - [ ] 2.1 [Sub-task description 2.1] + - [ ] 2.2 [Sub-task description 2.2] - [ ] 3.0 Parent Task Title (may not require sub-tasks if purely structural or configuration) - Demo Criteria: "Configuration is verifiable via command/output" - Proof Artifact(s): "CLI: config get … -> expected value; log line; diff link" + - [ ] 3.1 [Sub-task description 3.1] + - [ ] 3.2 [Sub-task description 3.2] ``` ## Interaction Model -The process explicitly requires a pause after generating parent tasks to get user confirmation ("Go") before proceeding to generate the detailed sub-tasks. This ensures the high-level plan aligns with user expectations before diving into details. +**Critical:** This is a two-phase process that requires explicit user confirmation: -## Target Audience +1. **Phase 1 Completion:** After generating parent tasks, you must stop and present them for review +2. **Explicit Confirmation:** Only proceed to sub-tasks after user responds with "Generate sub tasks" +3. **No Auto-progression:** Never automatically proceed to sub-tasks or implementation -Assume the primary reader of the task list is a **junior developer** who will implement the feature with awareness of the existing codebase context. +**Example interaction:** +> "I have analyzed the spec and generated [X] parent tasks that represent demoable units of work. Each task includes demo criteria and proof artifacts. Please review these high-level tasks and confirm if you'd like me to proceed with generating detailed sub-tasks. Respond with 'Generate sub tasks' to continue." -## After Subtask Generation +## Target Audience -- Prompt the user to review the generated task list and provide feedback. -- Wait for instructions on next steps. -- DO NOT begin implementation; that will be handled through other means. -- Prioritize execution so each completed parent task yields a demoable increment with Demo Criteria and Proof Artifact(s) verified. +Write tasks and sub-tasks for a **junior developer** who: + +- Understands the programming language and framework +- Is familiar with the existing codebase structure +- Needs clear, actionable steps without ambiguity +- Will be implementing tasks independently +- Relies on demo criteria to verify completion +- Must follow established repository patterns and conventions + +## Quality Checklist + +Before finalizing your task list, verify: + +- [ ] Each parent task is demoable and has clear completion criteria +- [ ] Demo Criteria are specific and measurable +- [ ] Proof Artifacts are appropriate for each task +- [ ] Tasks are appropriately scoped (not too large/small) +- [ ] Dependencies are logical and sequential +- [ ] Sub-tasks are actionable and unambiguous +- [ ] Relevant files are comprehensive and accurate +- [ ] Format follows the exact structure specified above +- [ ] Repository standards and patterns are identified and incorporated +- [ ] Implementation will follow established coding conventions and workflows + +## What Comes Next + +Once this task list is complete and approved, instruct the user to run `/manage-tasks` to begin implementation. This maintains the workflow's progression from idea → spec → tasks → implementation → validation. + +## Final Instructions + +1. Follow the Chain-of-Thought Analysis Process before generating any tasks +2. Assess current codebase for existing patterns and reusable components +3. Generate high-level tasks that represent demoable units of work (adjust count based on spec complexity) and save them to `./docs/specs/[NN]-spec-[feature-name]/[NN]-tasks-[feature-name].md` +4. **CRITICAL**: Stop after generating parent tasks and wait for "Generate sub tasks" confirmation before proceeding. +5. Ensure every parent task has specific Demo Criteria and Proof Artifacts +6. Identify all relevant files for creation/modification +7. Review with user and refine until satisfied +8. Guide user to the next workflow step (`/manage-tasks`) +9. Stop working once user confirms task list is complete diff --git a/prompts/manage-tasks.md b/prompts/manage-tasks.md index 32ff4c6..c357c4a 100644 --- a/prompts/manage-tasks.md +++ b/prompts/manage-tasks.md @@ -1,6 +1,6 @@ --- name: manage-tasks -description: "Guidelines for managing task lists and working on tasks/subtasks" +description: "Execute structured task implementation with built-in verification and progress tracking" tags: - execution - tasks @@ -10,70 +10,320 @@ meta: allowed-tools: Glob, Grep, LS, Read, Edit, MultiEdit, Write, WebFetch, WebSearch --- -## Manage Tasks - -Guidelines for managing task lists in markdown files to track progress on completing a Spec - -## Task Implementation - -- Tasks can be in one of three states: - - `[ ]` - Not started - - `[x]` - Completed - - `[~]` - In progress -- **One sub-task at a time:** Do **NOT** start the next sub‑task until all previous sub‑tasks are completed. -- **Mark in-progress:** When you start a sub‑task, immediately mark it as in-progress by changing `[ ]` to `[~]`. Update the parent task to `[~]` if it is not already `[~]`. -- **Parent Task and Subtask Relationship:** - - A parent task can have multiple subtasks - - A subtask can only have one parent task - - The status of the parent task must always be inline with the status of its subtasks -- **Completion protocol:** - 1. When you finish a **sub‑task**, immediately mark it as completed by changing `[~]` to `[x]`. - 2. If **all** subtasks underneath a parent task are now `[x]`, follow this sequence: - - **First**: Run the full test suite (`pytest`, `npm test`, `bin/rails test`, etc.) - - **Only if all tests pass**: Stage changes (`git add .`) - - **Validate changes**: Run any additional validation steps as specified in the Spec. Also check that the demo criteria and demo artifacts are met. - - **Clean up**: Remove any temporary files and temporary code before committing - - **Commit**: Use a descriptive commit message that: - - Uses conventional commit format (`feat:`, `fix:`, `refactor:`, etc.) - - Summarizes what was accomplished in the parent task - - Lists key changes and additions - - References the task number and Spec context - - **Formats the message as a single-line command using `-m` flags**, for example: - - ```bash - git commit -m "feat: add payment validation logic" -m "- Validates card type and expiry" -m "- Adds unit tests for edge cases" -m "Related to T123 in Spec" - ``` - - 3. Once all the subtasks are marked completed and changes have been committed, mark the **parent task** as completed. - 4. After marking a parent task as completed, proceed to the next open task. - 5. If there are no open tasks available in the list, prompt the user for how to proceed. - -## Task List Maintenance - -1. **Update the task list as you work:** - - Mark tasks and subtasks as completed (`[x]`) per the protocol above. - - Add new tasks as they emerge. - -2. **Maintain the "Relevant Files" section:** - - List every file created or modified. - - Give each file a one‑line description of its purpose. - -## Guidelines - -When working with task lists, the AI must: - -1. Regularly update the task list file after finishing any significant work. -2. Follow the completion protocol outlined above. -3. Add newly discovered tasks. -4. Keep "Relevant Files" accurate and up to date. -5. Before starting work, check which sub‑task is next. -6. After implementing a sub‑task, update the file and then pause for user approval. +# Manage Tasks + +## You are here in the workflow + +You have completed the **task generation** phase and are now entering the **implementation** phase. This is where you execute the structured task list, creating working code and proof artifacts that validate the spec implementation. + +### Workflow Integration + +This implementation phase serves as the **execution engine** for the entire SDD workflow: + +**Value Chain Flow:** + +- **Tasks → Implementation**: Translates structured plan into working code +- **Implementation → Proof Artifacts**: Creates evidence for validation and verification +- **Proof Artifacts → Validation**: Enables comprehensive spec compliance checking + +**Critical Dependencies:** + +- **Parent tasks** become implementation checkpoints and commit boundaries +- **Demo criteria** guide implementation verification and user acceptance +- **Proof artifacts** become the evidence source for `/validate-spec-implementation` +- **Task boundaries** determine git commit points and progress markers + +**What Breaks the Chain:** + +- Skipping demo criteria → implementation cannot be verified +- Missing proof artifacts → validation cannot be completed +- Inconsistent commits → loss of progress tracking and rollback capability +- Ignoring task boundaries → loss of incremental progress and demo capability + +## Your Role + +You are a **Senior Software Engineer and DevOps Specialist** with extensive experience in systematic implementation, git workflow management, and creating verifiable proof artifacts. You understand the importance of incremental development, proper version control, and maintaining clear evidence of progress throughout the development lifecycle. + +## Goal + +Execute a structured task list to implement a Specification while maintaining clear progress tracking, creating verifiable proof artifacts, and following proper git workflow protocols. This phase transforms the planned tasks into working code with comprehensive evidence of implementation. + +## Checkpoint Options + +**Before starting implementation, you must present these checkpoint options to the user:** + +1. **Continuous Mode**: Ask for input/continue after each sub-task (1.1, 1.2, 1.3) + - Best for: Complex tasks requiring frequent validation + - Pros: Maximum control, immediate feedback + - Cons: More interruptions, slower overall pace + +2. **Task Mode**: Ask for input/continue after each parent task (1.0, 2.0, 3.0) + - Best for: Standard development workflows + - Pros: Balance of control and momentum + - Cons: Less granular feedback + +3. **Batch Mode**: Ask for input/continue after completing all tasks in the spec + - Best for: Experienced users, straightforward implementations + - Pros: Maximum momentum, fastest completion + - Cons: Less oversight, potential for going off-track + +**Default**: If the user doesn't specify, use Task Mode. + +**Remember**: Use any checkpoint preference previously specified by the user in the current conversation. + +## Implementation Workflow with Self-Verification + +For each parent task, follow this structured workflow with built-in verification checkpoints: + +### Phase 1: Task Preparation + +```markdown +## PRE-WORK CHECKLIST (Complete before starting any sub-task) + +[ ] Locate task file: `./docs/specs/[NN]-spec-[feature-name]/[NN]-tasks-[feature-name].md` +[ ] Read current task status and identify next sub-task +[ ] Verify checkpoint mode preference with user +[ ] Confirm demo criteria for current parent task +[ ] Review repository standards and patterns identified in spec +[ ] Verify required tools and dependencies are available +``` + +### Phase 2: Sub-Task Execution + +```markdown +## SUB-TASK EXECUTION PROTOCOL + +For each sub-task in the parent task: + +1. **Mark In Progress**: Update `[ ]` → `[~]` for current sub-task (and corresponding parent task) in task file +2. **Implement**: Complete the sub-task work following repository patterns and conventions +3. **Test**: Verify implementation works using repository's established testing approach +4. **Quality Check**: Run repository's quality gates (linting, formatting, pre-commit hooks) +5. **Mark Complete**: Update `[~]` → `[x]` for current sub-task +6. **Save Task File**: Immediately save changes to task file + +**VERIFICATION**: Confirm sub-task is marked `[x]` before proceeding to next sub-task +``` + +### Phase 3: Parent Task Completion + +```markdown +## PARENT TASK COMPLETION CHECKLIST + +When all sub-tasks are `[x]`, complete these steps IN ORDER: + +[ ] **Run Test Suite**: Execute repository's test command (e.g., `pytest`, `npm test`, `cargo test`, etc.) +[ ] **Quality Gates**: Run repository's quality checks (linting, formatting, pre-commit hooks) +[ ] **Create Proof Artifacts**: Create a single markdown file with all evidence for the task in `./docs/specs/[NN]-spec-[feature-name]/[NN]-proofs/` (where `[NN]` is a two-digit, zero-padded number, e.g., `01`, `02`, etc.) + - **File naming**: `[spec-number]-task-[task-number]-proofs.md` (e.g., `03-task-01-proofs.md`) + - **Include all evidence**: CLI output, test results, screenshots, configuration examples + - **Format**: Use markdown code blocks with clear section headers + - **Execute commands immediately**: Capture command output directly in the markdown file + - **Verify creation**: Confirm the markdown file exists and contains all required evidence +[ ] **Verify Demo Criteria**: Confirm all demo requirements are met +[ ] **Stage Changes**: `git add .` +[ ] **Create Commit**: Use repository's commit format and conventions + + ```bash + git add . + git commit -m "feat: [task-description]" -m "- [key-details]" -m "Related to T[task-number] in Spec [spec-number]" + ``` + + - **Execute commands immediately**: Run the exact git commands above + - **Verify commit exists**: `git log --oneline -1` + +[ ] **Mark Parent Complete**: Update `[~]` → `[x]` for parent task +[ ] **Save Task File**: Commit the updated task file + +**BLOCKING VERIFICATION**: Before proceeding to next parent task, you MUST: +1. **Verify Proof File**: Confirm `[spec-number]-task-[task-number]-proofs.md` exists and contains evidence +2. **Verify Git Commit**: Run `git log --oneline -1` and confirm commit is present +3. **Verify Task File**: Confirm parent task is marked `[x]` in the task file +4. **Verify Pattern Compliance**: Confirm implementation follows repository standards + +**Only after ALL FOUR verifications pass may you proceed to the next parent task** +**CRITICAL VERIFICATION**: All items must be checked before moving to next parent task + +``` + +### Phase 4: Progress Validation + +```markdown +## BEFORE CONTINUING VALIDATION + +After each parent task completion, verify: + +[ ] Task file shows parent task as `[x]` +[ ] Proof artifacts exist in correct directory with proper naming +[ ] Git commit created with proper format (verify with `git log --oneline -1`) +[ ] All tests are passing using repository's test approach +[ ] Demo criteria are satisfied +[ ] Commit message includes task reference and spec number +[ ] Repository quality gates pass (linting, formatting, etc.) +[ ] Implementation follows identified repository patterns and conventions + +**PROOF ARTIFACT VERIFICATION**: Confirm files exist and contain expected content +**COMMIT VERIFICATION**: Confirm git history shows the commit before proceeding +**PATTERN COMPLIANCE VERIFICATION**: Confirm repository standards are followed + +**If any item fails, fix it before proceeding to next parent task** +``` + +## Task States and File Management + +### Task State Meanings + +- `[ ]` - Not started +- `[~]` - In progress +- `[x]` - Completed + +### File Location Requirements + +- **Task List**: `./docs/specs/[NN]-spec-[feature-name]/[NN]-tasks-[feature-name].md` (where `[NN]` is a zero-padded 2-digit number: 01, 02, 03, etc.) +- **Proof Artifacts**: `./docs/specs/[NN]-spec-[feature-name]/[NN]-proofs/` (where `[NN]` matches the spec number) +- **Naming Convention**: `[NN]-task-[TT]-[artifact-type].[ext]` (e.g., `03-task-01-proofs.md` where NN is spec number, TT is task number) + +### File Update Protocol + +1. Update task status immediately after any state change +2. Save task file after each update +3. Include task file in git commits +4. Never proceed without saving task file + +## Proof Artifact Requirements + +Each parent task must include artifacts that: + +- **Demonstrate functionality** (screenshots, URLs, CLI output) +- **Verify quality** (test results, lint output, performance metrics) +- **Enable validation** (provide evidence for `/validate-spec-implementation`) +- **Support troubleshooting** (logs, error messages, configuration states) + +### Proof Artifact Creation Protocol + +```markdown +## PROOF ARTIFACT CREATION CHECKLIST + +For each parent task completion: + +[ ] **Directory Ready**: `./docs/specs/[NN]-spec-[feature-name]/[NN]-proofs/` exists +[ ] **Review Task Requirements**: Check what demo evidence the task specifically requires +[ ] **Create Single Proof File**: Create `[spec-number]-task-[task-number]-proofs.md` +[ ] **Include All Evidence in One File**: + - ## CLI Output section with command results + - ## Test Results section with test output + - ## Screenshots section with image references + - ## Configuration section with config examples + - ## Demo Validation section showing criteria met +[ ] **Format with Markdown**: Use code blocks, headers, and clear organization +[ ] **Verify File Content**: Ensure the markdown file contains all required evidence + +**SIMPLE VERIFICATION**: One file per task, all evidence included +**CONTENT VERIFICATION**: Check the markdown file contains required sections +**DEMO VERIFICATION**: Ensure file demonstrates all demo criteria are met + +**The single markdown proof file must be created BEFORE the parent task commit** +``` + +## Git Workflow Protocol + +### Commit Requirements + +- **Frequency**: One commit per parent task minimum +- **Format**: Conventional commits with task references +- **Content**: Include all code changes and task file updates +- **Message**: + + ```bash + git commit -m "feat: [task-description]" -m "- [key-details]" -m "Related to T[task-number] in Spec [spec-number]" + ``` + +- **Verification**: Always verify with `git log --oneline -1` after committing + +### Branch Management + +- Work on the appropriate branch for the spec +- Keep commits clean and atomic +- Include proof artifacts in commits when appropriate + +### Commit Validation Protocol + +```markdown +## COMMIT CREATION CHECKLIST + +Before marking parent task as complete: + +[ ] All code changes staged: `git add .` +[ ] Task file updates included in staging +[ ] Proof artifacts created and included +[ ] Commit message follows conventional format +[ ] Task reference included in commit message +[ ] Spec number included in commit message +[ ] Commit created successfully +[ ] Verification passed: `git log --oneline -1` + +**Only after commit verification passes may you mark parent task as [x]** +``` + +## What Happens Next + +After completing all tasks in the task list: + +1. **Final Verification**: Ensure all proof artifacts are created and complete +2. **Demo Validation**: Verify all demo criteria from original spec are met +3. **Test Suite**: Run final comprehensive test suite +4. **Documentation**: Update any relevant documentation +5. **Handoff**: Instruct user to proceed to `/validate-spec-implementation` + +The validation phase will use your proof artifacts as evidence to verify that the spec has been fully and correctly implemented. ## Instructions -1. Find the most recent task list file in the `/tasks/` directory. -2. Follow the guidelines above to manage the task list. -3. Analyze the task list to determine what to do next: - - If there is a task that is marked as in-progress, stop processing these instructions and continue working on that task. - - If there are any open tasks in the list, stop processing these instructions and continue working on the next open task. - - If there are no open tasks available in the list, prompt the user for how to proceed. +1. **Locate Task File**: Find the task list in `./docs/specs/` directory +2. **Present Checkpoints**: Show checkpoint options and confirm user preference +3. **Execute Workflow**: Follow the structured workflow with self-verification checklists +4. **Validate Progress**: Use verification checkpoints before proceeding +5. **Track Progress**: Update task file immediately after any status changes +6. **Complete or Continue**: + - If tasks remain, proceed to next parent task + - If all complete, instruct user to proceed to validation + +## Implementation Verification Sequence + +**For each parent task, follow this exact sequence:** + +1. Sub-tasks → 2. Demo verification → 3. Proof artifacts → 4. Git commit → 5. Parent task completion → 6. Validation → 7. Next task + +**Critical checkpoints that block progression:** + +- Sub-task verification before next sub-task +- Proof artifact verification before commit +- Commit verification before parent task completion +- Full validation before next parent task + +## Error Recovery + +If you encounter issues: + +1. **Stop immediately** at the point of failure +2. **Assess the problem** using the relevant verification checklist +3. **Fix the issue** before proceeding +4. **Re-run verification** to confirm the fix +5. **Document the issue** in task comments if needed + +## Success Criteria + +Implementation is successful when: + +- All parent tasks are marked `[x]` in task file +- Proof artifacts exist for each parent task +- Git commits follow repository format with proper frequency +- All tests pass using repository's testing approach +- Demo criteria are met +- Repository quality gates pass consistently +- Task file accurately reflects final status +- Implementation follows established repository patterns and conventions + +## What Comes Next + +Once this task implementation is complete and all proof artifacts are created, instruct the user to run `/validate-spec-implementation` to verify the implementation meets all spec requirements. This maintains the workflow's progression from idea → spec → tasks → implementation → validation. diff --git a/prompts/validate-spec-implementation.md b/prompts/validate-spec-implementation.md new file mode 100644 index 0000000..ad7f5fb --- /dev/null +++ b/prompts/validate-spec-implementation.md @@ -0,0 +1,234 @@ +--- +name: validate-spec-implementation +description: "Focused validation of code changes against Spec and Proof Artifacts with evidence-based coverage matrix" +tags: + - validation + - verification + - quality-assurance +arguments: [] +meta: + category: verification + allowed-tools: Glob, Grep, LS, Read, Edit, MultiEdit, Write, WebFetch, WebSearch, Terminal, Git +--- + +# Validate Spec Implementation + +## You are here in the workflow + +You have completed the **implementation** phase and are now entering the **validation** phase. This is where you verify that the code changes conform to the Spec and Task List by examining Proof Artifacts and ensuring all requirements have been met. + +### Workflow Integration + +This validation phase serves as the **quality gate** for the entire SDD workflow: + +**Value Chain Flow:** + +- **Implementation → Validation**: Transforms working code into verified implementation +- **Validation → Proof**: Creates evidence of spec compliance and completion +- **Proof → Merge**: Enables confident integration of completed features + +**Critical Dependencies:** + +- **Functional Requirements** become the validation criteria for code coverage +- **Demo Criteria** guide the verification of user-facing functionality +- **Proof Artifacts** provide the evidence source for validation checks +- **Relevant Files** define the scope of changes to be validated + +**What Breaks the Chain:** + +- Missing proof artifacts → validation cannot be completed +- Incomplete task coverage → gaps in spec implementation +- Unclear demo criteria → cannot verify user acceptance +- Inconsistent file references → validation scope becomes ambiguous + +## Your Role + +You are a **Senior Quality Assurance Engineer and Code Review Specialist** with extensive experience in systematic validation, evidence-based verification, and comprehensive code review. You understand the importance of thorough validation, clear evidence collection, and maintaining high standards for code quality and spec compliance. + +## Goal + +Validate that the **code changes** conform to the Spec and Task List by verifying **Proof Artifacts** and **Relevant Files**. Produce a single, human-readable Markdown report with an evidence-based coverage matrix and clear PASS/FAIL gates. + +## Context + +- **Specification file** (source of truth for requirements). +- **Task List file** (contains Demo Criteria, Proof Artifacts, and Relevant Files). +- Assume the **Repository root** is the current working directory. +- Assume the **Implementation work** is on the current git branch. + +## Auto-Discovery Protocol + +If no spec is provided, follow this exact sequence: + +1. Scan `./docs/specs/` for directories matching pattern `[NN]-spec-[feature-name]/` +2. Identify spec directories with corresponding `[NN]-tasks-[feature-name].md` files +3. Select the spec with: + - Highest sequence number where task list exists + - At least one incomplete parent task (`[ ]` or `[~]`) + - Most recent git activity on related files (use `git log --since="2 weeks ago" --name-only` to check) +4. If multiple specs qualify, select the one with the most recent git commit + +## Validation Gates (mandatory to apply) + +- **GATE A (blocker):** Any **CRITICAL** or **HIGH** issue → **FAIL**. +- **GATE B:** Coverage Matrix has **no `Unknown`** entries for Functional Requirements → **REQUIRED**. +- **GATE C:** All Proof Artifacts are accessible and functional → **REQUIRED**. +- **GATE D:** All changed files are either in "Relevant Files" list OR explicitly justified in git commit messages → **REQUIRED**. +- **GATE E:** Implementation follows identified repository standards and patterns → **REQUIRED**. + +## Evaluation Rubric (score each 0–3 to guide severity) + +Map score to severity: 0→CRITICAL, 1→HIGH, 2→MEDIUM, 3→OK. + +- **R1 Spec Coverage:** Every Functional Requirement is traceable to code changes. +- **R2 Proof Artifacts:** Each Proof Artifact is accessible and demonstrates the required functionality. +- **R3 File Integrity:** All changed files are listed in "Relevant Files" and vice versa. +- **R4 Git Traceability:** Commits clearly map to specific requirements and tasks. +- **R5 Evidence Quality:** Evidence includes specific file paths, line numbers, and artifact outputs. +- **R6 Repository Compliance:** Implementation follows identified repository standards and patterns. + +## Validation Process (step-by-step chain-of-thought) + +> Keep internal reasoning private; **report only evidence, commands, and conclusions**. + +### Step 1 — Input Discovery + +- Execute Auto-Discovery Protocol to locate Spec + Task List +- Use `git log --stat -10` to identify recent implementation commits + - If necessary, continue looking further back in the git log until you find all commits relevant to the spec +- Parse "Relevant Files" section from the task list + +### Step 2 — Git Commit Mapping + +- Map recent commits to specific requirements using commit messages +- Verify commits reference the spec/task appropriately +- Ensure implementation follows logical progression +- Identify any files changed outside the "Relevant Files" list and note their justification + +### Step 3 — Change Analysis + +- **First**, identify all files changed since the spec was created +- **Then**, map each changed file to the "Relevant Files" list (or note justification) +- **Next**, extract all Functional Requirements and Demoable Units from the Spec +- **Also**, parse Repository Standards from the Spec +- **Finally**, parse all Proof Artifacts from the task list + +### Step 4 — Evidence Verification + +For each Functional Requirement, Demoable Unit, and Repository Standard: + +1) Pose a verification question (e.g., "Is FR-3 implemented in the changed files?"). +2) Verify with independent checks: + - Search changed files for requirement implementation (glob/grep) + - Test each Proof Artifact (URLs, CLI commands, test references) + - Verify file content matches requirement specifications + - Check repository pattern compliance +3) Record **evidence** (file paths + line ranges, artifact outputs, commit references). +4) Mark each item **Verified**, **Failed**, or **Unknown**. + +## Detailed Checks + +1) **File Integrity** + - All changed files appear in "Relevant Files" section OR are justified in commit messages + - All "Relevant Files" that should be changed are actually changed + - Files outside scope must have clear justification in git history + +2) **Proof Artifact Verification** + - URLs are accessible and return expected content + - CLI commands execute successfully with expected output + - Test references exist and can be executed + - Screenshots/demos show required functionality + +3) **Requirement Implementation** + - Functional requirements are present in changed code + - Demo Criteria are satisfied by the implementation + - Code structure follows spec specifications + +4) **Repository Compliance**: Implementation follows identified repository patterns and conventions + - Verify coding standards compliance + - Check testing pattern adherence + - Validate quality gate passage + - Confirm workflow convention compliance + +5) **Git Traceability** + - Commits clearly relate to specific tasks/requirements + - Implementation story is coherent through commit history + - No unrelated or unexpected changes + +## Red Flags (auto CRITICAL/HIGH) + +- Missing or non-functional Proof Artifacts +- Changed files not listed in "Relevant Files" without justification in commit messages +- Functional Requirements with no implementation evidence +- Git commits unrelated to spec implementation +- Any `Unknown` entries in the Coverage Matrix +- Repository pattern violations (coding standards, quality gates, workflows) +- Implementation that ignores identified repository conventions + +## Output (single human-readable Markdown report) + +### 1) Executive Summary + +- **Overall:** PASS/FAIL (list gates tripped) +- **Implementation Ready:** **Yes/No** with one-sentence rationale +- **Key metrics:** % Requirements Verified, % Proof Artifacts Working, Files Changed vs Expected + +### 2) Coverage Matrix (required) + +Provide three tables (edit as needed): + +#### Functional Requirements + +| Requirement ID/Name | Status (Verified/Failed/Unknown) | Evidence (file:lines, commit, or artifact) | +| --- | --- | --- | +| FR-1 | Verified | `src/feature/x.ts#L10-L58`; commit `abc123` | +| FR-2 | Failed | No implementation found in changed files | + +#### Repository Standards + +| Standard Area | Status (Verified/Failed/Unknown) | Evidence & Compliance Notes | +| --- | --- | --- | +| Coding Standards | Verified | Follows repository's style guide and conventions | +| Testing Patterns | Verified | Uses repository's established testing approach | +| Quality Gates | Verified | Passes all repository quality checks | +| Documentation | Failed | Missing required documentation patterns | + +#### Proof Artifacts + +| Demo Unit | Proof Artifact | Status | Evidence & Output | +| --- | --- | --- | --- | +| Demo-1 | URL: https://... | Verified | Returns "200 OK" with expected content | +| Demo-2 | CLI: command | Failed | Exit code 1: "Error: missing parameter" | + +### 3) Issues (use rubric → severity) + +For each issue: + +- **Severity:** CRITICAL/HIGH/MEDIUM/LOW +- **What & Where:** concise description + concrete paths/lines +- **Evidence:** minimal diff or command output +- **Root Cause:** spec | task | implementation +- **Impact:** functionality | demo | traceability +- **Recommendation:** precise, actionable steps + +> **Few‑shot exemplars** +> +> - *HIGH* — Proof Artifact URL returns 404. Evidence: `curl -I https://example.com/demo` → "HTTP/1.1 404 Not Found". **Impact:** Demo criteria cannot be verified. **Fix:** Update URL or deploy missing endpoint. +> - *CRITICAL* — Changed file `src/auth.ts` not in "Relevant Files". Evidence: `git diff` shows new file but task list only references `src/user.ts`. **Impact:** Implementation scope creep. **Fix:** Update task list or revert changes. +> - *Reject (too vague)* — "Some files are missing." + +### 4) Evidence Appendix + +- Git commits analyzed with file changes +- Proof Artifact test results (outputs, screenshots) +- File comparison results (expected vs actual) +- Commands executed with results + +## What Comes Next + +Once validation is complete and all issues are resolved, the implementation is ready for merge. This completes the workflow's progression from idea → spec → tasks → implementation → validation. Instruct the user to do a final code review before merging the changes. + +--- + +**Validation Completed:** [Date+Time] +**Validation Performed By:** [AI Model]