kaizen-improvement

---
name: kaizen-improvement
description: Transform transcript analysis findings into actionable improvements. Triggers on "generate hooks from findings", "improve agent", "fix anti-pattern", "kaizen improvement", "generate hook proposals", or "create improvement plan". Provides templates for hook generation, agent prompt refinement, skill patches, CLAUDE.md updates, and script automation from analysis data.
---

# Kaizen Improvement

Transform analysis findings from `.planning/kaizen/` into actionable improvements — hooks, agent patches, skill refinements, CLAUDE.md updates, and automation scripts.

**Prerequisite:** Analysis findings must exist in `.planning/kaizen/` (generated by the transcript-analysis skill).

## Improvement Types

Five categories of output, each with a delegation template:

1. **Hook generation** — PreToolUse deny/redirect, SubagentStart context injection, Stop quality gates
2. **Agent prompt refinement** — surgical fixes to agent system prompts via @subagent-refactorer
3. **Skill patches** — add missing knowledge to skills via /plugin-creator:skill-creator
4. **CLAUDE.md updates** — project-wide behavioral rules
5. **Script automation** — replace repeated manual workflows with scripts or skills

For detailed templates and examples, see [Improvement Templates](./references/improvement-templates.md).

For the Autonomous Refinement Loop (ARL) knowledge base — Layer 3 implementation details, prerequisites, and research synthesis — see [ARL Knowledge](../../references/arl.md).

## Workflow

```mermaid
flowchart TD
    Start([Read analysis findings]) --> Parse[Extract anti-patterns with frequency and evidence]
    Parse --> Score[Score by frequency × impact]
    Score --> Top[Select top findings]
    Top --> Type{Improvement type?}
    Type -->|Repeated tool misuse| Hook[Generate hook — deny/redirect]
    Type -->|Agent behavior issue| Agent[Generate agent patch instruction set]
    Type -->|Knowledge gap| Skill[Generate skill patch instruction set]
    Type -->|Project-wide issue| Claude[Generate CLAUDE.md addition]
    Type -->|Manual workflow| Script[Generate automation proposal]
    Hook --> Output[Write to .planning/kaizen/improvements/]
    Agent --> Output
    Skill --> Output
    Claude --> Output
    Script --> Output
    Output --> Install{--install flag?}
    Install -->|Yes| Apply[Write hooks to settings, apply patches]
    Install -->|No| Draft[Leave as proposals for review]
```

## Hook Generation

Read findings → generate hook configuration + optional script. For patterns mapped to each anti-pattern type, guidelines, and examples, see [Hook Patterns](./references/hook-patterns.md).

## Delegation Protocol

Improvements are instruction sets for specialist agents, not direct edits. Follow outcome-focused delegation:

- Describe the problem with evidence (session IDs, tool calls, frequency)
- State the desired outcome
- Let the specialist agent determine the implementation approach
- Never prescribe specific code changes in the delegation prompt

## Output Modes

### Draft mode (default)

Write all proposals to `.planning/kaizen/improvements/` as markdown files. Each file contains:

- Finding summary with evidence
- Proposed improvement
- Delegation prompt for the appropriate specialist agent
- Priority score

### Install mode (--install flag)

For hooks only — write directly to `.claude/settings.json` or `hooks/hooks.json`. Other improvement types always produce delegation prompts (never direct edits).

## Priority Scoring

Rank improvements by:

1. **Frequency × Impact** — occurrences across sessions × cost per occurrence
2. **Automation potential** — hooks > scripts > documentation
3. **Blast radius** — project-wide > single-agent > single-session
4. **Implementation cost** — hook (minutes) < CLAUDE.md (minutes) < skill (hours) < agent (days)