Skip to content

πŸ’« 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.md
index b6af9a228..857bb4221 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/<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 Conventions
A *slug* is the per-idea directory name under `.specify/assessments/`. It is the handle all five commands share.