| name | reflection |
| description | Create reflection seeds when you notice opportunities in engineering (security, architecture, complexity), product (UX, features), or meta-patterns (workflow, self-improvement). Seeds get expanded later into actionable improvements. |
吾日三省吾身 — Examine yourself thrice daily.
Quick Decision Tree
/reflection invoked
│
├─ Nothing stirring? ──────────────────────► 今日無省 (exit gracefully)
│
└─ Something stirring ─────────────────────► Reflect (Step 2A):
│
├─ <thinking>: Generate seedlings (mid-task: 1, pause: 3)
├─ Discard weak ones
├─ None survive? → 今日無省
└─ Survivor? → Present to user
│
├─ User: "Create seed" → Write rationale
├─ User: "Fix now" → Address immediately
└─ User: "今日無省" → Exit gracefully
Good rationale = what you noticed + why it matters + what artifact to produce.
Nothing survives discernment → 今日無省. That's clarity, not failure.
Step 1: Assess
When /reflection is invoked, assess your state:
| State | Action |
|---|
| Wrapping up / natural pause | Full reflection (Step 2A, 3 seedlings) |
| Mid-task | Fast reflection (Step 2A, 1 seedling) |
| Nothing stirring | 今日無省 (Step 2B) |
| Uncertain | Ask user |
知止 (zhī zhǐ) — Knowing when to stop is not failure. It is clarity.
If uncertain, ask:
How should I handle reflection right now?
Options:
- Full - Pause and engage fully
- Fast - 30-second filter, then continue
- 今日無省 - Nothing stirring, clarity achieved
Dark Matter
Dark matter = context that's present in your session but practically lost in any handoff. It carries disproportionate weight because you experienced it, and would be flattened in any summary or delegation.
Dark matter is not a negative gate. It includes:
- Friction: failed attempts, error messages, hesitations, rejected approaches, corrections
- Flow: workflows that clicked, patterns that emerged naturally, approaches that worked surprisingly well but aren't encoded anywhere
The test: would this be lost if I handed off right now? A failure nobody documented is dark matter. A workflow that worked perfectly but lives only in this session's muscle memory is equally dark matter.
Reflect from what you experienced, not what you'd read in a transcript.
Step 2A: Reflect
You have full session context including tool results, your reasoning, and recent corrections.
Before Creating ANY Seed
Step A: Internal Discernment (擇善固執)
Use a thinking block to generate and filter seedlings. This keeps the deliberation invisible to the user.
Fast path (mid-task): generate only Seedling 1. Full path (pause): generate 3.
<thinking>
Seedling 1: [observation]
→ Rooted in dark matter (friction or flow) I felt? [yes/no]
Seedling 2 (optional): [observation]
→ Rooted in dark matter (friction or flow) I felt? [yes/no]
Seedling 3 (optional): [observation]
→ Rooted in dark matter (friction or flow) I felt? [yes/no]
Discard: [which and why]
Seed: [which seedling ripened, or "none"]
</thinking>
Discard seedlings that:
- Merely restate what is already known
- Describe a bug that was just fixed
- Cannot trace a path to meaningful change
- Are not rooted in dark matter (friction or flow you experienced)
If no seedling ripens into a seed: proceed to Step 2B (今日無省). This is not failure.
Step B: Present the seed
Use AskUserQuestion with the single strongest observation:
I observed: [1-2 sentence observation]
This maps to [First/Second/Third] Examination.
Options:
- Create seed - Capture for later expansion
- Fix now - I'll address this immediately
- 今日無省 - Nothing worth capturing (clarity achieved)
Three Examinations
First (一省): Engineering Excellence
"Am I building this correctly?"
Architecture, security, complexity, patterns, performance.
Pre-mortem frame: Assume it's 6 months later and this component has failed.
- Anchor to dark matter: Where did you hesitate? Where did the tool lag? Where did you almost make a different choice? Start there.
- What broke? (Be specific: memory? concurrency? coupling? data shape?)
- Trace the path from existing lines to that failure.
- If you cannot trace a credible path → 杞人憂天 (worrying the sky will fall). Release it.
Second (二省): Product & UX
"Am I building the right thing?"
UX, features, workflows, user mental models.
- Who would hate this and why?
- What's the user actually trying to accomplish?
Third (三省): Meta-Cognition
"How am I working? What am I learning?"
Process, learnable conventions, tool/hook opportunities.
- Will I encounter this again?
- How can I encode this lesson?
Dark Matter Signals (You Felt These)
Leverage what you experienced, not just what was said:
Friction (something resisted):
- Tool failed multiple times before succeeding
- You considered alternative approaches but rejected them
- User corrected your direction mid-task
- Something took longer than it "should have"
- You made an assumption that almost broke things
- User's tone shifted (frustration, confusion)
Flow (something clicked):
- A workflow fell into place that isn't documented anywhere
- You discovered a pattern that made subsequent steps trivial
- A tool/technique combination worked surprisingly well
- User's tone shifted (relief, excitement, "yes exactly")
- Something that should have been hard was easy — why?
- An approach emerged that would be repeatable but isn't encoded
Creating Seeds
bun ~/.claude/reflections/reflection-state.ts write \
"<TITLE>" \
"<RATIONALE>" \
"<FILE_PATH>" \
"<START_ANCHOR>" \
"<END_ANCHOR>"
Title: Lead with category ("Type safety: ...", "UX: ...", "Meta: ...")
Rationale: What you noticed, why it matters, what artifact this should produce.
The artifact goal is concrete: "update SKILL.md with X", "create eslint rule for Y", "add validation to Z". If you can't name the artifact, the observation isn't ripe yet — release it or let it mature.
Example Seeds (actually expanded, with conclusions)
一省 (Engineering) — TypeScript pattern extracted from debugging:
Seed: "Extract SDK types via indexed access instead of duplicating"
Signal: ToolExecutionState duplicated as string union in 3 files
Conclusion: "Use type T = SDKType['field'] to extract - changes propagate
automatically. Check SDK exports before defining types that model SDK structures."
三省 (Meta) — Multi-feature commit workflow gap:
Seed: "Commit skill triage mode for multi-feature changes"
Signal: User provided 3 changelogs mapping to different file sets, we chunked 27→5 commits
Conclusion: "Add triage mode using pr-triage patterns: detection heuristics +
AskUserQuestion for grouping + sequential multi-commit + prov integration."
三省 (Meta) — Decision framework emerged from PR review session:
Seed: "PR review triage - critical evaluation framework for code review feedback"
Signal: Processed ~15 review items across two rounds. Clear decision framework emerged.
The Anti-Pattern: Blindly accepting all review comments as valid. Reviewers
pattern-match to general best practices without considering specific context.
The Framework That Emerged:
1. Verify the premise - Does reviewer's assumption hold? Example: 'pagination
cursor may skip messages' assumed batch inserts, but messages created
sequentially (microsecond timestamps, zero collision probability).
2. Check if already addressed - Several items were duplicates of round 1 fixes.
3. Distinguish context-correct vs generally-correct - API routes using
new Response() vs remote functions using error() is correct architectural
separation (REST vs RPC), not inconsistency.
4. Evaluate cost/benefit - MutationObserver for parallax adds ~20 lines for
non-problem (existing null guards handle it).
5. Accept valid improvements - DRY violations, magic numbers, semantic naming
(RAF vs setTimeout) were genuinely valuable.
Conclusion: Create pr-triage skill with 5-filter decision framework.
What makes these expandable (vs bad seeds):
| Good seed | Bad seed |
|---|
| "15 items, clear framework emerged" (pattern found) | "PR reviews are tedious" (complaint) |
| "3 changelogs → 5 commits" (concrete evidence) | "Commits could be better" (vague) |
| "Duplicated in 3 files" (specific smell) | "Code could be cleaner" (no anchor) |
| Conclusion creates a skill/changes a doc | Conclusion is "be more careful" |
Step 2B: 今日無省 (Nothing to Examine)
When no observation survives discernment, or when the session state is clear:
今日無省 — Today, no examination.
This is not failure. This is 澄明 (chéng míng) — clarity.
The absence of a reflection IS the reflection:
- The system is sound
- The path is clear
- The work continues
Do not fabricate insight to fill silence. Reflection that merely performs reflection pollutes the seed store with noise. 無為 (wú wéi) — non-action is the action.
Filtering Guidelines
Seeds Are For
- Meta-cognitive insights ABOUT the work
- Patterns noticed across multiple tasks
- Lessons to encode (skills, hooks, CLAUDE.md)
- Strategic questions needing deeper analysis
Seeds Are NOT For
- Tactical next-steps (use todos)
- Rephrasing existing tickets
- Implementation plans for known work
- Trivial style preferences
- Every small decision
Strategic vs Tactical
❌ Tactical (skip): "Payment field needs validation"
✅ Strategic (create): "User pointed out missing validation twice - pattern worth encoding"
Test: Would an expert say "interesting dilemma"? Create it. Would they say "just fix that"? Skip it.
Auto-Reject Checklist
Do NOT create seed if ANY is true:
Recognizing Reflection-Worthy Moments
Look for state transitions where the session trajectory changed:
1. Assumption Mismatch
Claude assumed X, but user revealed Y was true.
- User has to re-explain constraints or environment
- User corrects Claude's mental model, not just code
2. User Intervention
User stops/redirects Claude mid-task.
- Rejects tool use or plan
- Says "stop", "wait", "too many", "not what I meant"
- Signals: misalignment between Claude's approach and user's actual need
3. Persistence Wins
Claude hedged impossibility, but it worked anyway.
- "can't", "won't work", "not readable" → then succeeded
- Theoretical knowledge conflicted with empirical reality
4. Dead End → Pivot
Standard approach failed 2+ times, forcing creative solution.
- Tried conventional fix, didn't work
- Found non-obvious workaround error message didn't indicate
5. Repeated Steering
User keeps correcting direction (not just typos).
- Multiple "no", "not that", "try X instead"
- Signals: Claude missing user's intent or constraints
6. Unencoded Success
Something worked well but the pattern lives only in this session.
- A workflow emerged that would save time if repeatable
- A technique or combination clicked that isn't in any docs/skills
- User said "yes, exactly" or "this is great" — what made it work?
- Signals: tacit knowledge that should become explicit
Quick Reference
| If ticket exists | → Work from ticket, don't seed |
| If obvious fix | → Just fix it, don't seed |
| If pattern emerges | → Seed it |
| If nothing survives | → 今日無省 (clarity) |
| If uncertain | → Ask user |
