/specs.change-spec

description: "Creates a Change Specification for delta/iterations and bug fixes. Use when modifying existing systems or documenting bug fixes. Output: docs/specs/[id]/changes/YYYY-MM-DD--change-name.md"
argument-hint: "[ --type=delta|bugfix ] [ --spec=docs/specs/XXX-feature ] [ --title=\"change description\" ]"
allowed-tools: Task, Read, Write, Edit, Bash, Grep, Glob, AskUserQuestion, TodoWrite
model: inherit

Change Specification

Overview

Creates a structured Change Specification document for: 1. **Delta specifications** — iteration changes, new features in existing system 2. **Bug fix specifications** — defect corrections with root cause analysis

When to Use

• **Delta**: Adding new feature to existing system, modifying existing behavior
• **Bug Fix**: Documenting a bug fix with before/after/unchanged behavior

Do NOT use for new features from scratch → use `specs.brainstorm`

Usage

# Create delta specification
/developer-kit-specs:specs.change-spec --type=delta --spec=docs/specs/001-feature/ --title="Add payment retry logic"

# Short form
/developer-kit-specs:specs.change-spec delta Add payment retry logic

# Create bug fix specification
/developer-kit-specs:specs.change-spec --type=bugfix --spec=docs/specs/001-feature/ --title="Fix race condition in checkout"

# Short form
/developer-kit-specs:specs.change-spec bugfix Fix race condition in checkout

Arguments

| Argument | Required | Description | |----------|----------|-------------| | `--type` | Yes | Change type: delta or bugfix | | `--spec` | No | Path to spec folder (e.g., docs/specs/XXX-feature) | | `--title` | No | Change description/title |

Argument Parsing

1. Run the shared argument parser:

   python3 "${CLAUDE_PLUGIN_ROOT}/scripts/parse_args.py" "$ARGUMENTS"

Read JSON output and extract:

• `type` → "delta" or "bugfix" (required)
• `spec` → spec folder path
• `title` → change description
• `flags` → boolean flags

2. If `type` is not provided, ask the user to choose between delta and bugfix

3. If `spec` is null, auto-detect from git branch

4. Validate required parameters (type is mandatory)

Workflow Position

brainstorm → spec-to-tasks → implementation → review
     ↓
change-spec (when modifying existing feature)
     ↓
task-implementation (from change spec)
     ↓
task-review

Core Principles

• **Delta-focused**: Only document WHAT changes, not the entire system
• **Minimal**: No need to restate unchanged behavior (except in bug fix)
• **Audit trail**: Changes are versioned with date
• **Root cause for bugs**: Not just symptom, but WHY the bug exists
• **Unchanged Behavior**: MANDATORY section for bug fixes to prevent regressions

---

Phase 1: Mode Detection & Argument Parsing

**Goal**: Determine the mode (delta or bugfix) and gather required arguments

**Actions**:

1. Run argument parser:

   python3 "${CLAUDE_PLUGIN_ROOT}/scripts/parse_args.py" "$ARGUMENTS"

2. Extract and validate parameters:

• `type`: Must be "delta" or "bugfix"
• `spec`: Path to parent specification folder
• `title`: Change description

3. If `type` is missing:

• Use AskUserQuestion to determine mode:
• "Is this a delta (new feature/iteration) or a bug fix?"
• Options: "Delta", "Bug Fix"

4. If `spec` is missing:

• Auto-detect from git branch (parse branch name for spec ID)
• If auto-detection fails, ask user for the spec path

5. If `title` is missing:

• Ask user: "What is the change description?"

6. Create todo list with relevant phases based on mode

---

Phase 2: Discovery

**Goal**: Gather context about the existing system and the change

**Actions**:

1. **For Delta mode**:

• Read the existing specification (from `--spec` path)
• Identify the current state of the affected components
• Ask the user what is changing:
• What's new?
• What's modified?
• What's removed?

2. **For Bug Fix mode**:

• Ask user for:
• Brief description of the bug
• Steps to reproduce (if known)
• Expected behavior
• Actual behavior
• Investigate codebase:
• Find the problematic code
• Identify root cause (not just symptom)
• Check git history for related changes

3. Create a summary of what you discovered

---

Phase 3: Delta Classification (Delta Mode Only)

**Goal**: Classify changes into ADDED/MODIFIED/REMOVED

**Actions**:

For each change, classify it:

| Classification | Meaning | Example | |---------------|---------|---------| | **ADDED** | New functionality | "Add payment retry logic" | | **MODIFIED** | Changed from old to new | "Session timeout: 30min → 60min" | | **REMOVED** | Deprecated/removed | "Remove legacy OAuth endpoint" |

For each classified change, ask the user:

• What requirements does this change need?
• What acceptance criteria define success?
• What components are affected?

---

Phase 4: Root Cause Analysis (Bug Fix Mode Only)

**Goal**: Understand WHY the bug exists, not just the symptom

**Actions**:

1. Trace the execution path that causes the bug

2. Identify the specific code responsible

3. Determine WHY this code is wrong:

• Logic error?
• Missing validation?
• Race condition?
• Wrong assumption?
• Edge case not handled?
• Type error?
• Concurrency issue?

4. Document the root cause clearly with:

• **Location**: File, class, method, line numbers
• **Root Cause**: Why this bug exists
• **Why It Happened**: The chain of events that caused the bug

5. **IMPORTANT**: The root cause is critical — document it thoroughly to prevent recurrence

---

Phase 5: Document Generation

**Goal**: Create the change specification document

**Actions**:

1. Determine the output path:

   docs/specs/[id]/changes/YYYY-MM-DD--change-name.md  (Delta)
   docs/specs/[id]/changes/YYYY-MM-DD--bugfix--short-name.md  (Bug Fix)

2. Create the changes directory if it doesn't exist:

   mkdir -p docs/