From 36e9d907f749fa4108b657fcfceb25bd437e6c17 Mon Sep 17 00:00:00 2001 From: Damien Storm Date: Tue, 4 Nov 2025 14:10:41 -0500 Subject: [PATCH 01/18] feat: add validation prompt --- prompts/validate-spec-implementation.md | 177 ++++++++++++++++++++++++ 1 file changed, 177 insertions(+) create mode 100644 prompts/validate-spec-implementation.md diff --git a/prompts/validate-spec-implementation.md b/prompts/validate-spec-implementation.md new file mode 100644 index 0000000..688cf7c --- /dev/null +++ b/prompts/validate-spec-implementation.md @@ -0,0 +1,177 @@ +--- +name: validate-spec-implementation-v3 +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 (v3 — focused evidence-based) + +## 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 `./tasks/` for files matching pattern `[n]-spec-*.md` +2. Identify specs with corresponding `tasks-[n]-spec-*.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**. + +## 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. + +## 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 +- **Finally**, parse all Proof Artifacts from the task list + +### Step 4 — Evidence Verification + +For each Functional Requirement and Demoable Unit: + +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 +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) **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 + +## 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 two 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 | + +**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 + +--- + +**Validation Completed:** [Date+Time] +**Validation Performed By:** [AI Model] From 14a8bf0300532f9732fd2c1fd789c2c0512c1136 Mon Sep 17 00:00:00 2001 From: Damien Storm Date: Tue, 4 Nov 2025 16:15:47 -0500 Subject: [PATCH 02/18] docs: add comprehensive spec-driven workflow refactoring plan This commit introduces a detailed refactoring roadmap for the Spec-Driven Development Workflow that maintains simplicity while improving newcomer accessibility. Key improvements include: - Enhanced prompt clarity with workflow guidance and next steps - Scope size recommendations with concrete examples (too large/small/just right) - Centralized directory structure for specs, tasks, and proofs - Simplified numbering system (01, 02, 03 instead of 0001, 0002, 0003) - Implementation steps for migration and prompt updates - Research-based prompt engineering best practices The document consolidates previous scattered improvements into a single, actionable plan that preserves the workflow's core differentiation: simplicity. --- refactor-sdd-workflow-prompts.md | 147 +++++++++++++++++++++++++++++++ 1 file changed, 147 insertions(+) create mode 100644 refactor-sdd-workflow-prompts.md diff --git a/refactor-sdd-workflow-prompts.md b/refactor-sdd-workflow-prompts.md new file mode 100644 index 0000000..d42b12e --- /dev/null +++ b/refactor-sdd-workflow-prompts.md @@ -0,0 +1,147 @@ +# 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 + ├── tasks-01-spec-feature-name.md + └── 01-proofs/ + ├── 01-01-demo.png + ├── 01-01-cli-output.txt + ├── 01-01-test-results.json + ├── 01-02-demo.png + ├── 01-02-cli-output.txt + ├── 01-02-test-results.json +├── 02-spec-another-feature + ├── 02-spec-another-feature.md + ├── tasks-02-spec-another-feature.md + └── 02-proofs/ + ├── 02-01-demo.png + ├── 02-01-cli-output.txt + ├── 02-01-test-results.json + ├── 02-02-demo.png + ├── 02-02-cli-output.txt + ├── 02-02-test-results.json +``` + +**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 `[spec]-[task]-[artifact]` pattern (e.g., 01-01-demo.png) + +### 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. From abacecd1a513651c3175fde1642a3f59a10877a9 Mon Sep 17 00:00:00 2001 From: Damien Storm Date: Tue, 4 Nov 2025 22:20:11 -0500 Subject: [PATCH 03/18] feat: enhance generate-spec prompt with research-based improvements and workflow guidance MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit implements comprehensive enhancements to the generate-spec prompt based on extensive prompt engineering research and the spec-driven workflow refactoring plan. **Applied findings from 2025 prompt engineering best practices research: - Role-based prompting: Added Senior Product Manager and Technical Lead persona to improve domain-specific response quality and expertise alignment - Chain-of-thought reasoning: Implemented step-by-step scope assessment process to prevent premature task generation and improve decision quality - Negative constraints: Added NEVER/ALWAYS sections to prevent common failure modes and establish clear behavioral guardrails - Output format templates: Provided exact markdown structure with concrete examples to ensure consistent, actionable specification output - Progressive disclosure: Structured questioning approach that starts with core understanding and expands based on feature complexity **Enhanced newcomer accessibility without external documentation dependencies: - Added "You are here in the workflow" section providing current position and next steps guidance - Clear workflow progression: idea → spec → tasks → implementation → validation - Enhanced process overview with 5-step structured approach - Explicit "What comes next" guidance pointing to task generation command **Implemented proactive scope management to prevent inappropriate spec sizes: - Chain-of-thought reasoning for scope evaluation - Concrete examples categorizing features as too large/small/just right - Three-tiered assessment with specific actionable recommendations - Validation step after gathering user requirements **Improved clarifying questions while maintaining original flexibility: - Reduced from 18 formal questions to 9 guided questions - Thematic grouping: Core Understanding, Success & Boundaries, Design & Technical, Demo & Proof - Preserved adaptive questioning: "Adapt your questions based on user input" - Progressive disclosure guidance for intelligent question expansion **Updated to align with new directory structure and numbering system: - File location: /tasks/ → ./docs/specs/ for centralized artifact management - Numbering system: 4-digit (0001) → 2-digit (01) for improved navigation - Enhanced FR1/FR2/FR3 requirement numbering for better traceability - Integrated proof artifacts throughout the specification process **Enhanced output quality and maintainability: - Comprehensive review and refinement process with specific validation questions - Enhanced spec structure with detailed templates and examples - Improved proof artifact integration and validation criteria - Better alignment with junior developer audience needs **Achieved optimal balance between comprehensiveness and efficiency: - Original: ~1133 tokens across 75 lines - Enhanced: ~1929 tokens across 248 lines - 70% increase delivers substantial value: workflow guidance, scope validation, research-based improvements, and enhanced newcomer experience - Maintains original's elegance and flexibility while adding robust capabilities This enhancement represents a thoughtful evolution that preserves the original's core philosophy while addressing key workflow pain points and incorporating modern prompt engineering research findings. --- prompts/generate-spec.md | 255 ++++++++++++++++++++++++++++++++------- 1 file changed, 209 insertions(+), 46 deletions(-) diff --git a/prompts/generate-spec.md b/prompts/generate-spec.md index 1b93dca..edf0fc0 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,228 @@ 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. + +**What comes next:** After completing this spec, the user will move to task generation using the `/generate-task-list-from-spec` command. + +## 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 + +1. **Initial Assessment** - Evaluate the user input for scope appropriateness +2. **Clarifying Questions** - Gather detailed requirements through structured inquiry +3. **Scope Validation** - Ensure the feature is appropriately sized +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: Scope Validation + +After gathering initial responses, validate that the scope remains appropriate. If the answers revealed additional complexity, reassess whether the feature needs to be split or refined. + +## Step 4: Spec Generation + +Generate a comprehensive specification using this exact structure: + +```markdown +# [n]-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 + +[Detail 3-5 user narratives using the format: "As a [type of user], I want to [perform an action] so that [benefit]."] + +## Demoable Units of Work + +[Define 2-4 small, end-to-end vertical slices. For each slice include:] + +### [Work 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] + +### [Work 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 + +[Numbered list of specific functionalities. Each should start with "The system shall..." or "The user shall..."] + +FR1. [Requirement 1 - clear, testable, unambiguous] +FR2. [Requirement 2 - clear, testable, unambiguous] +FR3. [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.] + +- [Specific exclusion 1] +- [Specific exclusion 2] +- [Specific exclusion 3] + +## Design Considerations + +[Link to mockups, describe UI/UX requirements, or mention relevant components/styles. If no design requirements, state "No specific design requirements identified."] + +## Technical Considerations + +[Mention known technical constraints, dependencies, or suggestions. If no technical constraints, state "No specific technical constraints identified."] + +## Success Metrics + +[How will success be measured? Include specific metrics where possible.] + +- [Metric 1 with target if applicable] +- [Metric 2 with target if applicable] +- [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."] + +- [Question 1] +- [Question 2] +``` + +## Step 5: Review and Refinement -## Process +After generating the spec, present it to the user and ask: -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`.) +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?" -## Clarifying Questions (Examples) +Iterate based on feedback until the user is satisfied. -The AI should adapt its questions based on the prompt, but here are some common areas to explore: +## Output Requirements -* **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)?" +**Format:** Markdown (`.md`) +**Location:** `./docs/specs/` +**Filename:** `[n]-spec-[feature-name].md` (Where `n` is a zero-padded 2-digit sequence starting from 01, e.g., `01-spec-user-authentication.md`) -## Spec Structure +## Critical Constraints (Negative Instructions) -The generated Spec should include the following sections: +**NEVER:** -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. +- 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 -## Target Audience +**ALWAYS:** -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. +- 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 -## Output +## What Comes Next -* **Format:** Markdown (`.md`) -* **Location:** `/tasks/` -* **Filename:** `[n]-spec-[feature-name].md` +Once this spec is complete and approved, the user should run `/generate-task-list-from-spec` to break down the specification into actionable tasks. This maintains the workflow's progression from idea → spec → tasks → implementation → validation. -## Final instructions +## Final Instructions -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. Assess scope appropriateness using the provided examples +2. Ask clarifying questions with numbered/lettered options +3. Validate scope based on user responses +4. Generate spec using the exact structure provided +5. Save to `./docs/specs/[n]-spec-[feature-name].md` +6. Review with user and refine until satisfied +7. Guide user to the next workflow step (`/generate-task-list-from-spec`) +8. Stop working once user confirms spec is complete From 380308439cd721d83b7208641a18fc7fbb162aeb Mon Sep 17 00:00:00 2001 From: Damien Storm Date: Tue, 4 Nov 2025 22:45:23 -0500 Subject: [PATCH 04/18] refactor: move context assessment earlier in spec-driven workflow This commit restructures the spec-driven workflow to move context assessment from the task generation phase to the specification creation phase for better decision-making and more realistic specifications. ## Workflow Improvements **Enhanced generate-spec.md:** - Added Step 3: Context Assessment (Optional) to review existing codebase and documentation for architecture patterns, components, and constraints - Updated Process Overview from 5 to 6 steps to include context assessment - Enhanced Scope Validation to consider both user requirements AND existing codebase context for more accurate scope decisions - Updated Final Instructions to reflect the new 9-step process **Streamlined generate-task-list-from-spec.md:** - Removed redundant Step 4: Assess Current State since context is now gathered during spec creation - Reduced process from 11 to 10 steps for cleaner workflow - Updated Phase 1 to reference existing codebase context captured during spec creation process ## Benefits **Better Scope Decisions:** - Context available when making scope validation decisions - Can identify if existing infrastructure makes features easier/harder - More realistic assessment of feature complexity and feasibility **Improved Spec Quality:** - Requirements can reference existing patterns and constraints - Prevents specifying impossible or redundant functionality - Better alignment with established architecture and conventions **Cleaner Workflow Separation:** - Spec phase handles "what exists" context gathering - Task phase focuses on "how to build" implementation planning - Eliminates redundant codebase analysis across workflow phases **Enhanced Documentation Coverage:** - Context assessment includes both codebase AND existing documentation - Captures architectural decisions, API specs, and design patterns - Prevents missing important documented constraints or standards This change maintains the workflow's focus on specification while providing better context for realistic planning and implementation decisions. --- prompts/generate-spec.md | 39 ++++++++++++++++++++++++++------------- 1 file changed, 26 insertions(+), 13 deletions(-) diff --git a/prompts/generate-spec.md b/prompts/generate-spec.md index edf0fc0..dfd79e4 100644 --- a/prompts/generate-spec.md +++ b/prompts/generate-spec.md @@ -32,9 +32,10 @@ If the user did not include an initial input or reference for the spec, ask the 1. **Initial Assessment** - Evaluate the user input for scope appropriateness 2. **Clarifying Questions** - Gather detailed requirements through structured inquiry -3. **Scope Validation** - Ensure the feature is appropriately sized -4. **Spec Generation** - Create the detailed specification document -5. **Review and Refine** - Validate completeness and clarity with the user +3. **Context Assessment** - Review existing codebase for relevant patterns and constraints (optional) +4. **Scope Validation** - Ensure the feature is appropriately sized considering requirements and context +5. **Spec Generation** - Create the detailed specification document +6. **Review and Refine** - Validate completeness and clarity with the user ## Step 1: Initial Scope Assessment @@ -108,11 +109,22 @@ Adapt your questions based on the user's input. Use the following common areas t **Progressive Disclosure:** Start with Core Understanding, then expand based on feature complexity and user responses. -## Step 3: Scope Validation +## Step 3: Context Assessment (Optional) -After gathering initial responses, validate that the scope remains appropriate. If the answers revealed additional complexity, reassess whether the feature needs to be split or refined. +If the feature involves existing systems, briefly review the codebase and existing docs to understand: -## Step 4: Spec Generation +- Current architecture patterns and conventions +- Relevant existing components or features +- Integration constraints or dependencies +- Files that might need modification or extension + +**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. + +## Step 4: Scope Validation + +After gathering initial responses and context, validate that the scope remains appropriate. Consider both the user requirements and the existing codebase context. If the answers revealed additional complexity or constraints, reassess whether the feature needs to be split or refined. + +## Step 5: Spec Generation Generate a comprehensive specification using this exact structure: @@ -185,7 +197,7 @@ FR3. [Requirement 3 - clear, testable, unambiguous] - [Question 2] ``` -## Step 5: Review and Refinement +## Step 6: Review and Refinement After generating the spec, present it to the user and ask: @@ -229,9 +241,10 @@ Once this spec is complete and approved, the user should run `/generate-task-lis 1. Assess scope appropriateness using the provided examples 2. Ask clarifying questions with numbered/lettered options -3. Validate scope based on user responses -4. Generate spec using the exact structure provided -5. Save to `./docs/specs/[n]-spec-[feature-name].md` -6. Review with user and refine until satisfied -7. Guide user to the next workflow step (`/generate-task-list-from-spec`) -8. Stop working once user confirms spec is complete +3. Review existing codebase for relevant context (optional) +4. Validate scope based on user responses and context +5. Generate spec using the exact structure provided +6. Save to `./docs/specs/[n]-spec-[feature-name].md` +7. Review with user and refine until satisfied +8. Guide user to the next workflow step (`/generate-task-list-from-spec`) +9. Stop working once user confirms spec is complete From 7b22b96735cd091b018ff89a650befc907c0706b Mon Sep 17 00:00:00 2001 From: Damien Storm Date: Tue, 4 Nov 2025 23:56:28 -0500 Subject: [PATCH 05/18] refactor: refine spec template to reduce verbosity and duplication This commit refines the generate-spec template to address verbosity concerns and eliminate content duplication across specification sections. ## Template Structure Improvements **Enhanced Section Guidance:** - Updated User Stories to focus on user motivation and WHY - Clarified Demoable Units to focus on tangible progress and WHAT - Refined Functional Requirements to focus on system behavior and WHAT - Improved Design Considerations to focus on UI/UX requirements - Enhanced Technical Considerations to focus on implementation constraints and HOW **Formatting Consistency:** - Changed "Work Unit" to "Unit" for conciseness - Updated FR1/FR2/FR3 format to standard numbered lists with bold requirements - Improved Non-Goals, Success Metrics, and Open Questions formatting - Added explicit fallback text for Design and Technical Considerations **Duplication Prevention:** - Added comprehensive guidance in Final Instructions section - Explicit instruction to ensure each section has distinct purpose - Clear mapping of sections to their specific focus areas (WHY vs WHAT vs HOW) - Guidance to avoid restating content from previous sections ## Benefits **Reduced Verbosity:** - Each section now has clear, distinct purpose - Eliminates redundant content across sections - More concise, focused specifications **Improved Clarity:** - Users understand what each section should contain - Clear separation between user value, demonstration, system behavior, and implementation - Better readability and maintainability **Better Implementation Guidance:** - Developers get clear requirements without duplication - Technical considerations focus on constraints, not restating requirements - Demoable units focus on tangible proof, not user stories This refinement maintains all research-based improvements while producing leaner, more focused specifications that avoid content redundancy. --- prompts/generate-spec.md | 41 ++++++++++++++++++++++------------------ 1 file changed, 23 insertions(+), 18 deletions(-) diff --git a/prompts/generate-spec.md b/prompts/generate-spec.md index dfd79e4..9d0226a 100644 --- a/prompts/generate-spec.md +++ b/prompts/generate-spec.md @@ -141,60 +141,60 @@ Generate a comprehensive specification using this exact structure: ## User Stories -[Detail 3-5 user narratives using the format: "As a [type of user], I want to [perform an action] so that [benefit]."] +[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 -[Define 2-4 small, end-to-end vertical slices. For each slice include:] +[Focus on tangible progress and WHAT will be demonstrated. Define 2-4 small, end-to-end vertical slices using the format below.] -### [Work Unit 1]: [Title] +### [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] -### [Work Unit 2]: [Title] +### [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 -[Numbered list of specific functionalities. Each should start with "The system shall..." or "The user shall..."] +[Focus on system behavior and WHAT the system must do. Each should start with "The system shall..." or "The user shall..."] -FR1. [Requirement 1 - clear, testable, unambiguous] -FR2. [Requirement 2 - clear, testable, unambiguous] -FR3. [Requirement 3 - clear, testable, unambiguous] +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.] -- [Specific exclusion 1] -- [Specific exclusion 2] -- [Specific exclusion 3] +1. [**Specific exclusion 1**: description] +2. [**Specific exclusion 2**: description] +3. [**Specific exclusion 3**: description] ## Design Considerations -[Link to mockups, describe UI/UX requirements, or mention relevant components/styles. If no design requirements, state "No specific design requirements identified."] +[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."] ## Technical Considerations -[Mention known technical constraints, dependencies, or suggestions. If no technical constraints, state "No specific technical constraints identified."] +[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.] -- [Metric 1 with target if applicable] -- [Metric 2 with target if applicable] -- [Metric 3 with target if applicable] +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."] -- [Question 1] -- [Question 2] +1. [Question 1] +2. [Question 2] ``` ## Step 6: Review and Refinement @@ -244,6 +244,11 @@ Once this spec is complete and approved, the user should run `/generate-task-lis 3. Review existing codebase for relevant context (optional) 4. Validate scope based on user responses and context 5. Generate 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 6. Save to `./docs/specs/[n]-spec-[feature-name].md` 7. Review with user and refine until satisfied 8. Guide user to the next workflow step (`/generate-task-list-from-spec`) From 895d6f9b397ddc97f1611087ea8286968f9f2860 Mon Sep 17 00:00:00 2001 From: Damien Storm Date: Wed, 5 Nov 2025 00:35:14 -0500 Subject: [PATCH 06/18] refactor: update spec output structure to use subdirectories This commit updates the generate-spec prompt to use a subdirectory structure for specification files instead of flat files in the specs directory. ## Directory Structure Changes **Previous Structure:** - Location: ./docs/specs/ - Format: [n]-spec-[feature-name].md (flat files) **New Structure:** - Location: ./docs/specs/[n]-spec-[feature-name]/ - Format: [n]-spec-[feature-name]/[n]-spec-[feature-name].md ## Benefits **Better Organization:** - Each spec gets its own dedicated directory - Related files can be co-located with the spec - Cleaner directory listing with logical grouping **Enhanced Extensibility:** - Room for additional spec-related artifacts - Can include diagrams, examples, or supporting documents - Future-proof for spec evolution needs **Improved Navigation:** - Clear separation between different specifications - Easier to find all files related to a specific feature - Better support for spec versioning or iterations ## Updated References - Updated Output Requirements section with new path structure - Modified Final Instructions to reflect new save location - Maintains all existing functionality while improving organization This change supports better long-term maintenance and organization of specification artifacts while preserving the established numbering system and workflow compatibility. --- prompts/generate-spec.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/prompts/generate-spec.md b/prompts/generate-spec.md index 9d0226a..05b7957 100644 --- a/prompts/generate-spec.md +++ b/prompts/generate-spec.md @@ -211,8 +211,8 @@ Iterate based on feedback until the user is satisfied. ## Output Requirements **Format:** Markdown (`.md`) -**Location:** `./docs/specs/` -**Filename:** `[n]-spec-[feature-name].md` (Where `n` is a zero-padded 2-digit sequence starting from 01, e.g., `01-spec-user-authentication.md`) +**Location:** `./docs/specs/[n]-spec-[feature-name]/` (Where `n` is a zero-padded 2-digit sequence starting from 01, e.g., `01-spec-user-authentication/`) +**Filename:** `[n]-spec-[feature-name].md` ## Critical Constraints (Negative Instructions) @@ -249,7 +249,7 @@ Once this spec is complete and approved, the user should run `/generate-task-lis - **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 -6. Save to `./docs/specs/[n]-spec-[feature-name].md` +6. Save to `./docs/specs/[n]-spec-[feature-name]/[n]-spec-[feature-name].md` 7. Review with user and refine until satisfied 8. Guide user to the next workflow step (`/generate-task-list-from-spec`) 9. Stop working once user confirms spec is complete From 347b8e2c926d281ea6f5d95b11b49c759bf3f0f9 Mon Sep 17 00:00:00 2001 From: Damien Storm Date: Wed, 5 Nov 2025 02:40:38 -0500 Subject: [PATCH 07/18] refactor(spec): fix prompt flow inconsistencies and enhance workflow integration - Resolve conflicting process sequences causing unpredictable AI behavior - Add comprehensive Workflow Integration section with value chain mapping - Standardize section naming across workflow prompts - Fix directory structure instructions to ensure proper subdirectory creation - Simplify process from 6-step to 5-step sequence removing duplicate validation - Enhance Output Requirements with explicit directory creation guidance These changes improve prompt reliability and consistency in the SDD workflow. --- prompts/generate-spec.md | 70 ++++++++++++++++++++++++++-------------- 1 file changed, 46 insertions(+), 24 deletions(-) diff --git a/prompts/generate-spec.md b/prompts/generate-spec.md index 05b7957..4863454 100644 --- a/prompts/generate-spec.md +++ b/prompts/generate-spec.md @@ -16,9 +16,32 @@ meta: 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. -**What comes next:** After completing this spec, the user will move to task generation using the `/generate-task-list-from-spec` command. +### Workflow Integration -## Role +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. @@ -30,12 +53,13 @@ If the user did not include an initial input or reference for the spec, ask the ## Process Overview -1. **Initial Assessment** - Evaluate the user input for scope appropriateness +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. **Scope Validation** - Ensure the feature is appropriately sized considering requirements and context -5. **Spec Generation** - Create the detailed specification document -6. **Review and Refine** - Validate completeness and clarity with the user +4. **Spec Generation** - Create the detailed specification document +5. **Review and Refine** - Validate completeness and clarity with the user ## Step 1: Initial Scope Assessment @@ -120,11 +144,7 @@ If the feature involves existing systems, briefly review the codebase and existi **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. -## Step 4: Scope Validation - -After gathering initial responses and context, validate that the scope remains appropriate. Consider both the user requirements and the existing codebase context. If the answers revealed additional complexity or constraints, reassess whether the feature needs to be split or refined. - -## Step 5: Spec Generation +## Step 4: Spec Generation Generate a comprehensive specification using this exact structure: @@ -197,7 +217,7 @@ Generate a comprehensive specification using this exact structure: 2. [Question 2] ``` -## Step 6: Review and Refinement +## Step 5: Review and Refinement After generating the spec, present it to the user and ask: @@ -211,8 +231,9 @@ Iterate based on feedback until the user is satisfied. ## Output Requirements **Format:** Markdown (`.md`) -**Location:** `./docs/specs/[n]-spec-[feature-name]/` (Where `n` is a zero-padded 2-digit sequence starting from 01, e.g., `01-spec-user-authentication/`) -**Filename:** `[n]-spec-[feature-name].md` +**Directory:** Create `./docs/specs/[n]-spec-[feature-name]/` (Where `n` is a zero-padded 2-digit sequence starting from 01, e.g., `01-spec-user-authentication/`) +**Full Path:** `./docs/specs/[n]-spec-[feature-name]/[n]-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 ## Critical Constraints (Negative Instructions) @@ -235,21 +256,22 @@ Iterate based on feedback until the user is satisfied. ## What Comes Next -Once this spec is complete and approved, the user should run `/generate-task-list-from-spec` to break down the specification into actionable tasks. This maintains the workflow's progression from idea → spec → tasks → implementation → validation. +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. ## Final Instructions -1. Assess scope appropriateness using the provided examples -2. Ask clarifying questions with numbered/lettered options -3. Review existing codebase for relevant context (optional) -4. Validate scope based on user responses and context -5. Generate spec using the exact structure provided +Follow this exact sequence: + +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 -6. Save to `./docs/specs/[n]-spec-[feature-name]/[n]-spec-[feature-name].md` -7. Review with user and refine until satisfied -8. Guide user to the next workflow step (`/generate-task-list-from-spec`) -9. Stop working once user confirms spec is complete +5. **Save**: Create directory `./docs/specs/[n]-spec-[feature-name]/` and save file as `[n]-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 From 45cf07b495c7ec58a66741caa880d44a9cfba386 Mon Sep 17 00:00:00 2001 From: Damien Storm Date: Wed, 5 Nov 2025 03:06:34 -0500 Subject: [PATCH 08/18] refactor(tasks): fix two-phase process by separating output formats MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add separate Phase 2 (parent tasks only) and Phase 3 (complete) output formats - Remove conflicting examples that caused AI to skip phase separation - Simplify overly restrictive instructions now that format confusion is resolved - Add fallback logic to auto-select oldest spec without tasks file - Enhance save process to preserve parent tasks before confirmation wait These changes ensure consistent two-phase behavior: generate parent tasks → save → wait for confirmation → generate sub-tasks. --- prompts/generate-task-list-from-spec.md | 201 +++++++++++++++++++++--- 1 file changed, 176 insertions(+), 25 deletions(-) diff --git a/prompts/generate-task-list-from-spec.md b/prompts/generate-task-list-from-spec.md index 3f7ebd6..4687e55 100644 --- a/prompts/generate-task-list-from-spec.md +++ b/prompts/generate-task-list-from-spec.md @@ -10,37 +10,150 @@ 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/[spec-directory]/` +- **Filename:** `[n]-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 `[n]-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 +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) -## Output Format +### Phase 2: Parent Task Generation -Every parent task must include **Demo Criteria** and **Proof Artifact(s)**. These are mandatory. +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/[spec-directory]/[n]-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" -The generated task list _must_ follow this example structure: +### 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/[spec-directory]/[n]-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 + +- [ ] 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" +``` + +## Phase 3 Output Format (Complete with Sub-Tasks) + +After user confirmation in Phase 3, update the file with this complete structure: ```markdown ## Relevant Files @@ -68,22 +181,60 @@ 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: + +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 + +**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." ## Target Audience -Assume the primary reader of the task list is a **junior developer** who will implement the feature with awareness of the existing codebase context. +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 + +## 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 + +## 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. -## After Subtask Generation +## Final Instructions -- 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. +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/[n]-spec-[feature-name]/[n]-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 From af76955b68e030894344247e634fd99471f84d63 Mon Sep 17 00:00:00 2001 From: Damien Storm Date: Wed, 5 Nov 2025 04:49:48 -0500 Subject: [PATCH 09/18] feat: refactor manage-tasks prompt with research-backed workflow engineering MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Apply structured workflow patterns from agentic AI research - Implement Chain-of-Verification (CoV) technique for self-checking - Add explicit command execution with immediate verification steps - Create blocking verification mechanisms that prevent progression - Replace heavy-handed enforcement with structured protocols - Use task-driven proof artifact requirements instead of prescriptive lists - Apply schema enforcement through checklist-based verification - Implement error recovery protocols with clear fix-verify cycles Research-backed techniques applied: 1. Structured workflows with validation gates (Skywork AI, 2024) 2. Self-verification mechanisms (Medium CoVe research, 2024) 3. Schema enforcement and structured outputs (OpenAI, 2024) 4. Chain-of-thought reasoning with verification checkpoints 5. Positive directives over negative constraints (PromptHub principles) Key improvements achieved: - Task list management: ✅ Working consistently - Git commits: ✅ Created after each parent task - Proof artifacts: ✅ Generated with proper naming convention - Progress tracking: ✅ Real-time task file updates - Verification: ✅ Built-in checkpoints prevent errors The refactor transforms prompt behavior from 0% compliance to consistent workflow adherence through structured guidance rather than authoritarian enforcement. --- prompts/manage-tasks.md | 366 +++++++++++++++++++++++++++++++++------- 1 file changed, 301 insertions(+), 65 deletions(-) diff --git a/prompts/manage-tasks.md b/prompts/manage-tasks.md index 32ff4c6..1bf6eac 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,306 @@ 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/[spec-directory]/[n]-tasks-[spec-name].md` +[ ] Read current task status and identify next sub-task +[ ] Verify checkpoint mode preference with user +[ ] Confirm demo criteria for current parent task +``` + +### 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 +3. **Test**: Verify implementation works as expected +4. **Mark Complete**: Update `[~]` → `[x]` for current sub-task +5. **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 `pytest`, `npm test`, or equivalent +[ ] **Create Proof Artifacts**: Generate ALL proof artifacts specified in the task's demo criteria in `./docs/specs/[spec-directory]/[n]-proofs/` + - Follow exactly what the task list specifies for demo artifacts + - **Use task number in naming**: For Task 1.0 use `01-`, Task 2.0 use `02-`, etc. + - **Naming format**: `[spec-number]-[task-number]-[artifact-name].[ext]` (e.g., `03-01-unified-help.txt` for Task 1.0) + - Include CLI output, test results, screenshots, or any other evidence required + - **Execute commands immediately**: `command > artifact.txt` or `screenshot-tool > artifact.png` + - **Verify creation**: `ls -la ./docs/specs/[spec-directory]/[n]-proofs/` +[ ] **Verify Demo Criteria**: Confirm all demo requirements are met +[ ] **Stage Changes**: `git add .` +[ ] **Create Commit**: Use conventional format with task reference + + ```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 Artifacts**: Run `ls -la ./docs/specs/[spec-directory]/[n]-proofs/` and confirm files exist +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 + +**Only after ALL THREE 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 +[ ] Demo criteria are satisfied +[ ] Commit message includes task reference and spec number + +**PROOF ARTIFACT VERIFICATION**: Confirm files exist and contain expected content +**COMMIT VERIFICATION**: Confirm git history shows the commit before proceeding + +**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/[spec-directory]/[n]-tasks-[spec-name].md` +- **Proof Artifacts**: `./docs/specs/[spec-directory]/[n]-proofs/` +- **Naming Convention**: `[spec]-[task]-[artifact-type].[ext]` + +### 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/[spec-directory]/[n]-proofs/` exists +[ ] **Review Task Requirements**: Check what demo artifacts the task specifically requires +[ ] **Create Required Artifacts**: Generate ALL proof artifacts specified in the task's demo criteria +[ ] **Use Task Number in Naming**: + - Task 1.0 artifacts: Use `01-` prefix (e.g., `03-01-unified-help.txt`) + - Task 2.0 artifacts: Use `02-` prefix (e.g., `03-02-server-startup.txt`) + - Task 3.0 artifacts: Use `03-` prefix (e.g., `03-03-config-validation.txt`) + - Task 4.0 artifacts: Use `04-` prefix (e.g., `03-04-entry-points.txt`) +[ ] **Verify Content**: Confirm artifacts contain the evidence required by the task +[ ] **Validate Demo Criteria**: Ensure artifacts demonstrate the demo requirements are met + +**TASK-DRIVEN VERIFICATION**: Artifacts must match exactly what the task specifies +**NAMING VERIFICATION**: Confirm files use correct task number prefix +**CONTENT VERIFICATION**: Ensure artifacts provide evidence for the specific demo criteria in the task + +**Proof artifacts 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 conventional format with proper frequency +- All tests pass and demo criteria are met +- Task file accurately reflects final status From bc654218a23ca3e101a565a215875c8a0ac306bd Mon Sep 17 00:00:00 2001 From: Damien Storm Date: Wed, 5 Nov 2025 05:38:50 -0500 Subject: [PATCH 10/18] refactor(workflow): simplify proof artifacts to single markdown file per task Replace complex multi-file artifact creation with single markdown file approach: - Change from multiple files with naming conventions to one [spec]-task-[number]-proofs.md file - Include structured sections for CLI output, test results, screenshots, and configuration - Simplify verification from checking multiple files to validating one comprehensive file - Maintain all blocking verification and checkpoint mechanisms - Reduce cognitive load while preserving proof quality and validation requirements This addresses user feedback about naming convention complexity and follows the pattern where the AI successfully implemented simpler, single-action workflows. --- prompts/manage-tasks.md | 47 ++++++++++++++++++++--------------------- 1 file changed, 23 insertions(+), 24 deletions(-) diff --git a/prompts/manage-tasks.md b/prompts/manage-tasks.md index 1bf6eac..d5c0992 100644 --- a/prompts/manage-tasks.md +++ b/prompts/manage-tasks.md @@ -110,13 +110,12 @@ For each sub-task in the parent task: When all sub-tasks are `[x]`, complete these steps IN ORDER: [ ] **Run Test Suite**: Execute `pytest`, `npm test`, or equivalent -[ ] **Create Proof Artifacts**: Generate ALL proof artifacts specified in the task's demo criteria in `./docs/specs/[spec-directory]/[n]-proofs/` - - Follow exactly what the task list specifies for demo artifacts - - **Use task number in naming**: For Task 1.0 use `01-`, Task 2.0 use `02-`, etc. - - **Naming format**: `[spec-number]-[task-number]-[artifact-name].[ext]` (e.g., `03-01-unified-help.txt` for Task 1.0) - - Include CLI output, test results, screenshots, or any other evidence required - - **Execute commands immediately**: `command > artifact.txt` or `screenshot-tool > artifact.png` - - **Verify creation**: `ls -la ./docs/specs/[spec-directory]/[n]-proofs/` +[ ] **Create Proof Artifacts**: Create a single markdown file with all evidence for the task in `./docs/specs/[spec-directory]/[n]-proofs/` + - **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 conventional format with task reference @@ -133,8 +132,7 @@ When all sub-tasks are `[x]`, complete these steps IN ORDER: [ ] **Save Task File**: Commit the updated task file **BLOCKING VERIFICATION**: Before proceeding to next parent task, you MUST: - -1. **Verify Proof Artifacts**: Run `ls -la ./docs/specs/[spec-directory]/[n]-proofs/` and confirm files exist +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 @@ -201,21 +199,22 @@ Each parent task must include artifacts that: For each parent task completion: [ ] **Directory Ready**: `./docs/specs/[spec-directory]/[n]-proofs/` exists -[ ] **Review Task Requirements**: Check what demo artifacts the task specifically requires -[ ] **Create Required Artifacts**: Generate ALL proof artifacts specified in the task's demo criteria -[ ] **Use Task Number in Naming**: - - Task 1.0 artifacts: Use `01-` prefix (e.g., `03-01-unified-help.txt`) - - Task 2.0 artifacts: Use `02-` prefix (e.g., `03-02-server-startup.txt`) - - Task 3.0 artifacts: Use `03-` prefix (e.g., `03-03-config-validation.txt`) - - Task 4.0 artifacts: Use `04-` prefix (e.g., `03-04-entry-points.txt`) -[ ] **Verify Content**: Confirm artifacts contain the evidence required by the task -[ ] **Validate Demo Criteria**: Ensure artifacts demonstrate the demo requirements are met - -**TASK-DRIVEN VERIFICATION**: Artifacts must match exactly what the task specifies -**NAMING VERIFICATION**: Confirm files use correct task number prefix -**CONTENT VERIFICATION**: Ensure artifacts provide evidence for the specific demo criteria in the task - -**Proof artifacts must be created BEFORE the parent task commit** +[ ] **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 From 309ba12543459d8bdc308ce2e4ef850f2b850340 Mon Sep 17 00:00:00 2001 From: Damien Storm Date: Wed, 5 Nov 2025 05:46:04 -0500 Subject: [PATCH 11/18] refactor(workflow): update validation prompt to use new directory structure - Update Auto-Discovery Protocol to scan ./docs/specs/ for directories - Change pattern from flat files to [n]-spec-[feature-name]/ directories - Maintain consistency with other workflow prompts - Ensure validation works with new subdirectory-based spec organization --- prompts/validate-spec-implementation.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/prompts/validate-spec-implementation.md b/prompts/validate-spec-implementation.md index 688cf7c..d13dcc3 100644 --- a/prompts/validate-spec-implementation.md +++ b/prompts/validate-spec-implementation.md @@ -28,8 +28,8 @@ Validate that the **code changes** conform to the Spec and Task List by verifyin If no spec is provided, follow this exact sequence: -1. Scan `./tasks/` for files matching pattern `[n]-spec-*.md` -2. Identify specs with corresponding `tasks-[n]-spec-*.md` files +1. Scan `./docs/specs/` for directories matching pattern `[n]-spec-[feature-name]/` +2. Identify spec directories with corresponding `[n]-tasks-[feature-name].md` files 3. Select the spec with: - Highest sequence number where task list exists - At least one incomplete parent task (`[ ]` or `[~]`) @@ -133,14 +133,14 @@ For each Functional Requirement and Demoable Unit: Provide two tables (edit as needed): -**Functional Requirements** +#### 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 | -**Proof Artifacts** +#### Proof Artifacts | Demo Unit | Proof Artifact | Status | Evidence & Output | | --- | --- | --- | --- | From afc8227367af825e23c98fa8fe1aad4469564a3a Mon Sep 17 00:00:00 2001 From: Damien Storm Date: Wed, 5 Nov 2025 06:01:29 -0500 Subject: [PATCH 12/18] fix(workflow): enhance validation prompt and standardize next-step guidance - Add 'You are here in the workflow' section to validation prompt - Add 'Your Role' section defining QA Engineer persona - Standardize 'What comes next' format across all prompts - Include final code review instruction in validation phase - Ensure consistent workflow progression messaging --- prompts/generate-task-list-from-spec.md | 6 ++-- prompts/manage-tasks.md | 14 +++++---- prompts/validate-spec-implementation.md | 40 +++++++++++++++++++++++-- 3 files changed, 50 insertions(+), 10 deletions(-) diff --git a/prompts/generate-task-list-from-spec.md b/prompts/generate-task-list-from-spec.md index 4687e55..7977cb0 100644 --- a/prompts/generate-task-list-from-spec.md +++ b/prompts/generate-task-list-from-spec.md @@ -96,7 +96,7 @@ Before generating any tasks, you must follow this reasoning process: ## Output - **Format:** Markdown (`.md`) -- **Location:** `./docs/specs/[spec-directory]/` +- **Location:** `./docs/specs/[n]-spec-[feature-name]/` - **Filename:** `[n]-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 @@ -121,7 +121,7 @@ Before generating any tasks, you must follow this reasoning process: - 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/[spec-directory]/[n]-tasks-[feature-name].md` before proceeding +2. **Save Initial Task List:** Save the parent tasks to `./docs/specs/[n]-spec-[feature-name]/[n]-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" @@ -131,7 +131,7 @@ 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/[spec-directory]/[n]-tasks-[feature-name].md` file with the sub-tasks and relevant files sections +3. **Update Task List:** Update the existing `./docs/specs/[n]-spec-[feature-name]/[n]-tasks-[feature-name].md` file with the sub-tasks and relevant files sections ## Phase 2 Output Format (Parent Tasks Only) diff --git a/prompts/manage-tasks.md b/prompts/manage-tasks.md index d5c0992..da00d0d 100644 --- a/prompts/manage-tasks.md +++ b/prompts/manage-tasks.md @@ -80,7 +80,7 @@ For each parent task, follow this structured workflow with built-in verification ```markdown ## PRE-WORK CHECKLIST (Complete before starting any sub-task) -[ ] Locate task file: `./docs/specs/[spec-directory]/[n]-tasks-[spec-name].md` +[ ] Locate task file: `./docs/specs/[n]-spec-[feature-name]/[n]-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 @@ -110,7 +110,7 @@ For each sub-task in the parent task: When all sub-tasks are `[x]`, complete these steps IN ORDER: [ ] **Run Test Suite**: Execute `pytest`, `npm test`, or equivalent -[ ] **Create Proof Artifacts**: Create a single markdown file with all evidence for the task in `./docs/specs/[spec-directory]/[n]-proofs/` +[ ] **Create Proof Artifacts**: Create a single markdown file with all evidence for the task in `./docs/specs/[n]-spec-[feature-name]/[n]-proofs/` - **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 @@ -171,8 +171,8 @@ After each parent task completion, verify: ### File Location Requirements -- **Task List**: `./docs/specs/[spec-directory]/[n]-tasks-[spec-name].md` -- **Proof Artifacts**: `./docs/specs/[spec-directory]/[n]-proofs/` +- **Task List**: `./docs/specs/[n]-spec-[feature-name]/[n]-tasks-[feature-name].md` +- **Proof Artifacts**: `./docs/specs/[n]-spec-[feature-name]/[n]-proofs/` - **Naming Convention**: `[spec]-[task]-[artifact-type].[ext]` ### File Update Protocol @@ -198,7 +198,7 @@ Each parent task must include artifacts that: For each parent task completion: -[ ] **Directory Ready**: `./docs/specs/[spec-directory]/[n]-proofs/` exists +[ ] **Directory Ready**: `./docs/specs/[n]-spec-[feature-name]/[n]-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**: @@ -312,3 +312,7 @@ Implementation is successful when: - Git commits follow conventional format with proper frequency - All tests pass and demo criteria are met - Task file accurately reflects final status + +## 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 index d13dcc3..a3eada4 100644 --- a/prompts/validate-spec-implementation.md +++ b/prompts/validate-spec-implementation.md @@ -1,5 +1,5 @@ --- -name: validate-spec-implementation-v3 +name: validate-spec-implementation description: "Focused validation of code changes against Spec and Proof Artifacts with evidence-based coverage matrix" tags: - validation @@ -11,7 +11,39 @@ meta: allowed-tools: Glob, Grep, LS, Read, Edit, MultiEdit, Write, WebFetch, WebSearch, Terminal, Git --- -# Validate Spec Implementation (v3 — focused evidence-based) +# 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 @@ -171,6 +203,10 @@ For each issue: - 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] From 1f86adbca6a87c141916d1d314a4b4916417f7b9 Mon Sep 17 00:00:00 2001 From: Damien Storm Date: Wed, 5 Nov 2025 06:19:12 -0500 Subject: [PATCH 13/18] docs: move refactor spec to archive --- .../archive/refactor-sdd-workflow-prompts.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename refactor-sdd-workflow-prompts.md => docs/archive/refactor-sdd-workflow-prompts.md (100%) diff --git a/refactor-sdd-workflow-prompts.md b/docs/archive/refactor-sdd-workflow-prompts.md similarity index 100% rename from refactor-sdd-workflow-prompts.md rename to docs/archive/refactor-sdd-workflow-prompts.md From 2147d3d468eac4ba5ef825872f0190f716bc73ee Mon Sep 17 00:00:00 2001 From: Damien Storm Date: Wed, 5 Nov 2025 06:28:31 -0500 Subject: [PATCH 14/18] chore: tweak pre-commit --- .pre-commit-config.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 From e6f9e37f16ce7477760530862d6cdb5b4d57af5f Mon Sep 17 00:00:00 2001 From: Damien Storm Date: Wed, 5 Nov 2025 17:27:30 -0500 Subject: [PATCH 15/18] feat(workflow): integrate repository pattern compliance across spec-driven workflow This commit implements comprehensive repository pattern compliance guidance across all four SDD workflow prompts, ensuring AI implementations follow established project standards regardless of technology stack. **Applied research-backed prompt engineering findings:** - Context Engineering: Grounded pattern discovery in repository documentation and configuration rather than prescribing specific tools - Progressive Disclosure: Integrated pattern guidance throughout workflow phases rather than treating as separate concern - Structured Verification: Added repository compliance as validation gates and verification checkpoints following existing research-backed patterns - Framework-Agnostic Design: Used generic examples (pytest, npm test, cargo test, etc.) to work across any technology stack **Enhanced Prompts with Pattern Integration:** 1. **generate-spec.md**: Added repository pattern discovery to Context Assessment and 'Repository Standards' section to spec template 2. **generate-task-list-from-spec.md**: Enhanced Current State Assessment to identify repository standards and added pattern compliance to Quality Checklist 3. **manage-tasks.md**: Added repository pattern review to all execution phases with framework-agnostic quality gate integration 4. **validate-spec-implementation.md**: Added repository compliance as validation gate (GATE E) with dedicated coverage matrix table **Key Improvements Achieved:** - Repository Standards Discovery: AI now automatically identifies coding standards, testing patterns, quality gates, and workflows from project documentation - Framework-Agnostic Guidance: Works with any repository (Python, JavaScript, Rust, etc.) without prescribing specific tools - Seamless Workflow Integration: Pattern compliance woven throughout existing verification mechanisms - Blocking Verification: Repository standards enforced through same checkpoints that ensure workflow adherence **Technical Implementation:** - Enhanced verification checkpoints from 3 to 4 in manage-tasks.md to include pattern compliance - Added R6 Repository Compliance to validation rubric with dedicated evidence collection - Fixed consistency issues (table count, validation process references) - Maintained backward compatibility while adding comprehensive pattern guidance This enhancement ensures that any AI using these prompts will automatically discover and follow existing repository patterns, addressing the critical gap where implementations previously ignored project conventions and standards. Research sources: Context engineering best practices (DAIR AI), structured workflow verification (Skywork AI), and the repository's established research-backed prompt patterns. --- prompts/generate-spec.md | 20 +++++++++++++++- prompts/generate-task-list-from-spec.md | 8 ++++++- prompts/manage-tasks.md | 31 +++++++++++++++++-------- prompts/validate-spec-implementation.md | 27 ++++++++++++++++++--- 4 files changed, 71 insertions(+), 15 deletions(-) diff --git a/prompts/generate-spec.md b/prompts/generate-spec.md index 4863454..07086ed 100644 --- a/prompts/generate-spec.md +++ b/prompts/generate-spec.md @@ -141,8 +141,14 @@ If the feature involves existing systems, briefly review the codebase and existi - 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. +**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 @@ -197,6 +203,16 @@ Generate a comprehensive specification using this exact structure: [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."] @@ -244,6 +260,7 @@ Iterate based on feedback until the user is satisfied. - 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 **ALWAYS:** @@ -253,6 +270,7 @@ Iterate based on feedback until the user is satisfied. - 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 ## What Comes Next diff --git a/prompts/generate-task-list-from-spec.md b/prompts/generate-task-list-from-spec.md index 7977cb0..ecf4618 100644 --- a/prompts/generate-task-list-from-spec.md +++ b/prompts/generate-task-list-from-spec.md @@ -111,6 +111,7 @@ Before generating any tasks, you must follow this reasoning process: - 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) @@ -168,7 +169,9 @@ After user confirmation in Phase 3, update the file with this complete 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 @@ -209,6 +212,7 @@ Write tasks and sub-tasks for a **junior developer** who: - 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 @@ -222,6 +226,8 @@ Before finalizing your task list, verify: - [ ] 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 diff --git a/prompts/manage-tasks.md b/prompts/manage-tasks.md index da00d0d..2a996b1 100644 --- a/prompts/manage-tasks.md +++ b/prompts/manage-tasks.md @@ -84,6 +84,8 @@ For each parent task, follow this structured workflow with built-in verification [ ] 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 @@ -94,10 +96,11 @@ For each parent task, follow this structured workflow with built-in verification 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 -3. **Test**: Verify implementation works as expected -4. **Mark Complete**: Update `[~]` → `[x]` for current sub-task -5. **Save Task File**: Immediately save changes to 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 ``` @@ -109,7 +112,8 @@ For each sub-task in the parent task: When all sub-tasks are `[x]`, complete these steps IN ORDER: -[ ] **Run Test Suite**: Execute `pytest`, `npm test`, or equivalent +[ ] **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/[n]-spec-[feature-name]/[n]-proofs/` - **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 @@ -118,7 +122,7 @@ When all sub-tasks are `[x]`, complete these steps IN ORDER: - **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 conventional format with task reference +[ ] **Create Commit**: Use repository's commit format and conventions ```bash git add . @@ -135,8 +139,9 @@ When all sub-tasks are `[x]`, complete these steps IN ORDER: 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 THREE verifications pass may you proceed to the next parent task** +**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 ``` @@ -151,12 +156,15 @@ 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 +[ ] 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** ``` @@ -309,9 +317,12 @@ Implementation is successful when: - All parent tasks are marked `[x]` in task file - Proof artifacts exist for each parent task -- Git commits follow conventional format with proper frequency -- All tests pass and demo criteria are met +- 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 diff --git a/prompts/validate-spec-implementation.md b/prompts/validate-spec-implementation.md index a3eada4..ca22996 100644 --- a/prompts/validate-spec-implementation.md +++ b/prompts/validate-spec-implementation.md @@ -74,6 +74,7 @@ If no spec is provided, follow this exact sequence: - **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) @@ -84,6 +85,7 @@ Map score to severity: 0→CRITICAL, 1→HIGH, 2→MEDIUM, 3→OK. - **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) @@ -108,17 +110,19 @@ Map score to severity: 0→CRITICAL, 1→HIGH, 2→MEDIUM, 3→OK. - **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 and Demoable Unit: +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**. @@ -140,7 +144,13 @@ For each Functional Requirement and Demoable Unit: - Demo Criteria are satisfied by the implementation - Code structure follows spec specifications -4) **Git Traceability** +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 @@ -152,6 +162,8 @@ For each Functional Requirement and Demoable Unit: - 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) @@ -163,7 +175,7 @@ For each Functional Requirement and Demoable Unit: ### 2) Coverage Matrix (required) -Provide two tables (edit as needed): +Provide three tables (edit as needed): #### Functional Requirements @@ -172,6 +184,15 @@ Provide two tables (edit as needed): | 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 | From c91418401ad86402cd0908a4367674081f509a11 Mon Sep 17 00:00:00 2001 From: Damien Storm Date: Thu, 6 Nov 2025 00:03:37 -0500 Subject: [PATCH 16/18] fix: address PR review feedback - proof artifact structure and placeholder consistency MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix proof artifact structure conflict in archive document to show single markdown files - Clarify [n] placeholder format to [NN] with explicit zero-padded definition across all prompt files - Fix grammar: 'single line changes' → 'single-line changes' - All quality gates pass: pre-commit hooks, tests, and linting --- docs/archive/refactor-sdd-workflow-prompts.md | 24 +++++++------------ prompts/generate-spec.md | 4 ++-- prompts/generate-task-list-from-spec.md | 6 ++--- prompts/manage-tasks.md | 8 +++---- 4 files changed, 18 insertions(+), 24 deletions(-) diff --git a/docs/archive/refactor-sdd-workflow-prompts.md b/docs/archive/refactor-sdd-workflow-prompts.md index d42b12e..1674d06 100644 --- a/docs/archive/refactor-sdd-workflow-prompts.md +++ b/docs/archive/refactor-sdd-workflow-prompts.md @@ -114,24 +114,18 @@ All specs, tasks, and proofs should be stored in `./docs/specs`. Simple director ./docs/specs/ ├── 01-spec-feature-name ├── 01-spec-feature-name.md - ├── tasks-01-spec-feature-name.md + ├── 01-tasks-feature-name.md └── 01-proofs/ - ├── 01-01-demo.png - ├── 01-01-cli-output.txt - ├── 01-01-test-results.json - ├── 01-02-demo.png - ├── 01-02-cli-output.txt - ├── 01-02-test-results.json + ├── 01-01-proofs.md + ├── 01-02-proofs.md + ├── 01-03-proofs.md ├── 02-spec-another-feature ├── 02-spec-another-feature.md - ├── tasks-02-spec-another-feature.md + ├── 02-tasks-another-feature.md └── 02-proofs/ - ├── 02-01-demo.png - ├── 02-01-cli-output.txt - ├── 02-01-test-results.json - ├── 02-02-demo.png - ├── 02-02-cli-output.txt - ├── 02-02-test-results.json + ├── 02-01-proofs.md + ├── 02-02-proofs.md + ├── 02-03-proofs.md ``` **Key Principles:** @@ -140,7 +134,7 @@ All specs, tasks, and proofs should be stored in `./docs/specs`. Simple director - **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 `[spec]-[task]-[artifact]` pattern (e.g., 01-01-demo.png) +- **Consistent naming**: Proof artifacts follow single markdown file pattern `[spec]-[task]-proofs.md` containing all evidence as markdown code blocks ### Simplify numbering system diff --git a/prompts/generate-spec.md b/prompts/generate-spec.md index 07086ed..b50f3c0 100644 --- a/prompts/generate-spec.md +++ b/prompts/generate-spec.md @@ -247,8 +247,8 @@ Iterate based on feedback until the user is satisfied. ## Output Requirements **Format:** Markdown (`.md`) -**Directory:** Create `./docs/specs/[n]-spec-[feature-name]/` (Where `n` is a zero-padded 2-digit sequence starting from 01, e.g., `01-spec-user-authentication/`) -**Full Path:** `./docs/specs/[n]-spec-[feature-name]/[n]-spec-[feature-name].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 ## Critical Constraints (Negative Instructions) diff --git a/prompts/generate-task-list-from-spec.md b/prompts/generate-task-list-from-spec.md index ecf4618..ae744cd 100644 --- a/prompts/generate-task-list-from-spec.md +++ b/prompts/generate-task-list-from-spec.md @@ -52,7 +52,7 @@ Create a detailed, step-by-step task list in Markdown format based on an existin ⚠️ **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** 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? @@ -96,8 +96,8 @@ Before generating any tasks, you must follow this reasoning process: ## Output - **Format:** Markdown (`.md`) -- **Location:** `./docs/specs/[n]-spec-[feature-name]/` -- **Filename:** `[n]-tasks-[feature-name].md` (e.g., if the Spec is `01-spec-user-profile-editing.md`, save as `01-tasks-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 diff --git a/prompts/manage-tasks.md b/prompts/manage-tasks.md index 2a996b1..117eb9d 100644 --- a/prompts/manage-tasks.md +++ b/prompts/manage-tasks.md @@ -114,7 +114,7 @@ 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/[n]-spec-[feature-name]/[n]-proofs/` +[ ] **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 @@ -179,9 +179,9 @@ After each parent task completion, verify: ### File Location Requirements -- **Task List**: `./docs/specs/[n]-spec-[feature-name]/[n]-tasks-[feature-name].md` -- **Proof Artifacts**: `./docs/specs/[n]-spec-[feature-name]/[n]-proofs/` -- **Naming Convention**: `[spec]-[task]-[artifact-type].[ext]` +- **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 From cdda5e519bd01e8e3e424104980d1f1bf60b7508 Mon Sep 17 00:00:00 2001 From: Damien Storm Date: Thu, 6 Nov 2025 00:12:31 -0500 Subject: [PATCH 17/18] fix: address additional PR review feedback - placeholder consistency and grammar MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix remaining [n] → [NN] placeholder inconsistencies in generate-spec.md and generate-task-list-from-spec.md - Fix grammar: 'top level' → 'top-level' in archive document - Fix capitalization: 'markdown' → 'Markdown' as proper noun - All quality gates pass: pre-commit hooks, tests (79/85%), and linting --- docs/archive/refactor-sdd-workflow-prompts.md | 4 ++-- prompts/generate-spec.md | 2 +- prompts/generate-task-list-from-spec.md | 6 +++--- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/archive/refactor-sdd-workflow-prompts.md b/docs/archive/refactor-sdd-workflow-prompts.md index 1674d06..66564b6 100644 --- a/docs/archive/refactor-sdd-workflow-prompts.md +++ b/docs/archive/refactor-sdd-workflow-prompts.md @@ -42,7 +42,7 @@ Based on prompt engineering best practices for spec-driven development, the work **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 +- 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 @@ -134,7 +134,7 @@ All specs, tasks, and proofs should be stored in `./docs/specs`. Simple director - **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 +- **Consistent naming**: Proof artifacts follow single Markdown file pattern `[spec]-[task]-proofs.md` containing all evidence as Markdown code blocks ### Simplify numbering system diff --git a/prompts/generate-spec.md b/prompts/generate-spec.md index b50f3c0..8713925 100644 --- a/prompts/generate-spec.md +++ b/prompts/generate-spec.md @@ -289,7 +289,7 @@ Follow this exact sequence: - **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/[n]-spec-[feature-name]/` and save file as `[n]-spec-[feature-name].md` inside it +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 ae744cd..aa342e6 100644 --- a/prompts/generate-task-list-from-spec.md +++ b/prompts/generate-task-list-from-spec.md @@ -103,7 +103,7 @@ Before generating any tasks, you must follow this reasoning process: ### 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 `[n]-tasks-[feature-name].md` file in the same directory). +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 @@ -122,7 +122,7 @@ Before generating any tasks, you must follow this reasoning process: - 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/[n]-spec-[feature-name]/[n]-tasks-[feature-name].md` before proceeding +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" @@ -132,7 +132,7 @@ 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/[n]-spec-[feature-name]/[n]-tasks-[feature-name].md` file with the sub-tasks and relevant files sections +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) From b27fcf1500bad024f323c1bd6257b1f58a3f5774 Mon Sep 17 00:00:00 2001 From: Damien Storm Date: Thu, 6 Nov 2025 00:12:54 -0500 Subject: [PATCH 18/18] =?UTF-8?q?fix:=20complete=20[n]=20=E2=86=92=20[NN]?= =?UTF-8?q?=20placeholder=20consistency=20across=20all=20prompt=20files?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fixed remaining [n] placeholders in validate-spec-implementation.md - Fixed [n] → [NN] in generate-spec.md template header - Fixed [n] → [NN] in generate-task-list-from-spec.md final instructions - Fixed [n] → [NN] in manage-tasks.md checklist and protocol sections - All prompt files now consistently use [NN] for zero-padded two-digit spec numbers - Quality gates pass: pre-commit hooks, linting, and formatting --- prompts/generate-spec.md | 2 +- prompts/generate-task-list-from-spec.md | 2 +- prompts/manage-tasks.md | 4 ++-- prompts/validate-spec-implementation.md | 4 ++-- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/prompts/generate-spec.md b/prompts/generate-spec.md index 8713925..3418e76 100644 --- a/prompts/generate-spec.md +++ b/prompts/generate-spec.md @@ -155,7 +155,7 @@ If the feature involves existing systems, briefly review the codebase and existi Generate a comprehensive specification using this exact structure: ```markdown -# [n]-spec-[feature-name].md +# [NN]-spec-[feature-name].md ## Introduction/Overview diff --git a/prompts/generate-task-list-from-spec.md b/prompts/generate-task-list-from-spec.md index aa342e6..0d3f89d 100644 --- a/prompts/generate-task-list-from-spec.md +++ b/prompts/generate-task-list-from-spec.md @@ -237,7 +237,7 @@ Once this task list is complete and approved, instruct the user to run `/manage- 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/[n]-spec-[feature-name]/[n]-tasks-[feature-name].md` +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 diff --git a/prompts/manage-tasks.md b/prompts/manage-tasks.md index 117eb9d..c357c4a 100644 --- a/prompts/manage-tasks.md +++ b/prompts/manage-tasks.md @@ -80,7 +80,7 @@ For each parent task, follow this structured workflow with built-in verification ```markdown ## PRE-WORK CHECKLIST (Complete before starting any sub-task) -[ ] Locate task file: `./docs/specs/[n]-spec-[feature-name]/[n]-tasks-[feature-name].md` +[ ] 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 @@ -206,7 +206,7 @@ Each parent task must include artifacts that: For each parent task completion: -[ ] **Directory Ready**: `./docs/specs/[n]-spec-[feature-name]/[n]-proofs/` exists +[ ] **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**: diff --git a/prompts/validate-spec-implementation.md b/prompts/validate-spec-implementation.md index ca22996..ad7f5fb 100644 --- a/prompts/validate-spec-implementation.md +++ b/prompts/validate-spec-implementation.md @@ -60,8 +60,8 @@ Validate that the **code changes** conform to the Spec and Task List by verifyin If no spec is provided, follow this exact sequence: -1. Scan `./docs/specs/` for directories matching pattern `[n]-spec-[feature-name]/` -2. Identify spec directories with corresponding `[n]-tasks-[feature-name].md` files +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 `[~]`)