refactor(prompts): improve spec generation workflow and task list formatting (#30)

* refactor(prompts): reorganize generate-spec workflow steps

- Add dedicated Step 1 for spec directory creation
- Renumber all subsequent steps (1→2, 2→3, etc.)
- Add Questions File Workflow for iterative Q&A process
- Update all step references throughout document
- Fix typo: 'pre-existing'

* docs(prompts): improve task list format with hierarchical structure

Update generate-task-list-from-spec prompt to use hierarchical markdown structure for better readability.

- Change from flat bullet lists to hierarchical headers (### and ####)

- Convert Demo Criteria and Proof Artifacts to bulleted lists

- Add TBD placeholder for Tasks section in Phase 2 output format

* docs(prompts): remove redundant instruction from iterative process

Remove bullet point about handling clarification requests in the current
questions file, as this is already covered by the workflow steps above.

* docs(prompts): add validation report output location

Add 'Saving The Output' section specifying where validation reports should be saved, aligning with other workflow output file locations in the spec directory structure.

* docs(prompts): add example format for clarifying questions

Add a generic example template showing the expected format for clarifying
questions with numbered questions, lettered options, and checkboxes. Remove
redundant instruction about providing multiple choice answers.

* refactor(prompts): consolidate functional requirements into demoable units

Move functional requirements from separate section into each Demoable Unit
to make specs more self-contained and easier to read. Each unit now contains
all requirements needed for implementation, reducing cross-referencing and
making the spec structure more actionable.

* refactor(prompts): remove demo criteria, consolidate into proof artifacts

Remove separate 'Demo Criteria' sections and consolidate verification into
self-documenting proof artifacts. Each proof artifact now describes what
it demonstrates (e.g., 'Screenshot: `--help` output demonstrates new
command exists').

Changes:
- Remove Demo Criteria from spec and task list templates
- Update proof artifacts format to include descriptive language
- Update all workflow references from demo criteria to proof artifacts
- Rename 'Evidence & Output' to 'Verification Result' in validation table
- Update all verification checklists to focus on proof artifacts

This simplifies the workflow by making proof artifacts the single source
of truth for what needs to be demonstrated.

* refactor(prompts): align validation to focus on proof artifacts

Refactor validation process to consistently focus on proof artifact
verification rather than code implementation analysis. This improves
cohesion and clarity throughout the validation prompt.

Changes:
- Update Evaluation Rubric (R1, R5) to focus on proof artifacts
- Refactor Step 4 verification to test proof artifacts instead of
  searching code files
- Rename 'Requirement Implementation' to 'Requirement Coverage'
- Update Coverage Matrix examples to use proof artifact results
- Restructure Validation Issues section with clearer format and
  table examples
- Remove code analysis directives (line numbers, file content checks)
- Add commit log analysis to repository compliance checks

This aligns validation with its stated goal: verifying proof artifacts
demonstrate spec requirements, not analyzing code implementation.

* fix(prompts): enforce wait for user answers in spec generation

Add explicit STOP AND WAIT instructions to prevent AI from jumping
straight from creating clarifying questions to generating the spec
without waiting for user responses. Reorganize workflow section for
better clarity and add critical enforcement points.

* refactor(prompts): improve clarity and enforceability in spec generation

- Rename sections for better clarity (Process Overview → Spec Generation Overview)
- Add explicit requirement to report scope assessment results
- Make context assessment required instead of optional
- Standardize question format with uppercase option letters
- Remove redundant Final Instructions section
- Improve formatting consistency throughout

* fix: add missing space

Author: ryderstorm

prompts/generate-spec.md

@@ -29,14 +29,14 @@ This spec serves as the **planning blueprint** for the entire SDD workflow:
 
 **Critical Dependencies:**
 
-- **User Stories** become the basis for task demo criteria
+- **User Stories** become the basis for proof artifacts in task generation
 - **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
+- Vague user stories → unclear proof artifacts 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
@@ -51,24 +51,54 @@ To create a comprehensive Specification (Spec) based on an initial user input. T
 
 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
+## Spec Generation Overview
 
-Follow this exact sequence:
+1. **Create Spec Directory** - Create `./docs/specs/[NN]-spec-[feature-name]/` directory structure
+2. **Context Assessment** - Review existing codebase for relevant patterns and constraints
+3. **Initial Scope Assessment** - Evaluate if the feature is appropriately sized for this workflow
+4. **Clarifying Questions** - Gather detailed requirements through structured inquiry
+5. **Spec Generation** - Create the detailed specification document
+6. **Review and Refine** - Validate completeness and clarity with the user
 
-1. **Initial Scope Assessment** - Evaluate if the feature is appropriately sized for this workflow
-2. **Clarifying Questions** - Gather detailed requirements through structured inquiry
-3. **Context Assessment** - Review existing codebase for relevant patterns and constraints (optional)
-4. **Spec Generation** - Create the detailed specification document
-5. **Review and Refine** - Validate completeness and clarity with the user
+## Step 1: Create Spec Directory
 
-## Step 1: Initial Scope Assessment
+Create the spec directory structure before proceeding with any other steps. This ensures all files (questions, spec, tasks, proofs) have a consistent location.
 
-Before asking questions, evaluate whether this feature request is appropriately sized for this spec-driven workflow.
+**Directory Structure:**
+
+- **Path**: `./docs/specs/[NN]-spec-[feature-name]/` where `[NN]` is a zero-padded 2-digit sequence number (e.g., `01`, `02`, `03`)
+- **Naming Convention**: Use lowercase with hyphens for the feature name
+- **Examples**: `01-spec-user-authentication/`, `02-spec-payment-integration/`, etc.
+
+**Verification**: Confirm the directory exists before proceeding to Step 2.
+
+## Step 2: Context Assessment
+
+If working in a pre-existing project, begin by briefly reviewing the codebase and existing docs to understand:
+
+- Current architecture patterns and conventions
+- Relevant existing components or features
+- Integration constraints or dependencies
+- Files that might need modification or extension
+- **Repository Standards and Patterns**: Identify existing coding standards, architectural patterns, and development practices from:
+  - Project documentation (README.md, CONTRIBUTING.md, docs/)
+  - AI specific documentation (AGENTS.md, CLAUDE.md)
+  - Configuration files (package.json, Cargo.toml, pyproject.toml, etc.)
+  - Existing code structure and naming conventions
+  - Testing patterns and quality assurance practices
+  - Commit message conventions and development workflows
+
+**Use this context to inform scope validation and requirements, not to drive technical decisions.** Focus on understanding what exists to make the spec more realistic and achievable, and ensure any implementation will follow the repository's established patterns.
+
+## Step 3: Initial Scope Assessment
+
+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
+- Use context from Step 2 to inform the assessment
 - If scope is too large, suggest breaking into smaller specs
 - If scope is too small, suggest direct implementation without formal spec
 
@@ -102,13 +132,16 @@ Before asking questions, evaluate whether this feature request is appropriately
 - 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.
+### Report Scope Assessment To User
 
-## Step 2: Clarifying Questions
+- **ALWAYS** inform the user of the result of the scope assessment.
+- If the scope appears inappropriate, **ALWAYS** pause the conversation to suggest alternatives and get input from the user.
 
-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."
+## Step 4: Clarifying Questions
 
-Adapt your questions based on the user's input. Use the following common areas to guide your questions:
+Ask clarifying questions to gather sufficient detail. Focus on understanding the "what" and "why" rather than the "how."
+
+Use the following common areas to guide your questions:
 
 **Core Understanding:**
 
@@ -126,31 +159,61 @@ Adapt your questions based on the user's input. Use the following common areas t
 - Any existing design mockups or UI guidelines to follow?
 - Are there any technical constraints or integration requirements?
 
-**Demo & Proof:**
+**Proof Artifacts:**
 
-- How will we demonstrate this feature works?
-- What proof artifacts will we need (URLs, CLI output, screenshots)?
+- What proof artifacts will demonstrate this feature works (URLs, CLI output, screenshots)?
+- What will each artifact demonstrate about the feature?
 
 **Progressive Disclosure:** Start with Core Understanding, then expand based on feature complexity and user responses.
 
-## Step 3: Context Assessment (Optional)
+### Questions File Format
 
-If the feature involves existing systems, briefly review the codebase and existing docs to understand:
+Follow this format exactly when you create the questions file.
 
-- Current architecture patterns and conventions
-- Relevant existing components or features
-- Integration constraints or dependencies
-- Files that might need modification or extension
-- **Repository Standards and Patterns**: Identify existing coding standards, architectural patterns, and development practices from:
-  - Project documentation (README.md, CONTRIBUTING.md, docs/)
-  - Configuration files (package.json, Cargo.toml, pyproject.toml, etc.)
-  - Existing code structure and naming conventions
-  - Testing patterns and quality assurance practices
-  - Commit message conventions and development workflows
+```markdown
+# [NN] Questions Round 1 - [Feature Name]
 
-**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.
+Please answer each question below (select one or more options, or add your own notes). Feel free to add additional context under any question.
 
-## Step 4: Spec Generation
+## 1. [Question Category/Topic]
+
+[What specific aspect of the feature needs clarification?]
+
+- [ ] (A) [Option description explaining what this choice means]
+- [ ] (B) [Option description explaining what this choice means]
+- [ ] (C) [Option description explaining what this choice means]
+- [ ] (D) [Option description explaining what this choice means]
+- [ ] (E) Other (describe)
+
+## 2. [Another Question Category/Topic]
+
+[What specific aspect of the feature needs clarification?]
+
+- [ ] (A) [Option description explaining what this choice means]
+- [ ] (B) [Option description explaining what this choice means]
+- [ ] (C) [Option description explaining what this choice means]
+- [ ] (D) [Option description explaining what this choice means]
+- [ ] (E) Other (describe)
+```
+
+### Questions File Process
+
+1. **Create Questions File**: Save questions to a file named `[NN]-questions-[N]-[feature-name].md` where `[N]` is the round number (starting at 1, incrementing for each new round).
+2. **Point User to File**: Direct the user to the questions file and instruct them to answer the questions directly in the file.
+3. **STOP AND WAIT**: Do not proceed to Step 5. Wait for the user to indicate they have saved their answers.
+4. **Read Answers**: After the user indicates they have saved their answers, read the file and continue the conversation.
+5. **Follow-Up Rounds**: If answers reveal new questions, create a new questions file with incremented round number (`[NN]-questions-[N+1]-[feature-name].md`) and repeat the process (return to step 3).
+
+**Iterative Process:**
+
+- If a user's answer reveals new questions or areas needing clarification, ask follow-up questions in a new questions file.
+- Build on previous answers - use context from earlier responses to inform subsequent questions.
+- **CRITICAL**: After creating any questions file, you MUST STOP and wait for the user to provide answers before proceeding.
+- Only proceed to Step 5 after:
+  - You have received and reviewed all user answers to clarifying questions
+  - You have enough detail to populate all spec sections (User Stories, Demoable Units with functional requirements, etc.).
+
+## Step 5: Spec Generation
 
 Generate a comprehensive specification using this exact structure:
 
@@ -174,22 +237,31 @@ Generate a comprehensive specification using this exact structure:
 [Focus on tangible progress and WHAT will be demonstrated. Define 2-4 small, end-to-end vertical slices using the format below.]
 
 ### [Unit 1]: [Title]
+
 **Purpose:** [What this slice accomplishes and who it serves]
-**Demo Criteria:** [What will be shown to verify working value]
-**Proof Artifacts:** [Tangible evidence - URLs, CLI commands, test names, screenshots]
+
+**Functional Requirements:**
+- The system shall [requirement 1: clear, testable, unambiguous]
+- The system shall [requirement 2: clear, testable, unambiguous]
+- The user shall [requirement 3: clear, testable, unambiguous]
+
+**Proof Artifacts:**
+- [Artifact type]: [description] demonstrates [what it proves]
+- Example: `Screenshot: `--help` output demonstrates new command exists`
+- Example: `CLI: `command --flag` returns expected output demonstrates feature works`
 
 ### [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
+**Purpose:** [What this slice accomplishes and who it serves]
 
-[Focus on system behavior and WHAT the system must do. Each should start with "The system shall..." or "The user shall..."]
+**Functional Requirements:**
+- The system shall [requirement 1: clear, testable, unambiguous]
+- The system shall [requirement 2: clear, testable, unambiguous]
 
-1. [**Requirement 1**: clear, testable, unambiguous]
-2. [**Requirement 2**: clear, testable, unambiguous]
-3. [**Requirement 3**: clear, testable, unambiguous]
+**Proof Artifacts:**
+- [Artifact type]: [description] demonstrates [what it proves]
+- Example: `Test: MyFeature.test.ts passes demonstrates requirement implementation`
+- Example: `Order PDF: PDF downloaded from https://example.com/order-submitted shows completed flow demonstrates end-to-end functionality`
 
 ## Non-Goals (Out of Scope)
 
@@ -206,12 +278,13 @@ Generate a comprehensive specification using this exact structure:
 ## 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."]
+  If no specific standards are identified, state "Follow established repository patterns and conventions."]
 
 ## Technical Considerations
 
@@ -233,7 +306,7 @@ If no specific standards are identified, state "Follow established repository pa
 2. [Question 2]
 ```
 
-## Step 5: Review and Refinement
+## Step 6: Review and Refinement
 
 After generating the spec, present it to the user and ask:
 
@@ -247,11 +320,10 @@ Iterate based on feedback until the user is satisfied.
 ## Output Requirements
 
 **Format:** Markdown (`.md`)
-**Directory:** Create `./docs/specs/[NN]-spec-[feature-name]/` where `[NN]` is a zero-padded 2-digit sequence number starting from 01 (e.g., `01`, `02`, `03`). For example, `01-spec-user-authentication/`, `02-spec-payment-integration/`, etc.
 **Full Path:** `./docs/specs/[NN]-spec-[feature-name]/[NN]-spec-[feature-name].md`
-**Example:** For feature "user authentication", create directory `01-spec-user-authentication/` and save file as `01-spec-user-authentication.md` inside it
+**Example:** For feature "user authentication", the spec directory would be `01-spec-user-authentication/` with a spec file as `01-spec-user-authentication.md` inside it
 
-## Critical Constraints (Negative Instructions)
+## Critical Constraints
 
 **NEVER:**
 
@@ -265,31 +337,12 @@ Iterate based on feedback until the user is satisfied.
 **ALWAYS:**
 
 - 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
+- Include proof artifacts for each work unit that demonstrate what will be shown
 - Follow identified repository standards and patterns in all requirements
 
 ## What Comes Next
 
 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
-
-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
-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