gen-spec

name	gen-spec
description	Guided specification generation wizard. Use when adding a new feature, API endpoint, or component — forces a written spec before implementation. Validates scope, drafts a structured spec, checks it against conventions, and registers it in the project. NOT for: single-file bug fixes, refactors with no new behavior, or documentation-only changes.

Spec Generation Workflow

Structured workflow for generating a specification document before writing any implementation code. Specs-before-code prevents scope drift and makes review cheaper.

Arguments

• $ARGUMENTS — one of:
  • <name> — feature or component name (e.g., "user-auth", "batch-processor") → full generation workflow
  • validate <path> — run spec health check on an existing spec (former /spec-check)

Workflow

Phase 1: Scope Validation

• Confirm the feature/component boundaries with the user
• Identify dependencies and integration points
• Check for existing specs that overlap (avoid duplication)
• Review related stage contracts if any exist
• If a decision warrants an ADR, apply the three-part test: is it (1) hard to reverse, (2) surprising to future readers, and (3) a genuine trade-off with real alternatives? Skip ADRs for trivial or self-evident decisions.

Phase 2: Draft Spec

• Create specs/<name>.md (or .yaml / .json per project convention)
• Follow the spec template from .claude/rules/spec-conventions.md
• Required sections: Identity, Inputs, Behavior, Outputs, Constraints, Acceptance Criteria
• Link to related specs, ADRs, or design docs

Phase 3: Validate (inline spec health check)

Run the full validation checklist (formerly /spec-check):

1. Structure check — verify all required sections per spec-conventions.md: Identity, Inputs, Behavior, Outputs, Constraints, Acceptance Criteria
2. Reference check — for every file or resource referenced, verify it exists on disk
3. Acceptance criteria quality — each criterion must be testable, specific, and independent
4. Naming convention — filename uses kebab-case, Identity name matches filename
5. Constraint completeness — Constraints section is non-empty with spec-specific exclusions (not generic "don't do bad things")

Report as:

=== SPEC CHECK: <name> ===
Structure:   [PASS/FAIL]
References:  [PASS/FAIL]
Criteria:    [PASS/FAIL]
Naming:      [PASS/FAIL]
Constraints: [PASS/FAIL]

If any check fails, fix before proceeding.

Phase 4: Review

• Run the plan-reviewer agent for adversarial review
• Address any findings before marking the spec as ready
• Get user sign-off on the final spec

Phase 5: Register

• Add the spec to the project's spec index (if one exists)
• Cross-reference in relevant CONTEXT.md files
• The spec is now the source of truth for implementation

Principles

• A spec is a contract, not a wishlist — every statement should be verifiable
• Acceptance criteria are the spec's value — if they're vague, the spec is vague
• The spec drives implementation, not the reverse — don't retrofit specs to match code
• Keep specs DRY with stage contracts — a spec describes WHAT, a stage contract describes HOW

---

Validate Mode (/gen-spec validate <path>)

When $ARGUMENTS starts with validate, run only Phase 3 (spec health check) against the specified spec file. Skip generation phases. Report PASS/FAIL with diagnosis.

Search order for the spec: specs/, docs/specs/, docs/contracts/, then literal path.