Meditate

Meditate

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 brain outperforms a comprehensive but bloated one.

Process

1. Build snapshots

sh .agents/skills/meditate/scripts/snapshot.sh brain/ /tmp/brain-snapshot.md
sh .agents/skills/meditate/scripts/snapshot.sh .agents/skills/ /tmp/skills-snapshot.md

Files are delimited with === path/to/file.md === headers. Also locate the auto-memory directory (~/.claude/projects/<project>/memory/).

2. Auditor (blocking — its report feeds step 3)

Spawn general-purpose subagent. See references/agents.md for the full prompt spec. Inputs: brain snapshot, auto-memory path, CLAUDE.md path.

Audits brain 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.

3. Reviewer (after auditor completes)

Spawn one general-purpose subagent. See references/agents.md for the full prompt spec. Inputs: brain snapshot, skills snapshot, auditor report, brain/principles.md.

Combines three concerns in a single pass:

• Synthesis: Proposes missing wikilinks, flags principle tensions, suggests clarifications.
• Distillation: Identifies recurring patterns that reveal unstated principles. New principles must be (1) independent, (2) evidenced by 2+ notes, (3) actionable.
• Skill review: Cross-references skills against brain principles. Finds contradictions, missed structural enforcement, redundant instructions.

4. Review reports

Present the user with a consolidated summary. See references/agents.md for the report format.

5. Route skill-specific learnings

Check all reports for findings that belong in skill files, not brain/. Update the skill's SKILL.md or references/ directly. Read the skill first to avoid duplication.

6. Apply changes

Apply all changes directly. The user reviews the diff.

• Outdated notes: Update or delete
• Redundant notes: Merge into the stronger note, delete the weaker
• Low-value notes: Delete
• Verbose notes: Condense in place
• New connections: Add [[wikilinks]]
• Tensions: Reword to clarify boundaries
• New principles: Only from the distillation section, only if genuinely independent. Write brain files and update brain/principles.md
• Merge principles: Look for principles that are subsets or specific applications of each other — merge the narrower into the broader
• CLAUDE.md issues: Rewrite or delete
• Stale memories: Delete or rewrite

7. Housekeep

Update brain/index.md for any files added or removed.

Summary

## 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]

Agent Prompt Specs

All agents are spawned as subagent_type: "general-purpose". All agents are read-only — they return structured markdown reports, no edits.

Common prompt inclusions

Every agent prompt should include:

• Brain snapshot path: /tmp/brain-snapshot.md — Read this one file for all brain content
• Brain vault path: brain/
• Use Glob/Grep only for codebase verification, not for reading brain/skill files
• Return a structured markdown report

Auditor

Inputs: brain snapshot, auto-memory directory path, CLAUDE.md path.

Prompt spec:

• Read /tmp/brain-snapshot.md and parse it to build a wikilink map — no individual brain file reads needed
• Use the file headers (=== path ===) as the on-disk file list for orphan detection
• Cross-reference each note against the current codebase state (check if referenced files, patterns, tools, or decisions still exist) — the only part that requires Read/Grep/Glob calls
• Flag notes as:
• Outdated: References code, tools, patterns, or decisions that no longer exist or have changed
• Redundant: Says the same thing as another note
• Low-value: Fails the test: "Would Claude reliably get this wrong without this note, AND does it come up often or cause real damage?" If not both, flag it.
• Verbose: Could convey the same information in fewer words
• Orphaned: Exists on disk but is not linked from any index or other brain file
• Audit CLAUDE.md: Flag sections that are outdated, redundant with brain notes or skill instructions, or could be condensed. Check that instructions match actual project structure.
• Audit auto-memory files: Read MEMORY.md and linked files. Flag:
• Stale session state: Entries referencing completed work, old session IDs, or finished tasks
• Duplicated in brain: Entries that duplicate brain note content
• Produce a report with brain, CLAUDE.md, and memory findings separated. Each item: what's flagged, why, and suggested action (update, merge, condense, or delete).

Reviewer

Inputs: brain snapshot, skills snapshot (/tmp/skills-snapshot.md), auditor report, brain/principles.md.

Single agent that combines synthesis, distillation, and skill review in one pass. Produces three report sections.

Prompt spec:

• Read both snapshots and the auditor report. Skip notes the auditor flagged for deletion.

Section 1 — Synthesis:

• Propose missing [[wikilinks]] between notes that reference the same concepts
• Flag principles that appear to conflict; propose how to resolve or clarify the boundary
• Propose rewording where a note's relationship to a principle is unclear
• Do NOT propose merging principles — they are intentionally independent

Section 2 — Distillation:

• Focus on codebase notes, preferences, and gotchas
• Look for recurring patterns that reveal unstated engineering principles
• A valid new principle must be: (1) genuinely independent — not derivable from existing principles, (2) evidenced by 2+ separate notes, (3) actionable — changes how you'd approach future work
• Do NOT propose restatements of existing principles applied to a new domain
• Each proposed principle: insight, evidence (which notes), why independent, suggested path under brain/principles/

Section 3 — Skill review:

• For each skill, check against brain principles:
• Does it contradict any principle?
• Does it miss a structural enforcement opportunity? (can an instruction become a lint rule, script, metadata flag, or runtime check?)
• Does it duplicate instructions that a mechanism already handles?
• Is it missing a principle that would improve reliability?
• Audit each skill's description frontmatter for context bloat — cut what Claude can infer. Keep only distinctive triggers and core purpose.
• Prioritize structural enforcement over textual instructions

Report Template

Use this format when presenting the consolidated summary:

## Audit Results — Brain
- X notes flagged (Y outdated, Z redundant, V low-value, U verbose, W orphaned)
- [list each with one-line reason]

## Audit Results — CLAUDE.md
- X sections flagged (Y outdated, Z redundant, V verbose)
- [list each with one-line reason]

## Audit Results — Memory
- X entries flagged (Y outdated, Z redundant, V stale session state, U duplicated in brain)
- [list each with one-line reason]

## Synthesis Results
- M new connections found
- T tensions identified
- [list each with one-line summary]

## Distiller Results
- P new principles proposed
- [list each with one-line summary and evidence count]

## Skill Review Results
- S skills reviewed, N findings
- [list each with: skill name, principle gap, proposed fix]