// Reflect on the conversation and update docs/. Use when wrapping up, after mistakes or corrections, or when significant codebase knowledge was gained. Complements the automatic Stop-hook reflection (`.claude/hooks/docs-reflection.sh`) — invoke this manually for a deeper pass. Triggers: "reflect", "remember this".
Read/write the docs/ vault — this project's persistent memory. Use for any task that persists knowledge: reflection, planning, gotchas, principles, or direct edits. Triggers: docs/ modifications, "add to docs", "remember this".
Turn a rough feature request into a concrete spec file at `specs/pending/<slug>.md`. Read the codebase first, then ask the user targeted questions, then write the spec. Use when the user says "design a spec", "spec this out", "/design-spec", or hands you a feature idea that needs to become a concrete spec before implementation starts.
Audit and evolve docs/ — prune outdated content, discover cross-cutting principles, review skills for structural encoding opportunities. Triggers: "meditate", "audit the docs".
Mine past Claude Code conversations for uncaptured patterns, corrections, and knowledge. Cross-references with existing docs/. Triggers: "ruminate", "mine my history".
Produces a single-file interactive HTML explainer (dark theme, embedded React demos via CDN) by editing a self-contained template in place, written in Josh Comeau's conversational voice. Use when the user asks for an "interactive guide", "blog post explainer", "Josh Comeau style writeup", "visual deep-dive", "make this visual", or wants to turn a technical topic into a learning page with playable demos.
| name | reflect |
| description | Reflect on the conversation and update docs/. Use when wrapping up, after mistakes or corrections, or when significant codebase knowledge was gained. Complements the automatic Stop-hook reflection (`.claude/hooks/docs-reflection.sh`) — invoke this manually for a deeper pass. Triggers: "reflect", "remember this". |
Review the conversation and persist learnings — to docs/, to skill files, or as structural enforcement.
This is the manual counterpart to .claude/hooks/docs-reflection.sh, which nudges automatically on stop. Use this skill mid-session, or when the auto-nudge fires and you want a deliberate pass.
docs/index.md and skim relevant subsection indexes (docs/principles.md, docs/plans/index.md) to understand what's already captured@effect/ai, Vitest, oxlint, etc.)docs/principles.md and docs/plans/index.md indexes regenerate automatically — don't hand-edit them. Update docs/index.md only if the new content deserves a top-level mention.Not everything belongs in docs/. Route each learning to where it will have the most impact.
Before routing a learning to docs/, ask: can this be a lint rule (oxlint), a script in package.json, a bun run check step, a type, or a runtime check in the code itself? If yes, encode it structurally and skip the doc note. See docs/principles/encode-lessons-in-structure.md.
docs/)Codebase knowledge, principles, gotchas — anything that informs future sessions. The default destination. Use the brain skill for the writing conventions.
docs/principles/, gotchas under docs/patterns/, recipes under docs/guides/, plans under docs/plans/.docs/index.md is curated — only edit if the new content earns a top-level entry..agents/skills/<skill>/)If a learning is about how a specific skill works — its process, prompts, or edge cases — update the skill directly.
docs/backlog.md)Follow-up work that can't be done during reflection — bugs, non-trivial rewrites, tooling gaps.
## Reflect Summary
- Docs: [files created/updated, one-line each]
- Skills: [skill files modified, one-line each]
- Structural: [rules/scripts/checks added]
- Backlog: [follow-up items filed]