system-review

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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 Layer 1 assets (CLAUDE.md, plan templates, skills)

**Philosophy:**

- Good divergence reveals plan limitations → improve planning
- Bad divergence reveals unclear requirements → improve communication
- Repeated issues reveal missing automation → create skills

## Context & Inputs

You will analyze key artifacts:

**PROGRESS.md:**
Read this to find all notes for the current feature including:
- Planning phase notes
- Execution phase notes
- Execution report (what was actually done and why)

**Generated Plan:**
Read this to understand what the agent was SUPPOSED to do.
Look up plan file location from PROGRESS.md

**Execution Report & Code Review:**
Read `.agents/execution-reports/` and `.agents/code-reviews/` for this feature if they exist — they document divergences, challenges, and issues found post-execution.

**Skills used in the session:**
Identify which `ai-dev-env:*` skills were invoked (from PROGRESS.md, session summary, or conversation context). These are the skills you will inspect and improve in Step 6.

## Analysis Workflow

### Step 0: Read PROGRESS.md

**MANDATORY FIRST STEP:**

1. Read `PROGRESS.md` to find the feature being reviewed
2. Extract the plan file location from planning phase notes
3. Read the execution report section to understand what was actually done
4. Use this context for the remaining analysis steps

### Step 1: Understand the Planned Approach

Read the generated plan (from PROGRESS.md reference) and extract:

- What features were planned?
- What architecture was specified?
- What validation steps were defined?
- What patterns were referenced?

### Step 2: Understand the Actual Implementation

Read the execution report from PROGRESS.md and extract:

- 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 identified in the execution report, 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 that required 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?
- Was manual step repeated, where, why?

### Step 5: Generate Process Improvements

Based on patterns across divergences, suggest:

- **CLAUDE.md updates:** Universal patterns or anti-patterns to document
- **Plan skill updates:** Instructions that need clarification or missing steps
- **New skills:** Manual processes that should be automated
- **Validation additions:** Checks that would catch issues earlier

## Output Format

**CRITICAL: Create review in `.agents/system-reviews/` folder**

### Step 1: Determine Feature Name

Extract the feature/module name from PROGRESS.md or the execution report.
Example: "module-5-multi-format-enhancement" from execution report path

### Step 2: Create Detailed System Review

**Create file:** `.agents/system-reviews/{feature-name}.md`

From giladresisi/ai-dev-env, MIT.

More from giladresisi/ai-dev-env