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. |
mnriem
added
the
triage-can-wait
|
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`. |
| 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 |
| - 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. |
|
Please address Copilot feedback |
Description
Fixes #5325.
docs/guides/assessment.md("Resolve unknowns by refining the artifacts") says answering a[NEEDS CLARIFICATION]question is artifact refinement — edit the Markdown in place or ask in free-form chat — and that re-running a command is an exception. The decide command's report-back template still told the agent the opposite for aneeds-clarificationverdict: "re-run the named stage". Tools that offer a next-step answer box have to pick one of the two, and a re-run also triggers the overwrite confirmation, one more prompt than the guide describes. #4402 aligned the README and the guide on exactly this point but left the decide command's line behind; the README's flowchart already routesneeds-clarificationthrough "refine named artifact in place".This rewords the
needs-clarificationnext step inspeckit.assess.decide.mdto match the guide and the README: update the named artifact in place with the missing information, revisedecision.mdif that clears the blocker, and re-run a stage only when the answer changes that stage's inputs. 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 text plus version strings.
Testing
tests/contract/test_bundled_extension_versions.py,tests/extensions/assess,tests/workflows/test_bundled_bugfix_assess_workflows.py, and the fulltests/specify_cli/extensions+tests/specify_cli/bundlessuites pass locally (1,685 tests,.venv/bin/python -m pytestper CONTRIBUTING).Full suite: 13,946 passed; the same 11 pre-existing failures in the script-parity tests (
test_*_python_parity.py) occur on a cleanmaincheckout on this machine (also noted in fix(workflows): evaluate chained comparisons pairwise like Python #5203) and are 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 against both files and the #4402 history, wrote the reword and the synced version bumps, and ran the verification; I reviewed the diff before submitting. The commit carries a matching
Assisted-by:trailer.🤖 Generated with Claude Code