Reflect Skill

Post-session learning loop: Capture what worked, what caused friction, and embed those insights back into the codebase's context engineering.

Purpose

Learnings about workflow friction, missing context, and skill gaps evaporate after sessions. This skill closes that loop by mining git history and artifacts, identifying friction points and successful patterns, and producing concrete improvement proposals. Approved proposals are applied with atomic commits.

Output: Reflection artifact at docs/plans/YYYY-MM-DD-{topic}-reflection.md

When to Use

Use this skill when:

• A substantive session just finished (feature, refactor, debugging)
• Workflow friction was noticeable during the session
• A skill felt incomplete or produced unexpected results
• New conventions emerged that should be documented
• CLAUDE.md or hooks need updating based on experience

Don't use for:

• Mid-session course corrections (just fix it directly)
• Trivial sessions with no learnings
• Reviewing someone else's work (use code review instead)

Workflow

1. Establish Session Context — BEFORE Plan Mode

If the trigger includes a topic, use it. Otherwise, use AskUserQuestion to ask:

• What session or feature did you just finish?
• Which skill(s) did you use (if any)?
• What felt off or notably well?

Derive a reflection slug from the topic (e.g., auth-feature, payment-refactor).

2. Dispatch 4 Parallel Context Agents — BEFORE Plan Mode

CRITICAL: Dispatch ALL agents in a SINGLE message with run_in_background: true.

Agents need full tool access, so this step MUST happen before plan mode.

See agent prompts for full templates.

3. Collect Agent Results — BEFORE Plan Mode

• Poll agents with TaskOutput block: false to check progress
• Collect completed results with TaskOutput block: true
• If an agent returns thin results, note the gap — do NOT dispatch a follow-up

4. Enter Plan Mode

Call EnterPlanMode — synthesis is a read/write-only activity.

5. Synthesize and Write Reflection Artifact — IN Plan Mode

Use the reflection artifact template to structure the output.

Cross-reference agent findings to identify:

• What worked well — patterns to preserve or document
• Friction points — where the session slowed down or went wrong
• Missing context — information that should have been in CLAUDE.md or skills
• Improvement proposals — concrete changes to make

Categorize each improvement using the taxonomy from the improvement guide.

Improvement types:

Constraints:

• Cap at 5 proposals max, priority-ordered
• Each proposal includes: Type, Priority (P1-P3), Target file, Current state (quoted), Proposed change, Rationale

Write the reflection artifact to the plan file.

6. Exit Plan Mode — User Reviews

Call ExitPlanMode to present the reflection for review.

Then use AskUserQuestion to list each proposal with its type and target. Ask the user to pick: All / None / specific items by number.

7. Apply Approved Improvements

For each approved proposal:

1. Read the target file
2. Apply the change using Edit or Write
3. Commit with message: reflect: <description>

One improvement per commit. Do NOT bundle multiple changes.

8. Persist Artifact

Save the reflection artifact:

docs/plans/YYYY-MM-DD-{topic}-reflection.md

Commit with: reflect: add session reflection for {topic}

Anti-Patterns to Avoid

• Don't invent problems — only propose improvements for friction that actually occurred during the session
• Don't propose more than 5 improvements — prioritize signal over noise
• Don't bundle multiple fixes in one commit — one improvement per commit
• Don't update ~/.claude/CLAUDE.md — it's auto-overwritten by tech-pass; use ~/.claude/CLAUDE.local.md
• Don't add hooks that already exist — read .claude/settings.json first
• Don't dispatch agents inside plan mode — they need full tool access; dispatch before entering plan mode
• Don't propose sweeping rewrites — small, targeted improvements compound better

After Reflect

Once improvements are applied:

1. Review the reflection artifact in docs/plans/
2. Verify applied changes with git log --oneline -5
3. Consider whether any deferred proposals should become issues or tasks
4. The next session benefits automatically from the updated context