The Right Amount of Spec

No. MinSpec implements the same SDD methodology that GitHub Spec Kit popularized, but adds an adaptive ceremony layer driven by a T1–T4 complexity classifier. Spec Kit applies the full lifecycle to every change. MinSpec asks: does this trivial fix really need a Plan document?

Spec files are intentionally Spec Kit-compatible — unknown frontmatter fields are ignored by both tools. You can move between them.

Spec-Driven Development is the practice of writing the specification before the implementation, then driving the implementation (often by AI agents) from that spec. Canonical SDD has seven phases: constitution → specify → clarify → plan → tasks → analyze → implement. Each phase produces a markdown artifact. The artifacts form a traceable chain from intent to code.

Contract-Driven Development pushes you to write contracts (TypeScript types, Zod schemas, OpenAPI specs) and invariant tests before implementation. SDD tells you what to build. CDD tells you what shape the output must satisfy.

The two compose well: SDD's plan phase is the natural place to write contracts, and CDD's T0 invariant tests give SDD's tasks something concrete to verify against. Spec Kit doesn't include CDD; MinSpec adds it as a thin layer because AI agents need contracts to avoid drift.

Because pure SDD doesn't answer some practical questions:

• ADR answers "why did we choose this approach?" — useful even mid-spec.
• WSJF answers "which spec do I work on next?" — SDD is silent on backlog order.
• GTD-style session scope answers "what counts as drift?" — needed for AI agents that wander.

None of these are full methodologies in MinSpec — they're small, well-known patterns plugged in where SDD has gaps. You can ignore any of them and MinSpec still works.

No. MinSpec is a development methodology tool — how you take one change from intent to merged code. It doesn't tell you how to run standups, plan sprints, or estimate stories. The WSJF scoring is for ordering MinSpec's own backlog of specs, not your team's overall workflow.

SDD assumes you're building a feature — you know roughly what you want, you write a spec, you implement. Bug fixes invert this: you don't know what's wrong, you have to find the root cause first, and a written "spec" before diagnosis is just guessing.

RCDD — Root-Cause-Driven Debugging (Reproduce → Diagnose → Fix → Harden) is MinSpec's separate, lighter lifecycle that respects this. Bug work is roughly half of developer time and shouldn't be forced through a feature-shaped process. RCDD's differentiator is the final Harden phase — close the contract or test gap that let the bug in, not just patch the symptom.

No. Open VS Code, install the extension, run MinSpec: Init. The classifier suggests tiers, the lifecycle UI shows which phase you're in, the templates fill in the boilerplate. You'll absorb the underlying SDD/CDD ideas by using them.

This FAQ exists for the curious developer who wants to know what's under the hood — not as required reading.

Yes. User override always wins is a hard invariant. The classifier suggests a tier; you click to change it. Phases are never mandatory — MinSpec warns when you skip something the rules say you should keep, but it doesn't block. The methodology is a recommendation engine, not a gate.