add-delta

What this skill does

# Add Delta

Add a new delta to the project without requiring full upfront planning.

## Input

Delta description: $ARGUMENTS (optional - will prompt if not provided)

## Context

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

### Skills
- `katachi:iterative-development` - Workflow guidance

### Delta inventory
- `docs/planning/DELTAS.md` - Existing delta definitions

### Existing documentation patterns
- `docs/delta-specs/` - Existing delta specs (for pattern reference)
- `docs/delta-designs/` - Existing delta designs (for pattern reference)

### Feature documentation (for categorization)
- `docs/feature-specs/README.md` - Feature capability index
- Read to understand existing capabilities and help categorize new delta
- Helps identify which features the delta might affect

## Pre-Check

Verify framework is initialized:
- If `docs/planning/` doesn't exist, suggest `/katachi:init-framework` first
- If DELTAS.md missing, explain what's needed

## Process

### 1. Capture Delta Description

If not provided in arguments, ask:
```
"Describe the delta you want to add:
- What does this change or add to the system?
- What user capability does this provide or modify?
- Why is it needed? (the benefit or problem it solves)

This can be a new capability, modification to existing functionality, bug fix, or improvement."
```

### 2. Research Context

#### Existing deltas

Read DELTAS.md to understand:
- Existing delta patterns
- Next available ID number
- Complexity patterns for similar deltas

Compare the user's delta description against each existing delta's name and description. Look for deltas whose core scope — the capability being added or the change being made — substantially overlaps with what the user described. Only flag genuine duplication (same capability/change), not incidental overlap (same broad area or domain). Record any matches for the next step.

#### Codebase and documentation

Use the Explore agent to research the codebase and existing documentation relevant to the delta description. The goal is to understand the current state of the system in the areas the delta would affect:

- **Code**: Find existing implementations, patterns, and architecture related to the delta's scope
- **Documentation**: Check feature specs, delta specs, and designs for related functionality
- **Gaps**: Identify what doesn't exist yet that the delta would need to introduce

This research informs the complexity assessment, dependency identification, and delta description quality.

### 3. Propose Delta Details

If the overlap check in Step 2 found matching deltas, present them, explain why you think they are similar, and ask the user to confirm how to proceed:
```
"This sounds similar to an existing delta:

- **DLT-NNN**: [name] — [description]

[Explain why you think this matches the user's request]

What would you like to do?"
```
- If the user confirms it's the same delta and describes what to change: use the existing delta as a base and draft a proposal incorporating the new information. Continue through Steps 4–6 as normal (validation, iteration, update).
- If the user explains how it's different: use their explanation to refine the proposal and continue below.

Based on the description, codebase research, and existing patterns, draft a complete proposal:

```
"Based on your description, I propose:

**ID**: DLT-NNN (next available)
**Name**: [concise delta name]
**Description**: [follow the format in the DELTAS template from framework-core]
**Priority**: [1-5] ([Critical/High/Medium/Low/Backlog]) - [rationale]
**Complexity**: [Easy/Medium/Hard] - [reason based on scope]
**Dependencies**: [proposed deps or 'None'] - [reason based on analysis]

Does this look right? What needs adjustment?"
```

#### Description writing rule

When this delta builds on capabilities provided by other deltas, describe those capabilities by name — not by delta ID. Delta IDs belong exclusively in the `Depends on` field.

- **Correct**: "uses the user authentication system to verify the session"
- **Incorrect**: "uses DLT-001 to verify the session"

This keeps descriptions self-explanatory and ensures context is preserved when dependencies are reconciled and their IDs become less meaningful.

#### Priority Rationale

The agent proposes a priority based on:
- **Delta scope**: Broader impact suggests higher priority
- **Impact on other deltas**: If this delta blocks many others, it should be higher priority
- **User's expressed goals**: If the user mentioned urgency or importance, reflect that
- **Default**: Use priority 3 (Medium) when there's no clear signal

Priority levels:
| Level | Label | When to use |
|-------|-------|-------------|
| 1 | Critical | Blocks release, urgent deadline |
| 2 | High | Important for near-term goals |
| 3 | Medium | Standard work (default) |
| 4 | Low | Nice to have, no urgency |
| 5 | Backlog | Future consideration |

### 4. Validate Delta Quality

Dispatch the delta-validator agent to validate the proposed delta.

```python
Task(
    subagent_type="katachi:delta-validator",
    prompt=f"""
Validate this proposed delta (single delta mode).

## Proposed Delta
**ID**: {proposed_id}
**Name**: {proposed_name}
**Complexity**: {proposed_complexity}
**Description**: {proposed_description}
"""
)
```

If validation finds issues, refine the delta based on recommendations before presenting to user.

Optionally, dispatch impact analyzer to suggest dependencies:
```python
Task(
    subagent_type="katachi:impact-analyzer",
    prompt=f"""
Analyze likely dependencies for this new delta:

## Delta Description
{delta_description}

## Existing Deltas
{deltas_list}

Suggest which existing deltas this likely depends on, with rationale.
"""
)
```

### 5. Iterate Based on Feedback

- Apply user corrections to priority, complexity, or dependencies
- Re-present if significant changes
- Repeat until user approves

### 6. Update DELTAS.md

If updating an existing delta (user chose the update path in Step 3), replace the existing entry with the updated version — only the fields that changed should differ. Do not change the delta ID or create a new entry.

Otherwise, add a new delta entry:

```markdown
### DLT-NNN: Delta name
**Status**: ✗ Defined
**Depends on**: [DLT-XXX, DLT-YYY or None]
**Priority**: [priority] ([label])
**Complexity**: [complexity]
**Description**: [follow the format in the DELTAS template from framework-core]
```

Reminder: the description must reference dependency capabilities by concept name, not by delta ID. Delta IDs belong only in `Depends on`.

If dependencies were identified during the process, include them inline. For adding dependencies to *existing* deltas, use:
```bash
python ${CLAUDE_PLUGIN_ROOT}/scripts/deltas.py deps add-dep DLT-NNN DEP-ID
```

### 7. Summary and Next Steps

Present summary:
```
"Delta added:

ID: DLT-NNN
Description: [description]
Priority: [priority] ([label])
Complexity: [complexity]
Dependencies: [list or 'None']

Next steps:
- Create spec: /katachi:spec-delta DLT-NNN
- Or continue adding more deltas

Create spec now? [Y/N]"
```

If user says yes, transition to `/katachi:spec-delta DLT-NNN`.

## Error Handling

**Framework not initialized:**
- Suggest `/katachi:init-framework` first
- Don't attempt to create files manually

**Invalid dependency:**
- Delta ID doesn't exist
- Show available deltas
- Ask user to correct

**ID conflict:**
- ID already exists
- Show what exists
- Assign next available number

## Workflow

This is a collaborative process:
- Capture description
- Research existing patterns
- Propose complete delta details (ID, priority, complexity, dependencies)
- Iterate based on user feedback
- Update framework files
- Offer next steps