deltas

What this skill does

# Delta Extraction Workflow

Extract deltas from VISION.md into DELTAS.md.

## Context

**You must load the following skills and read the following files before proceeding.**

### Skills
- `katachi:framework-core` - Workflow principles

### Required files
- `docs/planning/VISION.md` - Project vision to extract deltas from
- `docs/planning/DELTAS.md` - Current delta inventory (if exists)

## General Guidance

Follow the collaborative workflow principles from the framework-core skill.

**Deltas-specific guidance:**

**Use a scratchpad** - Track state in `/tmp/deltas-<project-name>-state.md` (where `<project-name>` is the basename of the current working directory):
- Raw deltas identified with source traceability
- Agent validation findings
- Refinements to apply

**Extract all at once** - Review entire vision and extract all deltas in one pass.

**Detect gaps proactively** - Challenge completeness:
- "What handles errors here?"
- "What validates this input?"
- "Should we consider security/logging/configuration?"

## Process

### 0. Check Existing State

If `docs/planning/DELTAS.md` exists:
- Read current delta inventory
- Read current vision (check for changes)
- Compare: Are there new workflows? Changed scope?
- Ask: "Should we review for new deltas, or refine existing ones?"
- Enter iteration mode as appropriate

If no deltas exist: proceed with initial extraction

### 1. Extract All Deltas at Once

Review the vision document thoroughly. Extract all deltas in a single pass:

Consider all aspects:
- User-facing capabilities (what users can DO)
- Core workflows and interactions
- Foundational user needs
- Cross-cutting user concerns (security, privacy, error handling from user perspective)

**Each delta represents a bounded piece of work:**
- Can be a new capability, modification, or improvement
- Should be implementable in a reasonable timeframe
- May affect one or more areas of the system
- Description must follow the format in the DELTAS template (`references/DELTAS-template.md` from framework-core)

For each delta, document source traceability (which vision section).

### 2. Agent Validation #1: Raw Delta List

Dispatch the delta-validator agent to review the raw delta list.

```python
Task(
    subagent_type="katachi:delta-validator",
    prompt=f"""
Validate this raw delta list.

## Vision Document
{vision_content}

## Raw Delta List
{raw_deltas}
"""
)
```

Review agent findings with user.

### 3. User Iteration on Raw Deltas

Based on agent validation:
- Split deltas that are too large or deliver multiple capabilities
- Merge or remove redundant deltas
- Add missing deltas identified
- Ensure each delta is traceable to vision

### 4. Organize and Number

Assign sequential IDs (DLT-001, DLT-002, etc.) to all deltas.

**For each delta:**
- Show: proposed ID, description, complexity
- User reviews each delta
- Validate/adjust as needed

### 5. Agent Validation #2: Complete Delta Inventory

Dispatch the delta-validator agent to review the completed inventory.

```python
Task(
    subagent_type="katachi:delta-validator",
    prompt=f"""
Validate this complete delta inventory.

## Delta Inventory
{deltas_md_content}
"""
)
```

Review agent findings with user.

### 6. User Iteration and Finalization

Ask: "Should we iterate based on this feedback, or is the inventory complete?"

If gaps to address → refine deltas
If complete → finalize and write to `docs/planning/DELTAS.md`

### 7. Dependency Analysis

After the delta inventory is finalized, analyze all deltas for dependencies.

#### Analyze each delta

For each delta, analyze:
- What data/capabilities does it consume from other deltas?
- What other deltas must exist for this to work?
- What does it share with other deltas (state, configuration)?
- What must be initialized before this can start?
- What must work for this to be testable?

**Apply dependency priority principles:**
- Core capabilities before workflows
- Core workflows before enhancements
- Foundation before configuration
- Functionality before polish
- Configuration deltas are enhancements, not prerequisites

#### Present proposed dependencies

Present all proposed `**Depends on**:` values with reasoning for each delta.

#### User iteration on dependencies

User reviews proposed dependencies. Discuss and adjust based on user knowledge.

Surface hidden dependencies with gap detection questions:
- "Does X need data that Y produces?"
- "What must be initialized before X can start?"
- "Do X and Y access the same configuration?"
- "What must work for X to be testable?"
- "If Y fails, does X need to know?"

#### Agent validation

Dispatch a general-purpose subagent to validate the dependency graph.

Include user's explicit decisions made during analysis.

Request critique on:
- **Missing implicit dependencies**
- **Hidden coupling** (shared config, state, resources)
- **Over-specification** (unnecessary dependencies)
- **Circular dependencies** (cycles)

If cycles found, work with user to resolve:
- Re-examine if dependency is really needed
- Revise delta scope
- Split deltas

Review findings with user. Iterate if needed.

#### Write dependencies inline

Write dependencies as `**Depends on**: DLT-XXX, DLT-YYY` (or `None`) in each delta's entry in `docs/planning/DELTAS.md`.

## Workflow

**This is a collaborative process:**
- Extract deltas systematically
- Challenge gaps and completeness
- User confirms complexity, IDs
- Challenge deltas that are too large or too small
- Never add deltas without user agreement
- Analyze and propose dependencies after inventory is finalized
- Iterate until complete