SKILL: spec-init Skill | Agent Skills

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

NEVER ask more than 7 clarifying questions — detect optimal stopping and generate the spec
ALWAYS detect the intent type (feature/bug/chore/refactor/docs) before any questioning
NEVER generate a spec without validating all required sections are populated
ALWAYS save the spec to .claude/context/artifacts/specs/ with the correct naming convention
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.

Agent Skills: SKILL: spec-init

Install this agent skill to your local

Skill Files