patch

What this skill does

# Patch Workflow

Apply a focused change to the project using a compressed delta workflow. This skill runs the full spec → design → plan → implement → reconcile process in a single session without creating intermediate files. Can also accept a tracked delta ID to use its description and mark it as reconciled when done.

## Input

Change description or delta ID: $ARGUMENTS (optional — will prompt if not provided)

## Context

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

### Skills
- `katachi:framework-core` - Workflow principles
- `katachi:research-docs` - Documentation research for library verification

### Reference Guides
- `${CLAUDE_PLUGIN_ROOT}/skills/framework-core/references/technical-diagrams.md` - ASCII diagram guidance
- `${CLAUDE_PLUGIN_ROOT}/skills/framework-core/references/code-examples.md` - Code snippet guidance

### Delta inventory
- `docs/planning/DELTAS.md` - Delta definitions (used for delta matching in Pre-Check and conflict awareness in Phase 1)

### Project documentation (read during Phase 1)
- `docs/feature-specs/README.md` + relevant feature specs
- `docs/feature-designs/README.md` + relevant feature designs
- `docs/architecture/README.md` + relevant ADRs
- `docs/design/README.md` + relevant DES patterns

## When to Use Patch vs Full Delta

**Use `patch` when ALL apply:**
- The change affects at most 2-3 feature areas
- Requirements are expressible in 1-3 sentences
- No significant design unknowns requiring spikes or external research
- Builds on existing patterns (ADRs/DES), doesn't establish new ones
- Can be planned, implemented, and reconciled in a single session

**Escalate to a full delta when ANY apply:**
- Introduces a new user-facing capability or significantly alters existing ones
- Multiple valid approaches need investigation (spikes)
- Will likely produce new ADRs or DES patterns
- Spans many feature areas or introduces cross-cutting concerns
- Has complex dependencies on in-flight deltas

**Delta-driven patches**: You can run patch with a delta ID (e.g., `/katachi:patch DLT-042`). This uses the delta's description as the change description and marks it as `✓ Reconciled` when done. Best for Easy-Medium complexity deltas that don't need the full multi-session workflow.

## Pre-Check

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

If no $ARGUMENTS provided, ask the user to describe the change they want to make.

### Free-Text Path

If $ARGUMENTS is free text (not a delta ID):

1. **Delta matching**: Scan `docs/planning/DELTAS.md` (already loaded as context) for existing deltas whose description closely matches the provided change description. If a match is found, use `AskUserQuestion` to offer treating it as a delta-driven patch:

   - Option A: "Yes, use DLT-042" — continue to the Delta-Driven Path below with the matched delta ID
   - Option B: "No, continue as an untracked patch" — proceed with the free-text description

   Include the delta's name, description, status, and complexity in the question context so the user can make an informed choice.

### Delta-Driven Path

If $ARGUMENTS looks like a delta ID (e.g., "DLT-042"), or the Free-Text Path matched an existing delta:

1. Fetch delta info:
   ```bash
   python ${CLAUDE_PLUGIN_ROOT}/scripts/deltas.py status show DELTA-ID
   ```

2. If the delta is not found, report the error and stop.

3. Extract the description, complexity, and dependencies from the output.

4. Check for existing work files for this delta: `docs/delta-specs/DELTA-ID.md`, `docs/delta-designs/DELTA-ID.md`, `docs/delta-plans/DELTA-ID.md`. If any exist, note them — they'll be used as additional context during Phase 1 research and Phase 3 planning.

5. If the description is empty, prompt the user for a change description.

6. Use the delta description as the change description for the rest of the workflow.

7. Note the delta ID and any existing work file paths in the scratchpad.

### Patch Fitness Assessment

After resolving the input (whether free-text or delta-driven), evaluate whether the change is suitable for the compressed patch workflow. Consider the change description's scope, and — if delta-driven — the delta's complexity, number of dependencies, and whether existing work files suggest deeper investigation was needed.

If the change appears too complex for a single-session patch (e.g., spans many feature areas, suggests architectural unknowns, Hard complexity, many dependencies), warn the user:

- **Delta-driven**: Recommend the full delta workflow instead (`/katachi:spec-delta DLT-042`). Ask if they want to continue as a patch anyway.
- **Free-text**: Recommend creating a tracked delta via `/katachi:add-delta` instead. Ask if they want to continue as a patch anyway.

Wait for user response. If they decline, stop.

## Scratchpad

Use `/tmp/patch-<animal-adjective>-state.md` for state tracking (animal-adjective pattern for parallel execution support).

Track:
- Delta ID (if patching a tracked delta)
- Existing delta work files found (if any)
- Change description
- Affected features discovered
- Plan file path
- Implementation progress
- Reconciliation decisions
- Issues encountered

## Process

### Phase 1: Research Context (Silent)

Read project documentation to understand the current state:

1. **Delta awareness**: Review `docs/planning/DELTAS.md` (already loaded as context) for in-flight work. Check for conflicts — if the patch modifies files being worked on by an in-flight delta (status is `⧗ ...`), warn the user about potential conflicts.

2. **Feature documentation**: Read `docs/feature-specs/README.md` and `docs/feature-designs/README.md` to identify affected features. Read the specific feature specs and designs relevant to the change.

3. **Project decisions**: Read `docs/architecture/README.md` and `docs/design/README.md`. Read full ADR/DES documents that are relevant to the affected areas.

4. **Existing delta work files** (delta-driven only): If the scratchpad notes existing work files (spec, design, plan) for this delta, read them. These provide valuable context from prior analysis — use them to inform scope assessment and planning.

5. **Source code**: Explore relevant source code in the affected areas to understand current implementation.

6. **Library documentation**: If the change involves any external libraries or frameworks, follow the `katachi:research-docs` skill guidance to verify current APIs before planning. Even for simple patches, wrong API usage costs more to fix than a quick doc check.

### Phase 2: Scope Assessment (Checkpoint)

After research, evaluate whether this change fits the patch model:

- Count affected feature areas (if > 3, likely too broad)
- Assess design clarity (are there unknowns that need spikes?)
- Check for potential new ADR/DES needs (new architectural decisions → full delta)
- Check for conflicts with in-flight deltas

If the change exceeds patch scope, present the finding to the user:

```
"This change appears more complex than a patch can handle:
- [reasons: e.g., 'affects 5 feature areas', 'needs investigation for approach X']

I recommend creating a delta instead. Based on what I've learned, the delta description would be:

[proposed delta description]

Would you like to:
A) Create a delta with /katachi:add-delta
B) Continue as a patch anyway"
```

### Phase 3: Inline Planning (Plan Mode)

Enter Claude's plan mode via `EnterPlanMode`. Research the codebase and draft a plan that compresses spec + design + plan into a single document.

The plan file follows this structure:

```markdown
# Patch: [change description]

## Change Summary
[1-3 sentences: what changes, why, who benefits]

## Requirements
- R1: [requirement]
- R2: ...

## Acceptance Criteria
- AC1: Given [context] When [action] Then [result]
- AC2: ...

## Affected Features
- [feature-spec path] — [Adds