---
name: system-review
description: Meta-level analysis of plan vs execution to identify process improvements. Analyzes divergence patterns and suggests updates to CLAUDE.md, agents, and skills.
argument-hint: [plan-file] [execution-report-file]
disable-model-invocation: false
context: fork
---

# System Review

Perform a meta-level analysis of how well the implementation followed the plan and identify process improvements.

## Purpose

**System review is NOT code review.** You're not looking for bugs in the code -- you're looking for bugs in the *process*.

**Your job:**
- Analyze plan adherence and divergence patterns
- Identify which divergences were justified vs. problematic
- Surface process improvements that prevent future issues
- Suggest updates to CLAUDE.md, agent definitions, and skill definitions

## Inputs

**Plan file**: First argument from `$ARGUMENTS`
**Execution report**: Second argument from `$ARGUMENTS`

Read both files thoroughly.

## Analysis Workflow

### Step 1: Understand the Planned Approach

Extract from the plan:
- What features were planned?
- What architecture was specified?
- What validation steps were defined?
- What patterns were referenced?

### Step 2: Understand the Actual Implementation

Extract from the execution report:
- What was implemented?
- What diverged from the plan?
- What challenges were encountered?
- What was skipped and why?

### Step 3: Classify Each Divergence

For each divergence, classify as:

**Good Divergence** -- Justified:
- Plan assumed something that didn't exist in the codebase
- Better pattern discovered during implementation
- Performance optimization needed
- Security issue discovered requiring different approach

**Bad Divergence** -- Problematic:
- Ignored explicit constraints in plan
- Created new architecture instead of following existing patterns
- Took shortcuts that introduce tech debt
- Misunderstood requirements

### Step 4: Trace Root Causes

For each problematic divergence, identify the root cause:
- Was the plan unclear? Where, why?
- Was context missing? Where, why?
- Was validation missing? Where, why?

### Step 5: Generate Process Improvements

Based on patterns, suggest:
- **CLAUDE.md updates**: Universal patterns or anti-patterns to document
- **Agent definition updates**: Instructions that need clarification
- **Skill definition updates**: Missing steps or unclear instructions
- **New skills**: Manual processes that should be automated

## Output Format

### Overall Alignment Score: __/10

- 10: Perfect adherence, all divergences justified
- 7-9: Minor justified divergences
- 4-6: Mix of justified and problematic divergences
- 1-3: Major problematic divergences

### Divergence Analysis

For each divergence:
- **What changed**: [description]
- **Planned**: [what plan specified]
- **Actual**: [what was implemented]
- **Classification**: Good / Bad
- **Root cause**: [unclear plan | missing context | etc.]

### System Improvement Actions

**Update CLAUDE.md:**
- [ ] Document [pattern X] discovered during implementation
- [ ] Add anti-pattern warning for [Y]

**Update Agent Definitions:**
- [ ] Clarify [instruction] in [agent].md

**Update Skill Definitions:**
- [ ] Add [missing step] to /plan skill
- [ ] Improve [section] in /execute skill

**Create New Skill:**
- [ ] `/[skill-name]` for [repeated manual process]

### Key Learnings

**What worked well:**
- [specific things that went smoothly]

**What needs improvement:**
- [specific process gaps identified]

**For next implementation:**
- [concrete improvements to try]

---

Arguments: $ARGUMENTS