reflecting

Reflecting

Overview

Reflecting IS converting experience into reusable knowledge.

Analyze what worked, what failed, and encode learnings into the appropriate component (law, skill, rule, or documentation).

Core principle: Experience without reflection is wasted. Capture it before context is lost.

Violating the letter of the rules is violating the spirit of the rules.

Routing

Pattern: Tree Handoff: auto-invoke (per classification) Next: writing-claude-md | writing-skills | writing-rules

Task Initialization (MANDATORY)

Before ANY action, create task list using TaskCreate:

TaskCreate for EACH task below:
- Subject: "[reflecting] Task N: <action>"
- ActiveForm: "<doing action>"

Tasks:

1. Analyze conversation
2. Identify learnings
3. Classify each learning
4. Integrate into components
5. Review integrated components
6. Verify integration
7. Generate summary

Announce: "Created 7 tasks. Starting execution..."

Execution rules:

1. TaskUpdate status="in_progress" BEFORE starting each task
2. TaskUpdate status="completed" ONLY after verification passes
3. If task fails → stay in_progress, diagnose, retry
4. NEVER skip to next task until current is completed
5. At end, TaskList to confirm all completed

Task 1: Analyze Conversation

Goal: Review the conversation to identify significant events.

Look for:

• Successes: Patterns that led to good outcomes
• Failures: Errors, multiple attempts, dead ends
• Discoveries: New insights about the project/domain
• Repetitions: Actions performed multiple times

Document each event:

Event: [What happened]
Context: [When/where it occurred]
Outcome: [Success/failure/discovery]

Verification: Listed at least 3 significant events.

Task 2: Identify Learnings

Goal: Extract actionable learnings from events.

For each event, ask:

• What would have prevented this failure?
• What made this succeed that could be repeated?
• What did we learn that applies beyond this task?

Learning format:

Learning:
  context: [When this applies]
  insight: [What was learned]
  evidence: [Specific event that taught this]

Verification: Each event has at least one learning.

Task 3: Classify Each Learning

Goal: Determine where each learning belongs.

Classification Decision Tree

Is it true across ALL projects?
├─ Yes → USER ROOT (~/.claude/)
│   ├─ Universal behavior → ~/.claude/CLAUDE.md
│   └─ Convention/pattern → ~/.claude/rules/*.md
└─ No → PROJECT LEVEL (.claude/)
    ├─ Is it IMMUTABLE (must enforce every response)?
    │   ├─ Yes → LAW in .claude/CLAUDE.md
    │   └─ No → Is it a CAPABILITY (how to do)?
    │       ├─ Yes → SKILL
    │       │   └─ Is it SHARED across multiple skills?
    │       │       ├─ Yes → Also extract to RULE
    │       │       └─ No → Keep in Skill only
    │       └─ No → Is it a CONVENTION (what to do)?
    │           ├─ Yes → RULE in .claude/rules/
    │           └─ No → DOCUMENTATION only

Scope Signals

Signal	Scope
"This applies regardless of language or framework"	User root
"This is about how I work, not what I'm building"	User root
"This mistake could happen in any project"	User root
"This is specific to this codebase's architecture"	Project
"This convention only makes sense here"	Project

Classification Guide

Type	Characteristics	Example
User-root law	Universal, every project	"Show reasoning for decisions"
User-root rule	Cross-project convention	"Go edits must combine imports"
Project law	Immutable, this project only	"Always display laws"
Skill	How to do something, reusable	"How to write tests"
Rule	Convention, path-scoped	"API responses use { data, error }"
Documentation	Reference, not actionable	"Architecture overview"

Verification: Each learning has a classification.

Task 4: Integrate Into Components

Goal: Add learnings to the appropriate components.

For User-Root Learnings

1. Read current ~/.claude/CLAUDE.md and relevant ~/.claude/rules/*.md
2. Check: does an existing rule already cover this? → update, don't duplicate
3. If new rule needed → edit ~/.claude/rules/ directly (user-root has no writing-* skill chain)
4. Keep rules concise. One learning = one line.

For Project-Level Laws

Invoke writing-claude-md skill or edit CLAUDE.md directly.

For Skills

Invoke writing-skills skill to create/update skill.

For Rules

Invoke writing-rules skill to create rule file.

For Documentation

Add to appropriate references/ or docs/ location.

CRITICAL: Invoke the appropriate skill for project-level components—don't create them directly.

Verification: All learnings integrated into components.

Task 5: Review Integrated Components

Goal: Run reviewer agents on all newly created/modified components.

For each component created in Task 4, invoke its reviewer:

Component Type	Reviewer Agent
CLAUDE.md (law)	claudemd-reviewer
Skill	skill-reviewer
Rule	rule-reviewer
Hook	hook-reviewer
Subagent	subagent-reviewer

Agent tool:
- subagent_type: "rcc:[reviewer-name]"
- prompt: "Review [component type] at [path]"

If reviewer returns "Needs Fix" or "Fail": Fix the issues before proceeding.

Verification: All new/modified components pass their reviewer.

Task 6: Verify Integration

Goal: Confirm learnings are correctly integrated.

Check:

• New instructions added to CLAUDE.md (if broadly applicable)
• New skills pass validation
• New rules have correct paths: scope
• Documentation is in correct location

Test:

• Laws: Verify they display in responses
• Skills: Verify they activate on triggers
• Rules: Verify they inject on matching files

Verification: All integrated components work correctly.

Task 7: Generate Summary

Goal: Document what was captured.

Summary Format

## Reflection Summary

### Session Context
[What work was done]

### Learnings Captured

| Learning | Classification | Location |
|----------|----------------|----------|
| [insight] | law/skill/rule/doc | [path] |

### Components Modified
- Laws: [new/updated laws]
- Skills: [new/updated skills]
- Rules: [new/updated rules]

### Recommendations
- [Future improvements]

Verification: Summary accurately reflects all changes.

When to Reflect

Trigger reflection after:

• Completing a significant feature
• Resolving a difficult bug
• Multiple failed attempts → eventual success
• Discovering something unexpected
• End of long working session

Don't wait for "later"—context fades quickly.

Red Flags - STOP

These thoughts mean you're rationalizing. STOP and reconsider:

• "Nothing worth capturing"
• "I'll remember this"
• "Too small to document"
• "Reflection is overhead"
• "Skip classification, just document"

All of these mean: You're about to lose valuable learnings. Follow the process.

Common Rationalizations

Excuse	Reality
"Nothing learned"	Every session has learnings. Look harder.
"I'll remember"	You won't. Context fades. Capture now.
"Too small"	Small learnings compound. Capture them.
"Overhead"	10 minutes now saves hours later.
"Skip classification"	Wrong location = unfindable. Classify properly.

Flowchart: Reflection Process

digraph reflecting {
    rankdir=TB;

    start [label="Reflect on work", shape=doublecircle];
    analyze [label="Task 1: Analyze\nconversation", shape=box];
    identify [label="Task 2: Identify\nlearnings", shape=box];
    classify [label="Task 3: Classify\neach learning", shape=box];
    integrate [label="Task 4: Integrate into\ncomponents", shape=box];
    review [label="Task 5: Review\ncomponents", shape=box, style=filled, fillcolor="#e8e8ff"];
    review_pass [label="All\npassed?", shape=diamond];
    verify [label="Task 6: Verify\nintegration", shape=box];
    works [label="All\nworking?", shape=diamond];
    summary [label="Task 7: Generate\nsummary", shape=box];
    done [label="Reflection complete", shape=doublecircle];

    start -> analyze;
    analyze -> identify;
    identify -> classify;
    classify -> integrate;
    integrate -> review;
    review -> review_pass;
    review_pass -> verify [label="yes"];
    review_pass -> integrate [label="no\nfix"];
    verify -> works;
    works -> summary [label="yes"];
    works -> integrate [label="no\nfix"];
    summary -> done;
}

References

• Use writing-claude-md for laws
• Use writing-skills for capabilities
• Use writing-rules for conventions
• Use agent-architect for classification help