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

[ryderstorm]

Summary

This branch significantly strengthens the prompt-driven workflow across planning, spec generation, implementation evidence, and validation. The net effect is a more opinionated and reviewable SDD loop that blocks weak planning earlier, asks fewer unnecessary questions during spec generation, and produces artifacts that are easier for humans to inspect.

What changed

1. Add a mandatory planning-audit checkpoint in SDD-2

• insert a required audit between task generation and implementation handoff
• require human-approved remediation before planning defects can be corrected
• allow existing spec/task work to resume through audit/remediation without regenerating the plan
• add compact Gateboard-first reporting, re-audit deltas, and a reset/restart recommendation when planning debt is too high

2. Make planning audit decisions more reliable

• require explicit repository-standards discovery before audit decisions are made
• add a required standards evidence table so audit conclusions are grounded in actual repo guidance files instead of inferred behavior
• add a chain-of-verification pass before handing work to SDD-3
• clarify failure handling when standards files or other planning evidence are missing
• tighten proof-artifact and requirement-to-test expectations during task planning

3. Improve SDD-1 spec generation and clarification behavior

• replace the old always-generate-a-questions-file behavior with a clarification sufficiency check
• allow SDD-1 to proceed directly to spec generation when the request is already clear enough
• still force a questions file when ambiguity is material, requirements would be guessed, or current best practices leave meaningful approach choices open
• require generated questions files to include recommended answers and rationale so users get guided choices instead of a flat questionnaire
• add example guidance showing the intended recommendation style

4. Ground specs in current external guidance, not just repo patterns

• require latest-standards research for technologies that materially affect the spec
• prefer recent official or primary-source guidance when available
• route repo-pattern-vs-modern-guidance conflicts back through the clarification flow when the right direction is unclear
• require technical considerations in the spec to incorporate relevant current best practices or call out intentional deviations

5. Improve task and proof artifact review UX

• change the SDD-2 Relevant Files section from a bullet list to a markdown table for easier scanability
• require SDD-3 proof artifacts to lead with human-readable context instead of starting with raw command output
• require descriptive proof titles, summary-first layout, per-artifact "what it proves / why it matters" framing, and short reviewer conclusions
• require screenshot paths to be shown above inline embedded images so proof docs support faster visual review
• add an example proof document shape that demonstrates the expected format

6. Strengthen validation semantics in SDD-4

• refine file-integrity handling so unmapped core/source drift is blocker-level, while supporting-file linkage gaps are documented without automatically failing validation
• tighten evidence-quality expectations so validation looks at proof usability, not just proof existence
• explicitly check for descriptive proof titles, front-loaded context, inline screenshot presentation, and explanation before raw evidence
• add clearer examples of non-blocking reviewability issues in validation output

7. Update docs to match the new workflow

• update README.md to describe the audit-first planning flow, conditional questions files, current-standards grounding, and generated artifact set
• extend docs/faq.md with planning-audit/remediation behavior so the docs tell the same story as the prompts

Why this matters

Before this branch, the workflow was easier to move through quickly, but it also allowed weak planning handoffs, over-eager question generation, and proof artifacts that were technically present but slow for humans to validate. These changes push the workflow toward:

• better planning discipline before implementation starts
• fewer unnecessary clarification loops
• more grounded technical direction for modern stacks
• faster human review of both plans and proof artifacts
• clearer validation outcomes when evidence quality is weak

Files changed

• README.md
• docs/faq.md
• prompts/SDD-1-generate-spec.md
• prompts/SDD-2-generate-task-list-from-spec.md
• prompts/SDD-3-manage-tasks.md
• prompts/SDD-4-validate-spec-implementation.md

Validation

This is a prompt/docs-only branch. Validation focused on prompt/doc linting and consistency checks.

• pre-commit run --files "prompts/SDD-1-generate-spec.md" "README.md"
• pre-commit run --files "prompts/SDD-3-manage-tasks.md" "prompts/SDD-4-validate-spec-implementation.md"
• pre-commit run --files "prompts/SDD-2-generate-task-list-from-spec.md"

Reviewer notes

• this PR intentionally spans multiple prompts because the changes are workflow-coupled: planning audit behavior affects implementation handoff, proof artifacts affect validation, and spec clarification changes affect downstream planning quality
• there are no application/runtime code changes in this branch; the impact is entirely in workflow behavior and generated markdown artifacts

[PaulHLiatrio]

I wonder if we're leaning towards giving it too much freedom in this instance here; I reflect on when my AI ignored all my skills because it felt it could do it better and even called itself "overconfident".

I would almost prefer that it ask some clarifying questions about approach but mark what it thinks we want, and that could potentially introduce other methods we weren't aware of to the development process.

I can't count the amount of times I was on client and SDD asked me some questions, and I actually had to pull up with the team to discuss the approach because I hadn't considered the other options.

[PaulHLiatrio]

Adding on to this -- that being said maybe that can be up to the writer to include that in their prompt when generating the SDD. This could be the default, but if you want to hear different design choices you can ask for that.

[ryderstorm]

This is a great callout, and your example is an important use case.

In my practice with these changes, i've seen it ask questions when i've given it very little to start with, and avoid it when things are good enough already. I've been pleased with the results so far, it's giving the right level of interaction. Let me know if you think it needs some tweaking after you've run it through a few times.

[PaulHLiatrio]

I'd almost want it to provide some reading material as well to speed up the decision making process if you're unfamiliar with the material.

[ryderstorm]

interesting idea! i worry that leans too much into using SDD to just build anything, tho - the user should have some familiarity with what they're trying to build. SDD is designed for inputs that are already groomed, at least a little.

[PaulHLiatrio]

Yeah it was mostly the "junior-friendly spec" portion that brought this thought to me. In my mind part of Juniors job is learning more about what's being done, so helping with that process would be a part of making it "junior-friendly"

[leehopper]

I know AGENTS.md is becoming the standard, but is it worth still including CLAUDE.md for now as well?

[ryderstorm]

good call! this section is a little too strict, too. It should start with something like

Examples of required search targets (if present): 

[maddiehawkins]

FWIW mine still found CLAUDE.md and some other files like .gitlab-ci.yml that weren't explicitly listed! It noted that AGENTS.md was not in the repository, but didn't fail because of that