Skip to content

Commit 146332c

Browse files
committed
docs(assess): align every clarification path with reassess-through-decide
Copilot flagged three places where the old wording survived the report-and-stop rework: the decide command's opening summary still sent a needs-clarification verdict back to an earlier stage, the extension README's clarification prose still had the agent revise decision.md in place, and the agentic-assessment reference page did the same. All three now route reassessment through re-running decide against the refined artifacts, with earlier-stage reruns staying the exception, and the contract test also rejects the stale opening summary. Assisted-by: Claude Code (model: Claude Fable 5, supervised)
1 parent c4ed11d commit 146332c

4 files changed

Lines changed: 16 additions & 9 deletions

File tree

‎docs/reference/agentic-assessment.md‎

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,8 @@ directory exists.
6060

6161
Existing artifacts are not overwritten without confirmation. In automated mode,
6262
commands refuse to overwrite them. For routine clarification, refine the existing
63-
artifact rather than rerunning the command.
63+
artifact rather than rerunning its command; the verdict is then updated by
64+
re-running `decide`, which asks before overwriting the previous `decision.md`.
6465

6566
## Decisions and evidence
6667

@@ -82,11 +83,14 @@ A documented decision to stop is a useful result.
8283
Run each stage once in the usual flow. To resolve clarification markers or a
8384
`needs-clarification` verdict, edit the affected Markdown directly or ask the
8485
agent in free-form chat to incorporate the missing facts. Preserve sources and
85-
confidence tags, then review dependent artifacts and revise `decision.md` as
86-
needed. This is artifact refinement, not repeated command execution.
87-
88-
Rerunning an earlier command is reserved for exceptions such as a wrong slug or
89-
discarded draft. See the
86+
confidence tags and review dependent wording in the refined artifacts.
87+
`decision.md` itself is not revised in place: once the refined artifacts answer
88+
the blocking questions, request reassessment by re-running the decide command,
89+
which rebuilds the scorecard, verdict, and handoff from the updated artifacts
90+
and asks before overwriting the previous decision.
91+
92+
Rerunning a command earlier than decide is reserved for exceptions such as a
93+
wrong slug or discarded draft. See the
9094
[guided clarification example](../guides/assessment.md#resolve-unknowns-by-refining-the-artifacts).
9195

9296
## Handoff and guardrails

‎extensions/assess/README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -65,11 +65,11 @@ Resolve them by refining the existing file:
6565
1. **Edit the Markdown directly** (fill in the missing metric, owner, constraint, and so on), or
6666
2. **Ask the agent in free-form chat** to incorporate the missing information into that artifact.
6767

68-
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.
68+
Then ask whether the new information clears the blocker and to update any downstream wording in the refined artifact that depended on it. `decision.md` is the exception — it is rebuilt by the command, not edited in place: once the refined artifacts answer the blocking questions, request reassessment by re-running `/speckit-assess-decide`. It rebuilds the scorecard, rationale, verdict, and handoff from the updated artifacts, and asks before overwriting the previous decision.
6969

7070
When you add evidence, keep the source and confidence tags the research stage already uses (`ASSUMPTION` vs cited claims). Do not invent citations.
7171

72-
Rerunning an earlier assessment command is the exception (for example after a wrong slug or a discarded draft), not the default path for answering clarification markers.
72+
Rerunning an assessment command earlier than `decide` is the exception (for example after a wrong slug or a discarded draft), not the default path for answering clarification markers.
7373

7474
## Slug Conventions
7575

‎extensions/assess/commands/speckit.assess.decide.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ description: "Apply a go / needs-clarification / kill gate and hand survivors of
44

55
# Decide: Go, Clarify, or Kill
66

7-
Render the **verdict** on an assessed idea and record it at `.specify/assessments/<slug>/decision.md`. This is the gate between discovery and delivery: a **go** hands the idea off to `__SPECKIT_COMMAND_SPECIFY__`; a **kill** stops it with a documented reason; **needs-clarification** sends it back to an earlier stage. Killing ideas here is a success, not a failure — that is the entire point of an assessment pipeline.
7+
Render the **verdict** on an assessed idea and record it at `.specify/assessments/<slug>/decision.md`. This is the gate between discovery and delivery: a **go** hands the idea off to `__SPECKIT_COMMAND_SPECIFY__`; a **kill** stops it with a documented reason; **needs-clarification** reports the blocking unknowns and waits for the user to refine the artifacts and re-run `decide`. Killing ideas here is a success, not a failure — that is the entire point of an assessment pipeline.
88

99
Decide **judges; it does not spec or build.** It weighs the evidence already gathered and commits to a defensible call.
1010

‎tests/extensions/assess/test_assess_extension.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,9 @@ def test_decide_needs_clarification_step_reports_and_stops(self):
9797
for line in text.splitlines()
9898
if line.lstrip().startswith("- **needs-clarification** →")
9999
)
100+
# The opening summary must not contradict the report-back step by
101+
# sending the idea back to an earlier stage unconditionally.
102+
assert "sends it back to an earlier stage" not in text
100103
# decide reports and stops; it does not resolve the unknowns itself.
101104
assert "report the blocking questions and stop" in step
102105
# Refinement happens in the artifact, driven by the user.

0 commit comments

Comments
 (0)