// Audit and evolve docs/ — prune outdated content, discover cross-cutting principles, review skills for structural encoding opportunities. Triggers: "meditate", "audit the docs".
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.
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.
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".
| name | meditate |
| description | Audit and evolve docs/ — prune outdated content, discover cross-cutting principles, review skills for structural encoding opportunities. Triggers: "meditate", "audit the docs". |
Quality bar: A note earns its place by being high-signal (Claude would reliably get this wrong without it), high-frequency (comes up in most sessions or most tasks of a type), or high-impact (getting it wrong causes significant damage or wasted work). Everything else is noise. A lean, precise vault outperforms a comprehensive but bloated one.
sh .agents/skills/meditate/scripts/snapshot.sh docs/ /tmp/docs-snapshot.md
sh .agents/skills/meditate/scripts/snapshot.sh .agents/skills/ /tmp/skills-snapshot.md
Files are delimited with === path/to/file.md === headers. The snapshot scripts already exclude repos/ and node_modules/. Also locate the auto-memory directory (~/.claude/projects/<project>/memory/).
Spawn general-purpose subagent. See references/agents.md for the full prompt spec. Inputs: docs snapshot, auto-memory path, CLAUDE.md path.
Audits doc notes, CLAUDE.md, and auto-memory for staleness, redundancy, low-value content, verbosity, and orphans. Returns a categorized report.
Early-exit gate: If the auditor finds fewer than 3 actionable items, skip step 3 and go directly to step 4.
Spawn one general-purpose subagent. See references/agents.md for the full prompt spec. Inputs: docs snapshot, skills snapshot, auditor report, docs/principles.md.
Combines three concerns in a single pass:
Present the user with a consolidated summary. See references/agents.md for the report format.
Check all reports for findings that belong in skill files, not docs/. Update the skill's SKILL.md or references/ directly. Read the skill first to avoid duplication.
Apply all changes directly. The user reviews the diff.
[[wikilinks]]docs/principles/. The auto-index hook regenerates docs/principles.md on the next tool use.Verify docs/principles.md and docs/plans/index.md regenerated correctly after any file additions or removals. docs/index.md is curated — only update by hand if a top-level entry changed.
## Meditate Summary
- Pruned: [N notes deleted, M condensed, K merged]
- Extracted: [N new principles, with one-line + evidence count each]
- Skill review: [N findings, M applied]
- Housekeep: [state files cleaned]