feat(prompts): harden SDD planning, clarification, and review workflows

README.md

@@ -19,7 +19,7 @@
 This repository provides **structured prompts** (Markdown files) that guide AI assistants through a complete software development workflow:
 
 - **Define intent**: generate a reviewed spec with clear demo criteria
-- **Plan**: break work into demoable tasks and subtasks
+- **Plan**: break work into demoable tasks and subtasks, then run a planning audit gate
 - **Execute**: implement with checkpoints and proof artifacts
 - **Validate**: verify implementation against the spec with evidence
 
@@ -92,24 +92,24 @@ Copy the contents of a prompt file directly from `prompts/` and paste it into yo
 
 ### Quick "try it" flow
 
-1. Run `/SDD-1-generate-spec` and describe the feature you want.
-2. Next, use `/SDD-2-generate-task-list-from-spec` pointing it at the generated spec.
-3. Then execute `/SDD-3-manage-tasks` to implement tasks one at a time (creating proof artifacts before commits).
+1. Run `/SDD-1-generate-spec` and describe the feature you want. If the AI determines material clarification is needed, answer the generated questions file before continuing.
+2. Next, use `/SDD-2-generate-task-list-from-spec` pointing it at the generated spec; complete task generation, baseline planning commit, planning audit, and user-approved remediation if needed.
+3. Then execute `/SDD-3-manage-tasks` to implement tasks one at a time (creating proof artifacts before commits) after the SDD-2 audit required gates pass.
 4. Finally, apply `/SDD-4-validate-spec-implementation` to verify the implementation against the spec.
 
 ## Details for the 4-step workflow
 
 Each step uses a different prompt file and produces specific artifacts in `docs/specs/`.
 
 1. **Generate a spec** ([`prompts/SDD-1-generate-spec.md`](./prompts/SDD-1-generate-spec.md))
-   - **What it does**: asks structured clarifying questions, checks scope, and writes a junior-friendly spec with demo criteria
-   - **Output**: `docs/specs/[NN]-spec-[feature-name]/[NN]-spec-[feature-name].md`
+   - **What it does**: checks scope, researches current best practices for relevant technologies, determines whether clarification is needed, optionally creates a questions file for material ambiguities with recommended answers and justification notes, and writes a junior-friendly spec with demo criteria
+   - **Output**: `docs/specs/[NN]-spec-[feature-name]/[NN]-spec-[feature-name].md` and, when needed, `docs/specs/[NN]-spec-[feature-name]/[NN]-questions-[N]-[feature-name].md`
    - **Why**: aligns humans + AI on what to build before any code changes
 
 2. **Generate a task list** ([`prompts/SDD-2-generate-task-list-from-spec.md`](./prompts/SDD-2-generate-task-list-from-spec.md))
-   - **What it does**: converts the spec into parent tasks (demoable units) + detailed subtasks with a "Relevant Files" section
-   - **Output**: `docs/specs/[NN]-spec-[feature-name]/[NN]-tasks-[feature-name].md`
-   - **Why**: creates an actionable plan with clear checkpoints and reviewable scope
+   - **What it does**: converts the spec into parent tasks (demoable units) + detailed subtasks, creates a baseline planning commit, runs a planning audit gate, and requires user-approved remediation before implementation handoff
+   - **Output**: `docs/specs/[NN]-spec-[feature-name]/[NN]-tasks-[feature-name].md` and `docs/specs/[NN]-spec-[feature-name]/[NN]-audit-[feature-name].md`
+   - **Why**: catches planning defects early and improves downstream validation readiness
 
 3. **Manage tasks (implementation loop)** ([`prompts/SDD-3-manage-tasks.md`](./prompts/SDD-3-manage-tasks.md))
    - **What it does**: guides execution with checkpoints, verification checklists, and proof artifacts created **before** each commit
@@ -126,6 +126,7 @@ Each step uses a different prompt file and produces specific artifacts in `docs/
 ## Highlights
 
 - **Prompt-first workflow:** Use curated prompts to go from idea → spec → task list → implementation-ready backlog.
+- **Planning quality gate:** SDD-2 includes a mandatory audit with human-approved remediation before implementation starts.
 - **Predictable delivery:** Every step emphasizes demoable slices, proof artifacts, and collaboration with junior developers in mind.
 - **No dependencies required:** The prompts are plain Markdown files that work with any AI assistant.
 - **Context verification:** Built-in emoji markers (SDD1️⃣-SDD4️⃣) detect when AI responses follow critical instructions, helping identify context rot issues early.
@@ -136,7 +137,8 @@ Spec-Driven Development (SDD) keeps AI collaborators and human developers aligne
 
 ## Guiding Principles
 
-- **Clarify intent before delivery:** The spec prompt enforces clarifying questions so requirements are explicit and junior-friendly.
+- **Clarify intent before delivery:** The spec prompt requires a clarification sufficiency check so material ambiguities are resolved before planning, while minor uncertainty can remain explicit in the spec.
+- **Ground plans in current guidance:** The spec prompt combines repository pattern discovery with current external best-practice research for material technologies, then asks follow-up questions when those signals still leave meaningful choices open.
 - **Ship demoable slices:** Every stage pushes toward thin, end-to-end increments with clear demo criteria and proof artifacts.
 - **Make work transparent:** Tasks live in versioned markdown files so stakeholders can review, comment, and adjust scope anytime.
 - **Progress one slice at a time:** The management prompt enforces single-threaded execution to reduce churn and unfinished work-in-progress.
@@ -147,12 +149,16 @@ Spec-Driven Development (SDD) keeps AI collaborators and human developers aligne
 Each prompt writes Markdown outputs into `docs/specs/[NN]-spec-[feature-name]/` (where `[NN]` is a zero-padded 2-digit number: 01, 02, 03, etc.), giving you a lightweight backlog that is easy to review, share, and implement.
 
 - **Specs:** `docs/specs/[NN]-spec-[feature-name]/[NN]-spec-[feature-name].md`
+- **Questions files (when needed):** `docs/specs/[NN]-spec-[feature-name]/[NN]-questions-[N]-[feature-name].md`
 - **Task lists:** `docs/specs/[NN]-spec-[feature-name]/[NN]-tasks-[feature-name].md`
+- **Audit reports:** `docs/specs/[NN]-spec-[feature-name]/[NN]-audit-[feature-name].md`
 - **Proof artifacts:** `docs/specs/[NN]-spec-[feature-name]/[NN]-proofs/[NN]-task-[TT]-proofs.md`
 - **Validation reports:** `docs/specs/[NN]-spec-[feature-name]/[NN]-validation-[feature-name].md`
 
 Example directory structure:
 
+`[NN]-questions-[N]-[feature-name].md` is optional and appears only when the spec prompt determines a clarification round is required.
+
 ```bash
 docs/specs
 └── 01-spec-feature-name
@@ -162,6 +168,7 @@ docs/specs
     │   ├── 01-task-03-proofs.md
     │   └── 01-task-04-proofs.md
     ├── 01-questions-1-feature-name.md
+    ├── 01-audit-feature-name.md
     ├── 01-spec-feature-name.md
     ├── 01-tasks-feature-name.md
     └── 01-validation-feature-name.md

docs/faq.md

@@ -38,6 +38,14 @@ Commands and scaffolds steer teams toward skateboard‑to‑scooter increments:
 
 Yes. You can keep everything in a single repository using Markdown files with no external dependencies. Tool integrations and multi‑repo features are optional.
 
+## How does the workflow prevent low-quality planning from reaching implementation?
+
+The planning step includes a mandatory audit gate after task generation. The AI produces an audit report that checks requirement coverage, proof artifact quality, repository standards consistency, open-question handling, and context alignment against related docs (such as specs, PRDs, or roadmaps). Required failures block implementation handoff until remediated.
+
+## Is remediation fully automated?
+
+No. Remediation is human-in-the-loop. The AI presents findings and a concrete remediation plan, then waits for explicit user approval before editing planning artifacts. After approved edits, the AI reruns the audit. This loop repeats until required audit gates pass.
+
 ## Can solo developers use it?
 
 Yes. The same context and work‑breakdown helpers make it easy to pause and resume personal projects while keeping AI assistance on track.