π« Toolkit to help you get started with SDD or any other process!
docs: resolve assess clarifications by editing artifacts in place (#4402)
Gyanu Mayank5c4531268653
diff --git a/extensions/assess/README.md b/extensions/assess/README.mdindex b6af9a228..857bb4221 100644--- a/extensions/assess/README.md+++ b/extensions/assess/README.md@@ -26,7 +26,8 @@ flowchart LRA[intake] --> R[research] --> D[define] --> S[shape] --> C{decide}C -->|go| SPEC[/speckit.specify/]C -->|kill| X[closed, recorded]- C -.->|needs-clarification: revisit the named earlier stage| A+ C -.->|needs-clarification| F[refine named artifact in place]+ F -.->|then revise decision.md| C```## Commands@@ -45,6 +46,27 @@ Stages are meant to run in order but are not rigidly gated:- `shape` requires `problem.md`.- `decide` requires `problem.md`; a `go` verdict expects `concept.md` (otherwise it is downgraded to `needs-clarification`).+## Resolving clarifications++The normal process is sequential and each command usually runs **once**:++```text+intake β research β define β shape β decide+```++Each stage writes a Markdown artifact under `.specify/assessments/<slug>/`. Those files stay editable. The commands keep their existing output templates: they do not rewrite an earlier artifact or perform that refinement themselves. `[NEEDS CLARIFICATION: β¦]` markers are gaps in the artifact, not a signal to regenerate the whole stage from scratch.++Resolve them by refining the existing file:++1. **Edit the Markdown directly** (fill in the missing metric, owner, constraint, and so on), or+2. **Ask the agent in free-form chat** to incorporate the missing information into that artifact.++Then ask whether the new information clears the blocker and to update any downstream wording that depended on it. That includes `decision.md`: you can supply the missing facts and ask the agent to revise the scorecard, rationale, verdict, or handoff. That is artifact refinement, not command iteration.++When you add evidence, keep the source and confidence tags the research stage already uses (`ASSUMPTION` vs cited claims). Do not invent citations.++Rerunning an earlier `speckit.assess.*` command is the exception (for example after a wrong slug or a discarded draft), not the default path for answering clarification markers.+## Slug ConventionsA *slug* is the per-idea directory name under `.specify/assessments/`. It is the handle all five commands share.