Reflect & Patch

<mission_control> Enable Claude to learn from user corrections by analyzing session data and proactively updating its own rules/skills to prevent recurrence <success_criteria>After invocation: 1) Session transcript analyzed, 2) Root cause identified, 3) Relevant rule/SKILL.md updated, 4) Change documented with transparency</success_criteria> </mission_control>

Think of this skill as self-diagnostic surgery—when Claude makes a mistake that the user corrects, this skill investigates why and patches the relevant rule to prevent recurrence.

What This Skill Does

1. Detects correction triggers - User says "no", "wrong", "not what I asked", etc.
2. Reads session transcript - Accesses @.claude/transcripts/last-session.jsonl
3. Classifies failure type - Uses correction-patterns.md to categorize the mistake
4. Identifies root cause - Why did the mistake occur?
5. Determines target file - Which rule or SKILL.md needs patching?
6. Applies patch strategy - Uses patch-strategies.md to update the file
7. Reports transparently - Explains what was changed and why

Trigger Conditions

Auto-Invocation (Primary)

Claude should invoke this skill when it detects:

• User says "no", "wrong", "stop", "not what I asked", "actually..."
• User explicitly rejects Claude's output ("That's not what I meant")
• Claude recognizes its own mistake through user feedback

Example internal dialogue:

"I see I made a mistake with the directory structure. I'm invoking ops/reflect-and-patch to update my project rules so I don't do that again."

Manual Invocation

Users can explicitly request:

• "reflect on last session"
• "analyze what went wrong"
• "update rules based on our conversation"
• "why did you make that mistake?"

Transcript Access

The session transcript is symlinked to a stable location:

@.claude/transcripts/last-session.jsonl

How to read:

Read @.claude/transcripts/last-session.jsonl

The file contains the previous session's transcript for analysis.

Failure Classification

Use references/correction-patterns.md to classify the mistake type:

Patch Application

Use references/patch-strategies.md to determine how to update:

Workflow Overview

┌─────────────────────────────────────────────────────────────────┐
│                    POST-MORTEM WORKFLOW                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. DETECT    →  2. READ      →  3. CLASSIFY  →  4. ANALYZE   │
│  Trigger      →  Transcript   →  Failure      →  Root Cause   │
│                 →              →  Type         →               │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  5. PATCH    →  6. VERIFY    →  7. REPORT                     │
│  Apply       →  No           →  Transparency                  │
│  Strategy    →  Regressions  →  Report                        │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Step-by-Step Process

Step 1: Detect Trigger

Input: User correction detected in conversation

Recognition triggers:

• User says "no", "wrong", "not what I asked", "actually..."
• User uses /rewind command
• Claude explicitly recognizes its own mistake

Action: Note the trigger and proceed to Step 2

Step 2: Read Transcript

Action: Read the session transcript

Read @.claude/transcripts/last-session.jsonl

What to extract:

1. The user's original request
2. Claude's response/action
3. The user's correction
4. Any context about what went wrong

If transcript unavailable: Use conversation context directly

Step 3: Classify Failure Type

Use references/correction-patterns.md to classify:

Output: Confirmed category and target file

Step 4: Analyze Root Cause

Question: Why did Claude make this mistake?

Output: Root cause statement

Step 5: Apply Patch Strategy

Use references/patch-strategies.md to select and apply:

1. Select strategy based on root cause
2. Locate relevant section in target file
3. Apply patch following strategy instructions
4. Verify syntax is correct

Example application:

Root cause: Claude used "skill/" instead of "skills/"
Strategy: Add recognition question

Patch applied to .claude/rules/architecture.md:

**Recognition:** Am I using the correct directory name (check for plural/singular)?

Step 6: Verify No Regressions

Checklist:

• XML/Markdown syntax is valid
• Patch doesn't break existing content
• Reference links are correct
• Language strength is appropriate

If issues found: Revise patch and re-verify

Step 7: Generate Transparency Report

Format:

Reflect & Patch executed:

Trigger: [What caused the reflection]
Classification: [Category - Target file]
Root cause: [Why the mistake occurred]

Patched: [File path]
Change: [Specific edit applied]

Expected outcome: [How this prevents recurrence]

Complete Example

User: "No, that's wrong. The skill should be in skills/ not skill/"

1. DETECT: User correction detected ("No, that's wrong")
2. READ: Read transcript, found Claude created "skill/" directory
3. CLASSIFY: Architecture drift (directory structure issue)
   Target: .claude/rules/architecture.md
4. ANALYZE: Root cause = Claude didn't verify singular/plural
5. PATCH: Added recognition question using Strategy A
6. VERIFY: Syntax valid, no regressions
7. REPORT: Generated transparency report

Anti-Patterns to Avoid

• Don't patch the wrong file based on weak classification
• Don't apply too strong language for minor issues
• Don't create duplicates instead of updating existing rules
• Don't skip verification before completing

Do:

• Verify classification before patching
• Match language strength to severity
• Update existing rules, don't create duplicates
• Always verify before claiming completion

Transparency Reporting

After patching, report:

1. What triggered the reflection - The user correction or pattern detected
2. Root cause analysis - Why the mistake occurred
3. File patched - Which file was updated
4. Change made - Specific edit applied
5. Expected outcome - How this prevents recurrence

Example:

Reflect & Patch executed:

Trigger: User said "No, the directory should be skills/, not skill/"
Root cause: Claude created single directory when structure requires plural

Patched: .claude/rules/architecture.md
Change: Added recognition question to directory structure section:
  "Recognition: Am I using the correct directory name (plural for directories)?"

Expected: Claude will now verify directory names before creation.

Constraints

• Single Source of Truth: Update the actual rule, don't create duplicates
• Defensive Patching: Verify changes don't break existing functionality
• Progressive Enhancement: Start with recognition questions, escalate to constraints
• Transparency: Always report what was changed and why

Related Skills

• deviation-rules - Handles unexpected work during execution
• quality-standards - Audits conversation alignment and quality gates
• memory-persistence - Session lifecycle and transcript handling

Genetic Code

This component carries essential Seed System principles for context: fork isolation:

<critical_constraint> MANDATORY: All components MUST be self-contained (zero .claude/rules dependency) MANDATORY: Achieve 80-95% autonomy (0-5 AskUserQuestion rounds per session) MANDATORY: Description MUST use What-When-Not format in third person MANDATORY: No component references another component by name in description MANDATORY: Progressive disclosure - references/ for detailed content MANDATORY: Use XML for control (mission_control, critical_constraint), Markdown for data No exceptions. Portability invariant must be maintained. </critical_constraint>

Delta Standard: Good Component = Expert Knowledge − What Claude Already Knows

Recognition Questions:

• "Would Claude know this without being told?" → Delete (zero delta)
• "Can this work standalone?" → Fix if no (non-self-sufficient)
• "Did I read the actual file, or just see it in grep?" → Verify before claiming

When Claude detects user correction patterns or user explicitly requests reflection on mistakes

<success_criteria>

• Session transcript read and analyzed
• Failure type classified using correction-patterns.md
• Root cause identified
• Target file determined
• Patch applied using patch-strategies.md
• Change verified (no regressions)
• Transparency report generated </success_criteria>

<critical_constraint> MANDATORY: Read the session transcript before making any changes MANDATORY: Classify failure type before determining patch strategy MANDATORY: Update the actual rule file, not create duplicates MANDATORY: Report all changes transparently with expected outcome MANDATORY: Verify patch doesn't break existing functionality No exceptions. Systematic reflection requires systematic analysis. </critical_constraint>