system-evolution-review

Original：🇺🇸 English
Translated

Performs a meta-level review of how well an implementation followed its plan, classifying divergences and recommending AI-Layer improvements. Use after an execution report exists to find bugs in the process, not the code.

4installs
Sourcecoleam00/skills
Added on

NPX Install

npx skill4agent add coleam00/skills system-evolution-review

Tags

Translated version includes tags in frontmatter
system-reviewai-layer-improvementprocess-analysisplan-adherenceimplementation-audit

SKILL.md Content

View Translation Comparison →

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 AI-Layer 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 four key artifacts:
Plan Skill: Read this to understand the planning process and what instructions guide plan creation. 
.claude/skills/piv-plan-implementation/SKILL.md
Generated Plan: Read this to understand what the agent was SUPPOSED to do. Plan file: $plan
Execute Skill: Read this to understand the execution process and what instructions guide implementation. 
.claude/skills/piv-implement/SKILL.md
Execution Report: Read this to understand what the agent ACTUALLY did and why. Execution report: $report

Analysis Workflow

Step 1: Understand the Planned Approach

Read the generated plan ($plan) 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 ($report) 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

Save your analysis to: 
.claude/system-reviews/[feature-name]-review.md

Report Structure:

Meta Information

  • Plan reviewed: [path to $plan]
  • Execution report: [path to $report]
  • Date: [current date]

Overall Alignment Score: __/10

Scoring guide:
  • 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 from the execution report:
yaml
divergence: [what changed]
planned: [what plan specified]
actual: [what was implemented]
reason: [agent's stated reason from report]
classification: good ✅ | bad ❌
justified: yes/no
root_cause: [unclear plan | missing context | etc]

Pattern Compliance

Assess adherence to documented patterns:
  • Followed codebase architecture
  • Used documented patterns (from CLAUDE.md)
  • Applied testing patterns correctly
  • Met validation requirements

System Improvement Actions

Based on analysis, recommend specific actions:
Update CLAUDE.md:
  • Document [pattern X] discovered during implementation
  • Add anti-pattern warning for [Y]
  • Clarify [technology constraint Z]
Update Plan Skill ($plan):
  • Add instruction for [missing step]
  • Clarify [ambiguous instruction]
  • Add validation requirement for [X]
Create New Skill:
  • A new skill for [manual process repeated 3+ times]
Update Execute Skill:
  • Add [validation step] to execution checklist

Key Learnings

What worked well:
  • [specific things that went smoothly]
What needs improvement:
  • [specific process gaps identified]
For next implementation:
  • [concrete improvements to try]

Important

  • Be specific: Don't say "plan was unclear" - say "plan didn't specify which auth pattern to use"
  • Focus on patterns: One-off issues aren't actionable. Look for repeated problems.
  • Action-oriented: Every finding should have a concrete asset update suggestion
  • Suggest improvements: Don't just analyze - actually suggest the text to add to CLAUDE.md or skills