spec-init

Unified skill that guides spec creation through a structured, interactive process. Wraps progressive-disclosure (requirements gathering), spec-validator (schema validation), and plan-generator (plan from spec) into a single cohesive workflow.

What This Skill Does

spec-init automates the entire specification creation process:

1. Detects the work type (feature, bug, chore, refactor, docs)

2. Asks 5-7 adaptive questions tailored to the detected type

3. Auto-populates a complete spec document from answers

4. Validates the spec against a standard schema

5. Offers to generate an implementation plan

6. Stores the spec with metadata tracking

Instructions for AI Agent

Step 1: Read Memory Context

**MANDATORY FIRST STEP:**

Read `.claude/context/memory/learnings.md` to leverage previous patterns and decisions.

Step 2: Type Detection

Ask the user: "What are you building?"

Auto-detect the work type from their description:

**Feature**: Descriptions like "Build X functionality", "Add X feature" → `type: feature`

**Bug**: Descriptions like "Fix X issue", "Resolve X error" → `type: bug`

**Chore**: Descriptions like "Update X component", "Upgrade dependencies" → `type: chore`

**Refactor**: Descriptions like "Reorganize X", "Restructure Y" → `type: refactor`

**Docs**: Descriptions like "Document X", "Write guide for Y" → `type: docs`

Step 3: Adaptive Requirements Gathering (5-7 Questions)

Use adaptive questioning based on the detected type. Ask **only the most relevant questions** to minimize user effort while maximizing context quality.

**Domain Selection:**

```

feature → general domain

bug → debugging domain

chore → general domain

refactor → architecture domain

docs → documentation domain

```

**Core Question Set (adapt based on type):**

1. **What's the objective?** (all types)

- For features: "What capability are you adding?"

- For bugs: "What's the current broken behavior?"

- For refactors: "What structure needs improvement?"

2. **Who is impacted?** (features, bugs)

- "Who will use this feature?" / "Who is affected by this bug?"

3. **What's the success metric?** (features, refactors)

- "How will you measure success?"

4. **What's the timeline/urgency?** (all types)

- For bugs: "What's the severity and business impact?"

- For features: "When is this needed?"

5. **What are the acceptance criteria?** (all types)

- "How will you know this is complete and correct?"

6. **What are the constraints?** (if relevant)

- "Are there technical limitations, dependencies, or performance requirements?"

7. **What's out of scope?** (if needed for clarity)

- "What should explicitly NOT be included?"

**Adaptive Stopping Logic:**

Stop early (at 5 questions) if answers are detailed and cover all key dimensions

Continue to 7 questions if answers are vague or missing critical context

Track context quality: if user provides rich answers early, don't ask redundant questions

Step 4: Generate Spec Document

Auto-populate this template from the gathered answers:

```markdown

SPEC: [Feature Name]

1. Overview

**Title**: [From question 1]

**Type**: [Detected type: feature/bug/chore/refactor/docs]

**Objective**: [User summary from answers]

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

**Acceptance Criteria**:

[Criterion 1 from question 5]

[Criterion 2 from question 5]

[Criterion 3 from question 5]

2. Problem Statement

**Current State**: [Extracted from question 1 answers]

**Pain Points**: [Extracted from user answers]

**Impact**: [Quantified if possible from question 2 or 4]

3. Proposed Solution

**Approach**: [From user input across questions]

**Key Features**: [List from answers]

**Scope**:

- **In Scope**: [What's included]

- **Out of Scope**: [What's excluded, from question 7]

4. Implementation Approach

**Phase 1**: [Design/spike if needed]

**Phase 2**: [Core implementation]

**Phase 3**: [Testing and validation]

**Phase 4**: [Documentation and rollout]

5. Success Metrics

**Quantitative**: [From question 3 or user-provided metrics]

**Qualitative**: [User satisfaction, usability]

**Timeline**: [From question 4]

6. Effort Estimate

**Design**: [X days]

**Implementation**: [Y days]

**Testing**: [Z days]

**Documentation**: [W days]

**Total**: [Sum days]

(Provide realistic estimates based on scope and complexity)

7. Dependencies

**Required**: [Technologies, libraries, or systems needed]

**Blocking**: [What must complete before this work starts]

**Risks**: [Key risks or unknowns identified]

8. Acceptance Criteria Checklist

[ ] Feature implemented per spec

[ ] All tests passing

[ ] Documentation updated

[ ] No breaking changes introduced

[ ] Performance targets met

[Add any additional criteria from question 5]

```

Step 5: Validate Spec

Check the generated spec against these validation rules:

All required sections present (Overview, Problem Statement, Proposed Solution, Implementation Approach, Success Metrics, Effort Estimate, Dependencies, Acceptance Criteria)

At least 3 acceptance criteria defined

Effort estimate provided (in days)

Type field is valid (feature/bug/chore/refactor/docs)

Title is clear and descriptive

If validation fails, highlight missing sections and ask user to provide missing information.

Step 6: Save Spec

Store the validated spec to:

```

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

```

Track metadata:

```json

{

"trackId": "[auto-generated-uuid]",

"type": "[detected-type]",

"status": "new",

"created_at": "[ISO-8601-timestamp]",

"title": "[spec-title]",

"path": "[spec-file-path]"

}

```

Step 7: Offer Plan Generation

After spec is saved and validated, ask:

"Spec created and validated! Would you like me to generate an implementation plan?"

**If yes**: Execute `Skill({ skill: "plan-generator", args: { specPath: "[saved-spec-path]" } })`

**If no**: Provide path to saved spec and next steps guidance

Step 8: Update Memory (MANDATORY)

**After completing the workflow:**

If you discovered a new pattern or optimization → append to `.claude/context/memory/learnings.md`

If you encountered an issue or edge case → log to `.claude/context/memory/issues.md`

If you made a significant decision (e.g., chose one approach over another) → document in `.claude/context/memory/decisions.md`

**Memory Protocol Rule:** If it's not in memory, it didn't happen. Always persist learnings for future invocations.

Usage Examples

Example 1: Quick Feature

```

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

Workflow:

1. Detect type = "feature"

2. Ask 5 adaptive questions:

- What UI components need dark mode?

- Who are the target users?

- How will users toggle between modes?

- Any accessibility requirements?

- How will you validate it works correctly?

3. User answers in <5 minutes

4. Generate complete spec with all sections

5. Validate spec (all sections present, 3+ criteria)

6. Save to .claude/context/artifacts/specs/dark-mode-spec-20260202.md

7. Offer plan generation

```

Example 2: Bug Fix

```

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

Workflow:

1. Detect type = "bug"

2. Ask 5 debugging-focused questions:

- What are the reproduction steps?

- What's the expected vs actual behavior?

- What's the business impact and severity?

- Are there any error logs or stack traces?

- How will you verify the fix?

3. Generate bug fix spec with Problem Statement, Root Cause (if known), and Fix Approach

4. Validate and save

5. Offer plan generation for fix implementation

```

Example 3: Refactor

```

User: "Reorganize the authentication module"

Workflow:

1. Detect type = "refactor"

2. Ask 6 architecture-focused questions:

- What's the current structure and its problems?

- What's the target architecture?

- What are the performance or maintainability goals?

- What are the risks of this refactor?

- How will you ensure no regressions?

- What's out of scope?

3. Generate refactor spec with clear before/after architecture

4. Validate and save

5. Offer plan generation

```

Integration Points

**progressive-disclosure**: Used for adaptive requirements gathering

**spec-validator**: Used for schema validation in Step 5

**plan-generator**: Offered as next step after spec creation

**track-metadata schema**: Used for metadata storage in Step 6

**Memory system**: Integrated via learnings.md, issues.md, decisions.md

Constraints

Maximum 7 questions (typical: 5-6 for clear requirements)

Spec must pass validation before saving

All memory updates are mandatory (learnings, issues, decisions)

Spec file naming convention: `[feature-name]-spec-YYYYMMDD.md`

Always read memory context before starting

Success Criteria

User completes spec in <10 minutes

Generated spec passes validation

Spec contains all required sections

At least 3 acceptance criteria defined

Memory updated with learnings

User offered plan generation as next step

spec-init

spec-init

What This Skill Does

Instructions for AI Agent

Step 1: Read Memory Context

Step 2: Type Detection

Step 3: Adaptive Requirements Gathering (5-7 Questions)

Step 4: Generate Spec Document

SPEC: [Feature Name]

1. Overview

2. Problem Statement

3. Proposed Solution

4. Implementation Approach

5. Success Metrics

6. Effort Estimate

7. Dependencies

8. Acceptance Criteria Checklist

Step 5: Validate Spec

Step 6: Save Spec

Step 7: Offer Plan Generation

Step 8: Update Memory (MANDATORY)

Usage Examples

Example 1: Quick Feature

Example 2: Bug Fix

Example 3: Refactor

Integration Points

Constraints

Success Criteria

Reviews (0)