Bound speckit.clarify planning deferral to implementation details - #4507
Conversation
The command treated "better deferred to planning" as a catch-all, so agents skipped NFRs, acceptance criteria, and edge cases. Spec hits must stay question candidates. Defer only implementation method, tech-stack comparison, or task breakdown. Fixes github#1717
|
Thanks @gyanu2507 — you've correctly identified a real bug, but I think this should be split, because most of it belongs in a preset rather than the core command. The genuine defect is narrow: the deferral step has an unbounded escape hatch — "Information is better deferred to planning phase" — that lets the agent defer the entire (already-present) spec taxonomy and skip its spec-stage job, which is the contradictory "defer all 24 / no ambiguities" behavior in #1717. The rest — the explicit stage-gate procedure, the >60% defer-ratio self-audit, and the MUST-NOT enforcement block — is prescriptive clarify methodology. That's an opinion about how aggressively to enforce and self-police the spec/plan line, and baking it into the core command imposes it on everyone. That's exactly the use case for a preset that On the test: |
mnriem
added
triage-nice-to-have
The unbounded "better deferred to planning" catch-all is gone. Spec taxonomy still lives in the command. Stage-gate procedure and defer-ratio audit belong in an opt-in wrap preset, not core.
|
Agreed. I cut this back to the catch-all. Core now defers only implementation method, tech-stack comparison, or task breakdown. The stage-gate procedure, the >60% ratio audit, and the MUST-NOT block are out. The test asserts the unbounded phrase is gone, and that those three defer-only cases are named. I'll put the methodology in a wrap preset as a follow-up so teams can opt in. |
gyanu2507
changed the title
|
Wrap preset is #4515. Stage-gate procedure, 60% ratio, and MUST-NOT live there. |
mnriem
removed
the
author-needs-rescope
|
Thanks @gyanu2507 — this is exactly the split I was hoping for: the core now just bounds the deferral to implementation/tech-stack/task-breakdown, and the stage-gate methodology lives in the opt-in #4515 preset. The bounded-invariant test is the right shape too. I'll trigger CI and take a look. (Drafted with AI assistance — GitHub Copilot.) |
There was a problem hiding this comment.
🟡 Changes recommended
The completion report retains the broad planning-deferral catch-all the PR intends to remove.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
Bounds /speckit.clarify planning deferrals and adds regression coverage.
Changes:
- Restricts planning deferral to implementation-specific concerns.
- Adds a template-content regression test.
File summaries
| File | Description |
|---|---|
templates/commands/clarify.md |
Narrows the planning-deferral rule. |
tests/test_clarify_stage_gate.py |
Tests required and prohibited wording. |
Review details
- Files reviewed: 2/2 changed files
- Comments generated: 1
- Review effort level: Balanced
💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
The candidate-question skip was already limited to implementation method, tech-stack, or task breakdown. The coverage table still called anything "better suited for planning" Deferred. That leftover catch-all is gone, and the test now covers the report.
|
The completion-report Deferred row still said "better suited for planning". That is the same unbounded hatch, just later in the command. 7dccc7e bounds it to quota overflow or those three implementation cases, and the test now covers the report section. |
mnriem
added
the
author-needs-disclosure
|
Thanks @gyanu2507 for following through on the rescope and catching the completion-report wording too. Both deferral rules now match, and this stays within the focused core change we agreed on. I’m satisfied with that scope; no further code changes requested at this point. Please complete the AI disclosure in the PR description: agent/tool, model(s), settings/mode, and extent of assistance. If no AI was used, please state that explicitly. CI is now running on the latest commit. Once it passes and the disclosure is complete, I’m happy to approve this for merge. Drafted for @mnriem by GitHub Copilot (model: GPT-6 Astra). |
|
Thank you! |
* Update Status Report extension to v1.4.2 Update status-report extension submitted by @jwesleye: - extensions/catalog.community.json (version, download_url, effect, requires, etc.) - docs/community/extensions.md community extensions table Closes #4519 Assisted-by: GitHub Copilot (model: gpt-5.2-codex, autonomous) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs: simplify README around three processes (#4591) * docs: simplify README around three processes Use one shared setup and independent SDD, bug-fixing, and idea-assessment quickstarts. Consolidate detailed content into the docs and contributor guide, add missing process guides, align Chinese documentation, and preserve navigation without widening the site header. Assisted-by: GitHub Copilot (model: gpt-6-astra, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * docs: distinguish agent skills from terminal setup Explicitly describe workflow steps as skills invoked in the agent chat, while reserving terminal instructions for CLI installation and project or extension setup. Assisted-by: GitHub Copilot (model: gpt-6-astra, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Bound speckit.clarify planning deferral to implementation details (#4507) * Gate speckit.clarify so spec-taxonomy items are not deferred to plan The command treated "better deferred to planning" as a catch-all, so agents skipped NFRs, acceptance criteria, and edge cases. Spec hits must stay question candidates. Defer only implementation method, tech-stack comparison, or task breakdown. Fixes #1717 * Bound clarify planning deferral to implementation and tech-stack The unbounded "better deferred to planning" catch-all is gone. Spec taxonomy still lives in the command. Stage-gate procedure and defer-ratio audit belong in an opt-in wrap preset, not core. * Bound the clarify completion-report Deferred status too. The candidate-question skip was already limited to implementation method, tech-stack, or task breakdown. The coverage table still called anything "better suited for planning" Deferred. That leftover catch-all is gone, and the test now covers the report. * fix(integrations): dispatch bob commands via `bob run` (#4492) * fix(integrations): dispatch bob commands via `bob run` `BobIntegration` never overrode `build_exec_args()`, so it inherited the `IntegrationBase` no-op returning `None`. Callers read `None` as "this CLI is unavailable", so every workflow command/prompt step targeting Bob reported `CLI not found or not installed` even with `bob` on PATH. `build_command_invocation()` was inherited too, rendering `/speckit.specify` where skills-mode projects install `.bob/skills/speckit-specify/`. * fix(integrations): resolve the command layout from the project being dispatched into `build_command_invocation()` called `effective_invoke_separator()` with no arguments, so `is_skills_mode()` never reached its disk-detection branch (bob/__init__.py:223-228) and always returned the fresh-project default. `dispatch_command()` does receive the workflow project root, but the shared two-argument `build_command_invocation(command_name, args)` contract -- which eight integrations implement -- had nowhere to put it. Two consequences, measured against a real `.bob/commands/speckit.specify.md` project: legacy project, speckit.specify -> /speckit-specify (want /speckit.specify) skills project, speckit.git.commit -> /speckit-git.commit (want /speckit-git-commit) (a) Every existing Bob 1.x install is dispatched a skills-mode invocation naming a command it does not have, so the run fails exactly as it did before dispatch was implemented. (b) Only the `speckit.` prefix was converted, leaving inner dots. The installed skill directory is `speckit-git-commit` -- `SkillsIntegration` derives it with `stem.replace(".", "-")` (base.py:1759) and renders the invocation the same way (base.py:1649) -- so a dotted extension command names a skill that does not exist. The two layouts differ in both the separator and the dot handling: skills flatten every dot, legacy commands keep them. `_build_dispatch_prompt()` carries the project root from `dispatch_command()` into invocation building. The base implementation is the call it replaces, so the other integrations are unaffected; Bob overrides it to resolve the layout from disk, falling back to the working directory, which is where `dispatch_command` runs `bob` when no root is given. Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TqDT4qTj3sFBeg9tMRiXqZ --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com> * chore: release 1.0.7, begin 1.0.8.dev0 development (#4592) * chore: bump version to 1.0.7 * chore: begin 1.0.8.dev0 development --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * chore: upgrade feature-assess to gh-aw v0.88.7 (#4546) * chore: upgrade feature-assess to gh-aw v0.88.7 Regenerate the feature assessment workflow on the current upstream baseline and add positive and negative compatibility checks. Assisted-by: GitHub Copilot (model: GPT-5.6 Sol, autonomous) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * test: assert feature-assess safe output permissions Assisted-by: GitHub Copilot (model: GPT-6 Astra, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * test: enforce feature-assess trigger guards Assisted-by: GitHub Copilot (model: GPT-6 Astra, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Update adrkit extension to v0.1.4 (#4600) Update adrkit extension submitted by @mbeacom: - extensions/catalog.community.json (version, download_url, compatibility range) - docs/community/extensions.md community extensions table (no row changes required) Closes #4571 Assisted-by: GitHub Copilot (model: gpt-5.2-codex, autonomous) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Update Azure Cosmos DB extension to v0.2.0 (#4602) Update cosmosdb extension submitted by @TheovanKraay:\n- extensions/catalog.community.json (version, download_url, and timestamps)\n- docs/community/extensions.md community extensions table (already current)\n\nCloses #4579\n\nCo-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>\nAssisted-by: GitHub Copilot (model: gpt-5.2-codex, autonomous) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Add OpenUP Governed Lifecycle extension to community catalog (#4598) Add openup extension submitted by @anvigo12 to the community catalog and documentation. Closes #4567. Assisted-by: GitHub Copilot (model: gpt-5.2-codex, autonomous) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Add OpenUP Governance preset to community catalog (#4596) Add openup-governance preset submitted by @anvigo12 to the community catalog and documentation table. Closes #4568 Assisted-by: GitHub Copilot (model: gpt-5.2-codex, autonomous) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Manfred Riem <15701806+mnriem@users.noreply.github.com> Co-authored-by: Gyanu Mayank <gyanumayank0@gmail.com> Co-authored-by: temp-droid <82510451+temp-droid@users.noreply.github.com> Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-authored-by: Ken Schlobohm <keschlob@microsoft.com>
Description
/speckit.clarifytreated "better deferred to planning" as a catch-all, so agents skipped NFRs, acceptance criteria, empty-state UX, and edge cases.The command now defers only implementation method, tech-stack comparison, or task breakdown. Spec taxonomy is unchanged. Stage-gate procedure and defer-ratio audit stay out of core (those belong in an opt-in wrap preset).
Testing
uv run pytest tests/test_clarify_stage_gate.py