Spec Chef

Spec Chef

Transform implicit stakeholder knowledge into explicit artifacts through systematic gap detection and constrained questioning.

Why This Works

Stakeholders know more than they've written. Documentation has gaps because writers assume context their readers don't have.

1. Detects gaps in existing docs
2. Orders questions by dependency
3. Constrains choices to 2-4 options
4. Codifies immediately before stakeholders forget
5. Separates concerns across distinct artifacts

The Protocol

Phase 1: Analyze

Terminology check: When working with multi-author documentation or inconsistent domain vocabulary, extract domain terminology first:

1. Scan for domain nouns, verbs, and concepts
2. Flag ambiguities:

3. Select ONE canonical term per concept; list aliases to avoid
4. State relationships with explicit cardinality
5. Write UBIQUITOUS_LANGUAGE.md and index it in project documentation

Skip when domain vocabulary is already consistent.

Gap detection: Read existing documentation. Identify gaps using these categories:

Detection technique -- for each documentation section ask:

1. Could two engineers interpret this differently? (ambiguity gap)
2. Does this assume knowledge not stated? (assumption gap)
3. What questions would a new team member ask? (context gap)
4. What could go wrong that isn't mentioned? (edge case gap)
5. How would we demo this? (behavior gap)
6. Who decides if this is done? (success gap)

Phase 2: Map Dependencies

Order questions into tiers. Later tiers depend on earlier answers. Complete each tier before starting the next.

Tier 0: Foundation (identity, scale, privacy)
   |
Tier 1: User Model (accounts, sessions, discovery)
   |
Tier 2: Incentives (motivation, feedback, rewards)
   |
Tier 3: Lifecycle (create, modify, complete, delete)
   |
Tier 4: Edge Cases (errors, abuse, recovery)
   |
Tier 5: Success (MVP scope, metrics)

Domain-specific tier content:

Phase 3: Extract

Use AskUserQuestion tool with constrained choices:

Rules:

• 2-4 options per question (forces concrete decisions)
• Include trade-off in each option's description
• One decision per question (don't bundle)
• 1-4 questions per round (don't overwhelm)
• "Other" is always available (stakeholder can escape)

Question anatomy:

header: "Scale" (<=12 chars, categorizes)
question: "What scale should X support?" (specific, ends with ?)
options:
  - label: "Small (10-50)"
    description: "Use case A, trade-off B"
  - label: "Medium (50-200)"
    description: "Use case C, trade-off D"

Ask tier-by-tier. Capture answers before advancing to the next tier.

Phase 4: Codify

Write artifacts IMMEDIATELY after each tier (or at most after all tiers complete). Don't wait -- stakeholders forget details and rationales fade.

Artifact separation:

When uncertain where information belongs, use this decision matrix:

Separation rules:

• Don't mix WHAT and HOW (behavior in Spec, implementation in Architecture)
• Don't mix WHO and WHAT (persona details in Personas, constraints in Spec)
• Don't write stories without user value (technical work goes in Architecture)
• Don't duplicate decisions across artifacts (single source, references not copies)

When a decision changes, update the source artifact. Single source of truth.

Phase 5: Index

Update project documentation (CLAUDE.md or equivalent) to reference new artifacts. Future sessions must find them.

Anti-Patterns

Tool Requirements

This skill requires AskUserQuestion tool with:

• questions array (1-4 questions)
• options array per question (2-4 options)
• multiSelect boolean (usually false)
• header string (<=12 chars)

Each option needs label and description.