diff --git a/extensions/assess/README.md b/extensions/assess/README.md index b6af9a2289..857bb42211 100644 --- a/extensions/assess/README.md +++ b/extensions/assess/README.md @@ -26,7 +26,8 @@ flowchart LR A[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//`. 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 Conventions A *slug* is the per-idea directory name under `.specify/assessments/`. It is the handle all five commands share.