cc-reflection: teaching Claude Code to reflect - provi

Claude Code has an EDITOR hook - Ctrl-G. It opens a temp file in your editor, you write, save, close, and whatever you wrote gets injected back into Claude’s input box. The hook doesn’t care what happens between open and close. It just watches the file.<br>That gap is a black box. I replaced the gap with an fzf menu. Now Ctrl-G opens a control surface where any operation can run: edit your prompt with your IDE, enhance your prompt with an agent, browse and expand reflection seeds, and collapse its result back into the prompt file.<br>cc-reflection is what grew from within that black box. It’s not one system but several, wired together: a reflection skill that teaches Claude three lenses for self-examination, a dice accumulator that builds pressure over turns until it triggers organically, a seed store that captures observations, and a thought agent that expands seeds into codebase-grounded artifacts. The EDITOR hook is the connective tissue, and the menu is the container. Each piece works independently, but the hook gives them a shared surface.<br>Modeling how we actually reflect<br>Reflection is always after the fact. You observe what happened, not what is happening. Something in the work catches your attention and you go: huh. That’s the whole event. A small noticing.<br>Most of the time you’re mid-feature. You don’t want to pivot the session over a hunch. So you let it go. It dissolves. Whatever you half-noticed rejoins the noise and you never think about it again.<br>cc-reflection gives that moment a place to land. When a /reflection triggers, the agent assesses whether there’s anything worth surfacing using a designer skill. Sometimes there isn’t, and that’s fine. When there is, you get three choices: fix it now, dismiss it, or create a seed.<br>A seed is the interesting one. It captures the observation with a proposed artifact - what concrete action this thought might lead to. Then you move on. The session continues. The seed sits in the background, in the framework and in the back of your head, and it grows.<br>Actually engaging with a thought is expensive. It requires context-switching, holding multiple perspectives, stepping outside the work to look at it. You rarely do it in the moment. You come back later, when you have headspace, and open the menu. Your seeds are there, sorted by freshness. You pick one and engage. This is where the thought agent comes in. It gets a full interactive session: it reads the seed, pulls up the relevant code, reconstructs the context. You steer it. You add thoughts you’ve had since. It expands the seed into a detailed, codebase-grounded analysis with a clear next step.<br>That expansion can become a prompt you feed back to your main agent, like a sophisticated plan mode grown from a single observation. Or you let the thought agent make the changes directly. There’s freedom in how you use it.<br>The core design bet: noticing and analyzing compete for the same attention. If you try to do both in the moment, you either derail execution with second-guessing or suppress the observation to maintain flow. Seeds let you notice without analyzing. Expansions let you analyze without rushing.<br>The three examinations<br>The /reflection skill teaches Claude three lenses, borrowed from Confucius (吾日三省吾身 - I reflect upon myself thrice daily):<br>一省 : “Am I building this correctly?” - architecture, security, complexity, engineering patterns<br>二省 : “Am I building the right thing?” - UX, product, business logic, user mental models<br>三省 : “How am I working?” - process, conventions, workflow, skills and hooks<br>These aren’t categories for organizing notes. They’re lenses the agent applies in sequence when the skill fires. For each, it generates seedlings internally, tests them (“is this rooted in something I actually felt during the session?”), and discards the ones that don’t survive. A seedling that merely restates what’s already known, or describes a bug that was just fixed, gets rejected. Most reflections produce nothing.<br>That’s by design. 今日無省 - nothing to examine today. The skill treats silence as clarity, not failure. Fabricating insight to fill the space would pollute the seed store with noise. The framework’s most important output is often no output at all.<br>When thoughts surface<br>You can’t schedule insight. Real reflection happens because enough unexamined experience has accumulated that something pushes through. The longer the session, the more likely it is to happen.<br>The dice accumulator models this. After 7 (default) turns without reflection, the system starts rolling 1d20 behind the scenes at every turn. After 14 turns, 2d20. After 21, 3d20. Any natural 20 triggers an explicit nudge for the agent to reflect and a reset. Short sessions are never interrupted. Long sessions eventually get one, but when is unpredictable.<br>The dice decides when to reflect. The skill knows what to look for: moments where the session’s trajectory changed. The agent assumed something...