Bound speckit.clarify planning deferral to implementation details

[gyanu2507]

Description

/speckit.clarify treated "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

[mnriem]

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. clarify.md already lists the categories you want protected (Edge Cases & Failure Handling, external-dependency failure modes, Completion Signals / acceptance testability, etc.). So the minimal core fix is just to bound that one catch-all — defer only implementation-method / tech-stack / task-breakdown; a taxonomy hit is a spec-stage question. I'd happily take that as a focused change.

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 wraps speckit.clarify, which teams opt into. Would you be up for landing the bounded-catch-all fix in core and moving the stage-gate/ratio machinery into a preset?

On the test: test_clarify_stage_gate.py pins exact phrases, so it's brittle to rewording — for the minimal core fix, asserting the unbounded catch-all phrase is absent would be the more durable invariant.

[gyanu2507]

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]

Wrap preset is #4515. Stage-gate procedure, 60% ratio, and MUST-NOT live there. specify preset add clarify-spec-gate if a team wants that enforcement.

[mnriem]

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.)

[Copilot]

🟡 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.

[gyanu2507]

The coverage table used that catch-all for Deferred. It now uses the same three cases as the skip rule (implementation method, tech-stack comparison, or task breakdown), plus quota overflow. The test reads the Completion Report section too.

[gyanu2507]

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.