From ee4c8b2576ae85eb2ab64f0c16c3a281ac241af1 Mon Sep 17 00:00:00 2001 From: aarjang <115079190+aarjang@users.noreply.github.com> Date: Mon, 9 Nov 2026 10:01:54 +0330 Subject: [PATCH 1/5] docs(assess): align decide's needs-clarification step with the assessment guide docs/guides/assessment.md says answering a [NEEDS CLARIFICATION] question is artifact refinement: edit the Markdown in place or ask in free-form chat, and re-run a stage only as an exception. The decide command's report-back template still told the agent to re-run the named stage, so tools offering a next step had to pick a side, and a re-run also triggers the overwrite confirmation -- one more prompt than the guide describes. PR #4402 aligned the README and the guide but left this line behind. Reword the needs-clarification next step to match the guide and the README's own refine path: update the named artifact in place, revise decision.md if that clears the blocker, and re-run a stage only when the answer changes that stage's inputs. Patch-bump the assess extension to 1.0.3 in extension.yml, the core catalog, and the assess bundle, which the bundled-extension-versions contract test keeps in sync. Fixes #5325 Assisted-by: Claude Code (model: Claude Fable 5, supervised) --- bundles/assess/bundle.yml | 2 +- extensions/assess/commands/speckit.assess.decide.md | 2 +- extensions/assess/extension.yml | 2 +- extensions/catalog.json | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/bundles/assess/bundle.yml b/bundles/assess/bundle.yml index 5466b2ce6d..0bd2858fb2 100644 --- a/bundles/assess/bundle.yml +++ b/bundles/assess/bundle.yml @@ -17,7 +17,7 @@ requires: provides: extensions: - id: "assess" - version: "1.0.2" + version: "1.0.3" workflows: - id: "assess" version: "1.0.0" diff --git a/extensions/assess/commands/speckit.assess.decide.md b/extensions/assess/commands/speckit.assess.decide.md index 2f1900523d..abbdc8e6f2 100644 --- a/extensions/assess/commands/speckit.assess.decide.md +++ b/extensions/assess/commands/speckit.assess.decide.md @@ -85,7 +85,7 @@ Write `ASSESS_DIR/decision.md`: - The path `.specify/assessments//decision.md`. - The next step, by verdict: - **go** → `__SPECKIT_COMMAND_SPECIFY__` using the handoff summary as its input. - - **needs-clarification** → re-run the named stage (e.g. `__SPECKIT_COMMAND_ASSESS_RESEARCH__ slug=`). + - **needs-clarification** → refine the named artifact in place with the missing information (edit the Markdown directly, or ask in free-form chat), then revise `decision.md` if that clears the blocker. Re-run a stage (e.g. `__SPECKIT_COMMAND_ASSESS_RESEARCH__ slug=`) only when the answer changes that stage's inputs. - **kill** → none; the assessment is closed. The record remains for future reference. ## Guardrails diff --git a/extensions/assess/extension.yml b/extensions/assess/extension.yml index 1b6341e347..3ee1a32e55 100644 --- a/extensions/assess/extension.yml +++ b/extensions/assess/extension.yml @@ -3,7 +3,7 @@ schema_version: "1.0" extension: id: assess name: "Idea Assessment Pipeline" - version: "1.0.2" + version: "1.0.3" description: "Assess an idea before Spec-Driven Development via intake, research, define, shape, and decide. A go verdict hands off to /speckit.specify; a kill closes it. Lives under .specify/assessments//" category: "process" effect: "read-write" diff --git a/extensions/catalog.json b/extensions/catalog.json index 10ad367461..c67498ec67 100644 --- a/extensions/catalog.json +++ b/extensions/catalog.json @@ -20,7 +20,7 @@ "assess": { "name": "Idea Assessment Pipeline", "id": "assess", - "version": "1.0.2", + "version": "1.0.3", "description": "Assess an idea before Spec-Driven Development via intake, research, define, shape, and decide. A go verdict hands off to /speckit.specify; a kill closes it. Lives under .specify/assessments//", "author": "spec-kit-core", "repository": "https://github.com/github/spec-kit", From 0e94e5f806e174808a119e69f817ba33e9ab4949 Mon Sep 17 00:00:00 2001 From: aarjang <115079190+aarjang@users.noreply.github.com> Date: Mon, 9 Nov 2026 10:17:55 +0330 Subject: [PATCH 2/5] test(assess): pin decide's needs-clarification step to in-place refinement Review asked for focused coverage of the decide report-back contract: the existing assess tests verify layout, catalog registration, resolution, and installation, so they would still pass if the needs-clarification guidance regressed to "re-run the named stage". Pin the guide's side on the report-back arrow line: the next step names in-place refinement, never the unconditional re-run, and any re-run mention comes after the refinement wording and stays conditional ("only when"). The verdict definition and the decision.md output template deliberately stay untouched, as #4402 established. The test fails against the pre-#5325 wording and passes with it. Assisted-by: Claude Code (model: Claude Fable 5, supervised) --- .../assess/test_assess_extension.py | 33 +++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/tests/extensions/assess/test_assess_extension.py b/tests/extensions/assess/test_assess_extension.py index 138652b81f..9c1718a4d1 100644 --- a/tests/extensions/assess/test_assess_extension.py +++ b/tests/extensions/assess/test_assess_extension.py @@ -69,6 +69,39 @@ def test_command_files_exist(self): cmd = EXT_DIR / "commands" / f"{name}.md" assert cmd.is_file(), f"Missing command file: {cmd}" + def test_decide_needs_clarification_step_refines_in_place(self): + """The decide report-back must match the assessment guide (#5325). + + docs/guides/assessment.md says answering a [NEEDS CLARIFICATION] + question is artifact refinement -- edit the Markdown in place -- and + that re-running a command is an exception. The decide command used to + tell the agent the opposite ("re-run the named stage"), so tools + offering a next-step answer box had to pick a side, and a re-run also + triggers the overwrite confirmation. Pin the guide's side: the + needs-clarification next step names in-place refinement, and any + mention of re-running is conditional on the answer changing a stage's + inputs rather than the unconditional next step. + """ + text = (EXT_DIR / "commands" / "speckit.assess.decide.md").read_text( + encoding="utf-8" + ) + # The report-back next step is the arrow line; the verdict definition + # and the decision.md output template also mention the verdict and are + # deliberately untouched (#4402 kept the output template). + step = next( + line + for line in text.splitlines() + if line.lstrip().startswith("- **needs-clarification** →") + ) + assert "refine the named artifact in place" in step + assert "re-run the named stage" not in step + # A re-run may be offered only as the guarded exception, never first: + # the refinement wording must precede any re-run mention. + rerun = step.lower().find("re-run") + assert rerun == -1 or rerun > step.find("refine the named artifact") + if rerun != -1: + assert "only when" in step[rerun:] + # ── Catalog registration ───────────────────────────────────────────────────── From c4ed11d979f1eb3194f645de43cd977ed741cb70 Mon Sep 17 00:00:00 2001 From: aarjang <115079190+aarjang@users.noreply.github.com> Date: Tue, 10 Nov 2026 09:23:06 +0330 Subject: [PATCH 3/5] docs(assess): keep decide's report-and-stop separate from reassessment Per maintainer direction on #5329: a needs-clarification verdict reports the blocking questions and stops; the user refines the named artifact in place (direct edit or explicitly directing an agent) and then requests reassessment by re-running the decide command against the updated artifacts. Drop the interim "revise decision.md" wording that let the agent edit the decision in place, align the README flowchart and the assessment guide's refinement section with the same separation, and repin the contract test to reject both the old unconditional stage re-run and the interim in-place revision. Assisted-by: Claude Code (model: Claude Fable 5, supervised) --- docs/guides/assessment.md | 15 +++--- extensions/assess/README.md | 4 +- .../assess/commands/speckit.assess.decide.md | 2 +- .../assess/test_assess_extension.py | 48 +++++++++++-------- 4 files changed, 40 insertions(+), 29 deletions(-) diff --git a/docs/guides/assessment.md b/docs/guides/assessment.md index 1a9d433bb7..1e730d27de 100644 --- a/docs/guides/assessment.md +++ b/docs/guides/assessment.md @@ -77,7 +77,7 @@ The agent records the scorecard, rationale, and verdict in `decision.md`. | Verdict | What it means | What to do | | --- | --- | --- | | `go` | The problem and evidence are adequate and a concept is recommended | Decide whether to act; optionally hand a software idea to SDD | -| `needs-clarification` | Specific unknowns still block a defensible decision | Refine the affected artifacts with the missing information | +| `needs-clarification` | Specific unknowns still block a defensible decision | Refine the affected artifacts, then re-run `/speckit-assess-decide` | | `kill` | The idea is not worth pursuing now | Keep the recorded rationale; stopping is a successful outcome | All five artifacts live under `.specify/assessments/offline-mode/`. None of the @@ -90,14 +90,15 @@ The usual flow runs each command once. When an artifact contains in free-form chat to incorporate the missing information: ```text -Update .specify/assessments/offline-mode/problem.md with these confirmed success metrics: . Update any dependent wording and revise decision.md if this resolves the blocker. Preserve source and confidence tags. +Update .specify/assessments/offline-mode/problem.md with these confirmed success metrics: . Update any dependent wording. Preserve source and confidence tags. ``` -Do not automatically regenerate the entire stage. Ask the agent to review -whether the new facts clear the blocker and revise the downstream scorecard, -verdict, or handoff accordingly. Rerunning a command is an exception, such as -replacing a discarded draft, and existing artifacts must not be overwritten -without confirmation. +Do not automatically regenerate the entire stage. Once the refined artifacts +answer the blocking questions, request reassessment by re-running +`/speckit-assess-decide`: it rebuilds the scorecard, verdict, and handoff from +the updated artifacts, and asks before overwriting the existing `decision.md`. +Rerunning an earlier command is an exception, such as replacing a discarded +draft, and existing artifacts must not be overwritten without confirmation. ## Optional handoff to SDD diff --git a/extensions/assess/README.md b/extensions/assess/README.md index 655c5ae455..b01a3f2e6d 100644 --- a/extensions/assess/README.md +++ b/extensions/assess/README.md @@ -26,8 +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| F[refine named artifact in place] - F -.->|then revise decision.md| C + C -.->|needs-clarification| F[user refines named artifact in place] + F -.->|then re-run decide| C ``` ## Commands diff --git a/extensions/assess/commands/speckit.assess.decide.md b/extensions/assess/commands/speckit.assess.decide.md index abbdc8e6f2..7b0cf6443c 100644 --- a/extensions/assess/commands/speckit.assess.decide.md +++ b/extensions/assess/commands/speckit.assess.decide.md @@ -85,7 +85,7 @@ Write `ASSESS_DIR/decision.md`: - The path `.specify/assessments//decision.md`. - The next step, by verdict: - **go** → `__SPECKIT_COMMAND_SPECIFY__` using the handoff summary as its input. - - **needs-clarification** → refine the named artifact in place with the missing information (edit the Markdown directly, or ask in free-form chat), then revise `decision.md` if that clears the blocker. Re-run a stage (e.g. `__SPECKIT_COMMAND_ASSESS_RESEARCH__ slug=`) only when the answer changes that stage's inputs. + - **needs-clarification** → report the blocking questions and stop — do not resolve them here. The user supplies the missing information by refining the named artifact in place (editing the Markdown directly, or explicitly directing an agent), then requests reassessment by re-running `__SPECKIT_COMMAND_ASSESS_DECIDE__ slug=`, which consumes the updated artifacts. Re-run an earlier stage (e.g. `__SPECKIT_COMMAND_ASSESS_RESEARCH__ slug=`) only when the answer changes that stage's inputs. - **kill** → none; the assessment is closed. The record remains for future reference. ## Guardrails diff --git a/tests/extensions/assess/test_assess_extension.py b/tests/extensions/assess/test_assess_extension.py index 9c1718a4d1..c2f5e8b867 100644 --- a/tests/extensions/assess/test_assess_extension.py +++ b/tests/extensions/assess/test_assess_extension.py @@ -69,18 +69,22 @@ def test_command_files_exist(self): cmd = EXT_DIR / "commands" / f"{name}.md" assert cmd.is_file(), f"Missing command file: {cmd}" - def test_decide_needs_clarification_step_refines_in_place(self): - """The decide report-back must match the assessment guide (#5325). - - docs/guides/assessment.md says answering a [NEEDS CLARIFICATION] - question is artifact refinement -- edit the Markdown in place -- and - that re-running a command is an exception. The decide command used to - tell the agent the opposite ("re-run the named stage"), so tools - offering a next-step answer box had to pick a side, and a re-run also - triggers the overwrite confirmation. Pin the guide's side: the - needs-clarification next step names in-place refinement, and any - mention of re-running is conditional on the answer changing a stage's - inputs rather than the unconditional next step. + def test_decide_needs_clarification_step_reports_and_stops(self): + """The decide report-back must keep refinement and reassessment apart + (#5325, maintainer direction on PR #5329). + + A needs-clarification verdict means decide reports the blocking + questions and stops. The *user* supplies the missing information by + refining the named artifact in place (editing the Markdown directly, + or explicitly directing an agent), and reassessment then goes through + re-running the decide command against the updated artifacts -- never + through the agent revising decision.md on its own. The command used to + say the unconditional next step was "re-run the named stage" (skipping + refinement); an interim wording swung the other way and told the agent + to "revise decision.md" in place (skipping the command). Pin the + middle: refinement is in place and user-driven, reassessment is an + explicit decide re-run, and re-running an *earlier* stage stays the + guarded exception. """ text = (EXT_DIR / "commands" / "speckit.assess.decide.md").read_text( encoding="utf-8" @@ -93,14 +97,20 @@ def test_decide_needs_clarification_step_refines_in_place(self): for line in text.splitlines() if line.lstrip().startswith("- **needs-clarification** →") ) - assert "refine the named artifact in place" in step + # decide reports and stops; it does not resolve the unknowns itself. + assert "report the blocking questions and stop" in step + # Refinement happens in the artifact, driven by the user. + assert "refining the named artifact in place" in step + # Reassessment goes through the command, not in-place decision edits. + assert "__SPECKIT_COMMAND_ASSESS_DECIDE__" in step + assert "revise `decision.md`" not in step assert "re-run the named stage" not in step - # A re-run may be offered only as the guarded exception, never first: - # the refinement wording must precede any re-run mention. - rerun = step.lower().find("re-run") - assert rerun == -1 or rerun > step.find("refine the named artifact") - if rerun != -1: - assert "only when" in step[rerun:] + # An earlier-stage re-run may be offered only as the guarded + # exception, after the decide re-run, never as the default next step. + decide_rerun = step.find("__SPECKIT_COMMAND_ASSESS_DECIDE__") + earlier = step.find("Re-run an earlier stage") + assert earlier != -1 and earlier > decide_rerun + assert "only when" in step[earlier:] # ── Catalog registration ───────────────────────────────────────────────────── From 146332c0f4eab02c0b755d41b78c8ba991b5b9c0 Mon Sep 17 00:00:00 2001 From: aarjang <115079190+aarjang@users.noreply.github.com> Date: Mon, 16 Nov 2026 14:24:07 +0330 Subject: [PATCH 4/5] 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) --- docs/reference/agentic-assessment.md | 16 ++++++++++------ extensions/assess/README.md | 4 ++-- .../assess/commands/speckit.assess.decide.md | 2 +- tests/extensions/assess/test_assess_extension.py | 3 +++ 4 files changed, 16 insertions(+), 9 deletions(-) diff --git a/docs/reference/agentic-assessment.md b/docs/reference/agentic-assessment.md index c65dd54f6b..050ad23170 100644 --- a/docs/reference/agentic-assessment.md +++ b/docs/reference/agentic-assessment.md @@ -60,7 +60,8 @@ directory exists. Existing artifacts are not overwritten without confirmation. In automated mode, commands refuse to overwrite them. For routine clarification, refine the existing -artifact rather than rerunning the command. +artifact rather than rerunning its command; the verdict is then updated by +re-running `decide`, which asks before overwriting the previous `decision.md`. ## Decisions and evidence @@ -82,11 +83,14 @@ A documented decision to stop is a useful result. Run each stage once in the usual flow. To resolve clarification markers or a `needs-clarification` verdict, edit the affected Markdown directly or ask the agent in free-form chat to incorporate the missing facts. Preserve sources and -confidence tags, then review dependent artifacts and revise `decision.md` as -needed. This is artifact refinement, not repeated command execution. - -Rerunning an earlier command is reserved for exceptions such as a wrong slug or -discarded draft. See the +confidence tags and review dependent wording in the refined artifacts. +`decision.md` itself is not revised in place: once the refined artifacts answer +the blocking questions, request reassessment by re-running the decide command, +which rebuilds the scorecard, verdict, and handoff from the updated artifacts +and asks before overwriting the previous decision. + +Rerunning a command earlier than decide is reserved for exceptions such as a +wrong slug or discarded draft. See the [guided clarification example](../guides/assessment.md#resolve-unknowns-by-refining-the-artifacts). ## Handoff and guardrails diff --git a/extensions/assess/README.md b/extensions/assess/README.md index b01a3f2e6d..a43b896e91 100644 --- a/extensions/assess/README.md +++ b/extensions/assess/README.md @@ -65,11 +65,11 @@ 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. +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. 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 assessment command is the exception (for example after a wrong slug or a discarded draft), not the default path for answering clarification markers. +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. ## Slug Conventions diff --git a/extensions/assess/commands/speckit.assess.decide.md b/extensions/assess/commands/speckit.assess.decide.md index 7b0cf6443c..b0dda83ca9 100644 --- a/extensions/assess/commands/speckit.assess.decide.md +++ b/extensions/assess/commands/speckit.assess.decide.md @@ -4,7 +4,7 @@ description: "Apply a go / needs-clarification / kill gate and hand survivors of # Decide: Go, Clarify, or Kill -Render the **verdict** on an assessed idea and record it at `.specify/assessments//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. +Render the **verdict** on an assessed idea and record it at `.specify/assessments//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. Decide **judges; it does not spec or build.** It weighs the evidence already gathered and commits to a defensible call. diff --git a/tests/extensions/assess/test_assess_extension.py b/tests/extensions/assess/test_assess_extension.py index c2f5e8b867..979b322733 100644 --- a/tests/extensions/assess/test_assess_extension.py +++ b/tests/extensions/assess/test_assess_extension.py @@ -97,6 +97,9 @@ def test_decide_needs_clarification_step_reports_and_stops(self): for line in text.splitlines() if line.lstrip().startswith("- **needs-clarification** →") ) + # The opening summary must not contradict the report-back step by + # sending the idea back to an earlier stage unconditionally. + assert "sends it back to an earlier stage" not in text # decide reports and stops; it does not resolve the unknowns itself. assert "report the blocking questions and stop" in step # Refinement happens in the artifact, driven by the user. From 33cf0a092080da050291f62b3f6307bb1939c0ae Mon Sep 17 00:00:00 2001 From: aarjang <115079190+aarjang@users.noreply.github.com> Date: Tue, 17 Nov 2026 10:41:33 +0330 Subject: [PATCH 5/5] docs(assess): scope dependent-wording review to all affected artifacts Copilot pointed out that limiting the review to the artifact being edited misses downstream staleness: a clarification in problem.md can leave concept.md wording stale, and decide reads both. The README and the reference page now direct the user to review dependent wording across the affected artifacts, with decision.md staying the command-owned exception. Assisted-by: Claude Code (model: Claude Fable 5, supervised) --- docs/reference/agentic-assessment.md | 3 ++- extensions/assess/README.md | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/reference/agentic-assessment.md b/docs/reference/agentic-assessment.md index 050ad23170..32c697b374 100644 --- a/docs/reference/agentic-assessment.md +++ b/docs/reference/agentic-assessment.md @@ -83,7 +83,8 @@ A documented decision to stop is a useful result. Run each stage once in the usual flow. To resolve clarification markers or a `needs-clarification` verdict, edit the affected Markdown directly or ask the agent in free-form chat to incorporate the missing facts. Preserve sources and -confidence tags and review dependent wording in the refined artifacts. +confidence tags, and review dependent wording across the affected artifacts — +a clarification in one artifact can leave a downstream artifact stale. `decision.md` itself is not revised in place: once the refined artifacts answer the blocking questions, request reassessment by re-running the decide command, which rebuilds the scorecard, verdict, and handoff from the updated artifacts diff --git a/extensions/assess/README.md b/extensions/assess/README.md index a43b896e91..230b2f4705 100644 --- a/extensions/assess/README.md +++ b/extensions/assess/README.md @@ -65,7 +65,7 @@ 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 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. +Then ask whether the new information clears the blocker and to review and update dependent wording across the affected artifacts — a clarification in `problem.md` can leave downstream `concept.md` wording stale, and `decide` reads both. `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. When you add evidence, keep the source and confidence tags the research stage already uses (`ASSUMPTION` vs cited claims). Do not invent citations.