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.