Repository navigation
Conversation
…ment 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 github#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 github#5325 Assisted-by: Claude Code (model: Claude Fable 5, supervised)
There was a problem hiding this comment.
🟡 Changes recommended
The change lacks focused contract coverage for the decide report-back guidance, so existing tests could miss a regression that incorrectly instructs rerunning the named stage.
1 open issue
What changed in this PR
This pull request aligns the assess decide command’s needs-clarification guidance with the assessment guide and README, directing agents to refine artifacts in place and rerun stages only when inputs change. It also synchronizes the assess extension patch version to 1.0.3.
Changes:
- Updated clarification guidance in the decide command.
- Bumped the assess extension version across its manifest, catalog, and bundle pin.
- No executable behavior changes.
| File | Summary |
|---|---|
extensions/catalog.json |
Updates the cataloged assess extension version to 1.0.3. |
extensions/assess/extension.yml |
Bumps the assess extension manifest version to 1.0.3. |
extensions/assess/commands/speckit.assess.decide.md |
Aligns clarification guidance with the assessment documentation; follow-up coverage is requested for this agent-facing contract, and one opening description remains inconsistent. |
bundles/assess/bundle.yml |
Updates the bundle’s assess extension pin; the bundle and catalog release versions should also be bumped to deliver the metadata change as a distinct release. |
This pull request requires changes.
Review effort: Lite (auto)
| - 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=<ASSESS_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=<ASSESS_SLUG>`) only when the answer changes that stage's inputs. |
…ement
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 github#4402 established.
The test fails against the pre-github#5325 wording and passes with it.
Assisted-by: Claude Code (model: Claude Fable 5, supervised)
|
Addressed the Copilot review in 0e94e5f: added AI disclosure: this round's change and comment were produced with Claude Code (model: Claude Fable 5, default reasoning effort, human-supervised), posted on behalf of @aarjang, who reviewed them before posting. |
|
I agree that the command and guide should be consistent, but this changes the process rather than just clarifying its wording. Clarifications should be supplied by the user—either through manual edits or by explicitly directing an agent—before proceeding to the next stage, which then consumes the updated artifacts. If AI disclosure: Drafted for @mnriem by GitHub Copilot using GPT-6.1 Sol, human-directed; PR assessment and response drafting only. |
Per maintainer direction on github#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)
|
Reworked in c4ed11d9ea to preserve the separation you described — thanks for spelling it out.
AI disclosure: This comment and the commit were drafted with Claude Code (model: Claude Fable 5), human-directed and reviewed, on behalf of @aarjang. |
| `/speckit-assess-decide`: it rebuilds the scorecard, verdict, and handoff from | ||
| the updated artifacts, and asks before overwriting the existing `decision.md`. |
|
Please address Copilot feedback |
…cide 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)
There was a problem hiding this comment.
🟡 Changes recommended
The documented behavior conflicts with the implementation: users cannot revise decision.md in place as described and must instead rerun decide, so the PR or acceptance criteria needs alignment.
3 open issues
2 resolved since last review
Review effort: Lite (dynamic)
| - 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=<ASSESS_SLUG>`). | ||
| - **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=<ASSESS_SLUG>`, which consumes the updated artifacts. Re-run an earlier stage (e.g. `__SPECKIT_COMMAND_ASSESS_RESEARCH__ slug=<ASSESS_SLUG>`) only when the answer changes that stage's inputs. |
|
Addressed all three Copilot findings in 146332c — each was a spot where the pre-rework wording survived:
Verified no stale wording remains ( AI disclosure: This comment and the commit were drafted with Claude Code (model: Claude Fable 5), human-directed and reviewed, on behalf of @aarjang. |
|
Good catch — the description, not the change, was stale: it still described the pre-rework approach ("revise AI disclosure: This comment and the description update were drafted with Claude Code (model: Claude Fable 5), human-directed and reviewed, on behalf of @aarjang. |
There was a problem hiding this comment.
🟡 Changes recommended
The README guidance is too narrow because clarifications in problem.md can leave dependent concept.md wording stale, so it should direct updates across affected artifacts while preserving decision.md as the command-owned exception.
4 open issues
Review effort: Lite (adaptive)
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)
|
Addressed in 33cf0a0: the README's clarification prose now directs reviewing and updating dependent wording across the affected artifacts — with the example you gave (a AI disclosure: This comment and the commit were drafted with Claude Code (model: Claude Fable 5), human-directed and reviewed, on behalf of @aarjang. |
There was a problem hiding this comment.
🔵 Needs a closer look
Source tests pin the wording, but automated review cannot verify how supported agents interpret the stop/refine/re-run lifecycle or the interactive overwrite flow.
3 open issues
1 resolved since last review
Review effort: Lite (adaptive)

Description
Fixes #5325.
docs/guides/assessment.mdand the decide command's report-back disagreed on what aneeds-clarificationverdict means for the next step: the guide treated answering a[NEEDS CLARIFICATION]question as artifact refinement with command re-runs as the exception, whilespeckit.assess.decide.mdtold the agent to unconditionally "re-run the named stage". Tools that offer a next-step answer box had to pick a side (#5325).Per the maintainer's direction in this PR's discussion, the adopted design — the acceptance criterion for this change — keeps refinement and reassessment separate, and all four documents now state it consistently:
needs-clarificationverdict means decide reports the blocking questions and stops; it does not resolve them.decision.mdis not revised in place: reassessment goes through re-runningdecide, which rebuilds the scorecard, rationale, verdict, and handoff from the updated artifacts and asks before overwriting the previous decision.decidestays the exception (wrong slug, discarded draft, or an answer that changes that stage's inputs), never the default next step.Updated accordingly:
speckit.assess.decide.md(opening summary and report-back step), the extension README (flowchart and "Resolving clarifications" prose),docs/guides/assessment.md(verdict table and "Resolve unknowns by refining the artifacts"), anddocs/reference/agentic-assessment.md(overwrite note and "Refining an assessment"). The assess extension is patch-bumped to 1.0.3 inextension.yml, the core extensions catalog, and the assess bundle — the three places the bundled-extension-versions contract test keeps in sync.No executable behavior changes: the diff is command/doc text, version strings, and tests.
Testing
test_decide_needs_clarification_step_reports_and_stopspins the adopted design: it requires report-and-stop, in-place user-driven refinement, and adecidere-run in the report-back step, rejects both the old unconditional "re-run the named stage" and the interim "revisedecision.md" wordings, and rejects the stale opening summary. Verified to fail against both prior versions of the command file and pass on this branch.tests/extensions/assessandtests/contract/test_bundled_extension_versions.pypass locally (.venv/bin/python -m pytestper CONTRIBUTING); agrepfor the superseded phrases acrossextensions/anddocs/is clean.Full suite: the only failures are the pre-existing script-parity flakes on this macOS machine, identical on a clean
maincheckout (also noted in fix(workflows): evaluate chained comparisons pairwise like Python #5203) and untouched by this change.Tested locally with
uv run specify --helpRan existing tests with
uv sync && uv run pytestTested with a sample project (if applicable)
AI Disclosure
AI disclosure: Written with Claude Code (model: Claude Fable 5, default reasoning effort, human-supervised). The agent verified the documented mismatch, implemented the maintainer-chosen separation across the four documents, wrote the contract test and synced version bumps, and ran the verification; I reviewed the diff before submitting. Commits carry a matching
Assisted-by:trailer.🤖 Generated with Claude Code