Deltas

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.

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.

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