SKILL: spec-init

Overview

Unified skill that guides spec creation through structured, interactive process.

Wraps these existing skills:

• context-compressor (progressive disclosure mode for requirements gathering)
• plan-generator (plan from spec)

Workflow

1. Type Detection

Question: "What are you building?"

Auto-detect from description:

• Feature: "Build X functionality" → type: feature
• Bug: "Fix X issue" → type: bug
• Chore: "Update X component" → type: chore
• Refactor: "Reorganize X" → type: refactor
• Docs: "Document X" → type: docs

2. Progressive Disclosure v2 (Adaptive, 5-7 questions)

Invoke context-compressor (progressive disclosure mode) with adaptive algorithm:

const { AdaptiveQuestioner } = require('.claude/lib/utils/adaptive-discloser.cjs');
const { ContextAccumulator } = require('.claude/lib/utils/context-accumulator.cjs');

// Determine domain from detected type
const domainMap = {
  feature: 'general',
  bug: 'debugging',
  chore: 'general',
  refactor: 'architecture',
  docs: 'documentation',
};
const domain = domainMap[detectedType] || 'general';

const aq = new AdaptiveQuestioner(domain);
const ca = new ContextAccumulator();

let history = [];
let questionCount = 0;

while (questionCount < 7) {
  const context = ca.getContext();
  const result = await aq.getNextQuestion(context, history);

  // Check if we should stop early
  const readiness = await aq.detectOptimalStop(history, context);
  if (readiness.shouldStop) {
    break;
  }

  // Ask the question
  const answer = await AskUserQuestion({ question: result.question });

  // Store answer with metadata
  ca.addAnswer(result.question, answer, { domain, priority: 'HIGH' });
  history.push({ question: result.question, answer });

  questionCount++;
}

// Summary from accumulated context
const summary = ca.buildSummary();

Key Improvements over v1:

• Adaptive questioning (skips redundant questions)
• Context-aware (learns from answers)
• Memory-integrated (leverages learnings.md)
• Optimal stopping (5-7 questions typical, down from 10-12)
• Quality scoring (detects when ready for spec generation)

3. Spec Template Generation

Auto-populate spec from answers:

# SPEC: [Feature Name]

## 1. Overview

**Title**: [From question 1]
**Type**: [Detected type]
**Objective**: [User summary]

**User Story**: As a [user type], I want [capability], so that [benefit]

**Acceptance Criteria**: [From question 5]

## 2. Problem Statement

- **Current State**: [From question 1 answers]
- **Pain Points**: [Extracted from answers]
- **Impact**: [Quantified if possible]

## 3. Proposed Solution

- **Approach**: [From user input]
- **Key Features**: [From answers]
- **Scope**: [What's in/out]

## 4. Implementation Approach

- **Phase 1**: [Design/spike if needed]
- **Phase 2**: [Core implementation]
- **Phase 3**: [Testing]
- **Phase 4**: [Documentation]

## 5. Success Metrics

- **Quantitative**: [From question 3]
- **Qualitative**: [User satisfaction]
- **Timeline**: [From question 4]

## 6. Effort Estimate

- **Design**: 1 day
- **Implementation**: 3 days
- **Testing**: 2 days
- **Documentation**: 1 day
- **Total**: 7 days

## 7. Dependencies

- **Required**: [Extracted from context]
- **Blocking**: [What must complete first]
- **Risk**: [Key risks identified]

## 8. Acceptance Criteria Checklist

- [ ] Feature implemented per spec
- [ ] All tests passing
- [ ] Documentation updated
- [ ] No breaking changes
- [ ] Performance targets met

4. Validation

Validate spec against schema:

• Validate spec completeness inline
• Check: all required sections present
• Check: at least 3 acceptance criteria
• Check: effort estimate in days

5. Plan Suggestion

After spec approved:

• Suggest: "Ready for planner to create plan?"
• If yes: Show Skill({ skill: "plan-generator", args: { specPath: "..." } })
• If no: Allow editing spec

6. Storage

Save spec to:

.claude/context/artifacts/specs/[feature-name]-spec-YYYYMMDD.md

Track metadata:

• trackId: auto-generated
• type: detected
• status: "new"
• created_at: timestamp

Usage Examples

Example 1: Quick Feature

User: "I want to add dark mode to the UI"

spec-init workflow:
1. Detect: type = "feature"
2. Ask: 5 questions about dark mode
3. User answers in <5 minutes
4. Generate spec
5. Validate against schema
6. Store and offer plan generation

Example 2: Bug Fix

User: "There's a memory leak in the scheduler"

spec-init workflow:
1. Detect: type = "bug"
2. Ask: 5 questions (reproduce steps, impact, etc)
3. Generate bug fix spec
4. Suggest acceptance criteria
5. Ready for planner

Output

• Generated spec markdown (saved)
• Track metadata JSON
• Plan generation suggestion
• Next steps guidance

Integration Points

• context-compressor (progressive disclosure mode for requirements gathering)
• plan-generator (next step)
• track-metadata schema (metadata)

Iron Laws

1. NEVER ask more than 7 clarifying questions — detect optimal stopping and generate the spec
2. ALWAYS detect the intent type (feature/bug/chore/refactor/docs) before any questioning
3. NEVER generate a spec without validating all required sections are populated
4. ALWAYS save the spec to .claude/context/artifacts/specs/ with the correct naming convention
5. NEVER skip track metadata — every spec must include trackId, type, status, and created_at

Anti-Patterns

Anti-Pattern	Why It Fails	Correct Approach
Asking 10-12 fixed questions	Over-questioning reduces user engagement	Use progressive disclosure; stop at 5-7 questions when context is sufficient
Skipping intent type detection	Questions don't adapt to the task type	Always classify the request as feature/bug/chore/refactor/docs first
Generating spec without validation	Incomplete specs reach the planner	Validate all required sections before saving the spec
Missing track metadata	Spec cannot be tracked or referenced by downstream agents	Always populate trackId, type, status, and created_at fields
Saving to wrong location	Specs are not discoverable by other agents	Always save to .claude/context/artifacts/specs/ with standard naming

Memory Protocol (MANDATORY)

Before starting: Read .claude/context/memory/learnings.md

After completing:

• New pattern -> .claude/context/memory/learnings.md
• Issue found -> .claude/context/memory/issues.md
• Decision made -> .claude/context/memory/decisions.md

ASSUME INTERRUPTION: If it's not in memory, it didn't happen.