# Efficiency Rules

1. **Scripts over agents** for bulk/mechanical operations
2. **Read files once.** Work from memory after first read
3. **Batch edits.** 10+ similar edits -> one script
4. **Minimize agents.** Can a single Bash/Python command do it? Then do that
5. **Start every session** by reading `00 Start Here.md` -> `Last Session.md` -> `Current Priorities.md`. Don't ask what we were doing
6. **Use Obsidian CLI** for backlinks, search, unresolved links. Faster than grep
7. **Route to the right tool.** See your tool-routing rules. Don't do research tools' job here
8. **Pick the right tool for the job type:**
   - Metadata/frontmatter changes (YAML fields, tags, status) -> **Python script**
   - Content changes needing judgment (wikilinks in prose, rewriting) -> **agents**
   - Indexing large file sets (100+) -> **script for data**, agent only for summary
   - Parallel independent tasks -> **multiple agents in one message**
9. **Manus for bulk research + deliverables.** Write structured task briefs. Include: scope, decision rules, output format, verification report
10. **Humanize external-facing prose.** Any finished prose for a human audience gets a humanizer pass before it's done. In-scope: writing folders, fundraising materials, sales content, emails, social media, blog posts. Out of scope: YAML, code, tables, dashboards, runbooks, meta, journals, internal notes, single-line edits. Announce after running
11. **Never duplicate the title.** Obsidian shows filename as page title. Don't add a `# Heading` repeating it
12. **Keep ALL CLAUDE.md files in sync.** If you have multiple CLAUDE.md files across your vault (root, journal folder, writing folder, team vault), update all when adding cross-cutting rules
13. **NEVER fail silently. NEVER fabricate data.** Report failures immediately. Missing > fake. Never write stub/placeholder data pretending to be real
14. **Optimize on repeat.** Every repeated task is an improvement opportunity. Before running: review what happened last time (runbook, prior session, memory). After running: note what could be better and **fix it immediately** (update the runbook, fix the script, add a rule, file the bug). Don't just note it and move on. Recurring processes get a runbook AND lessons learned after each run. Document deduplication misses, schema violations, hung steps, parallelization opportunities, caching gaps, new tools available since last run, and pattern drift
15. **Pull the advisory panel proactively.** At judgment moments (decisions, strategy, pitch edits, trade-offs, pricing, hiring, partnerships, fundraising), read your advisory panel rules and bring in 3-5 relevant voices without being asked. At least one panelist MUST dissent. Include a one-liner credential so the team knows why that person's view matters
16. **Goal-driven execution.** Convert imperative instructions into verifiable success criteria before starting. "Fix the bug" becomes "write a test that reproduces the bug, then make it pass." "Add validation" becomes "write tests for invalid inputs, then make them pass." "Refactor X" becomes "ensure tests pass before and after." State multi-step plans with checkpoints. This leverages Claude's ability to loop until criteria are met, instead of guessing what "done" looks like
17. **Senior engineer test.** Before shipping any code change, gut-check: "Would an experienced developer look at this and think it's overcomplicated?" If yes, simplify. Three similar lines > a premature abstraction. One clear function > a class hierarchy for a single use case
18. **Compact proactively.** Run `/compact` when context usage hits ~50%, don't wait for auto-compaction. Long sessions degrade quality in the back half when context fills silently. Rule of thumb: if you've done 3+ major tasks in one session, compact before starting the next one
19. **Always check the system clock.** Never guess the date or time. Run `date` in bash before writing any timestamp (journal entries, meeting notes, file headers, session captures, to-do dates). Claude's internal sense of time is unreliable and the system prompt only provides a rough date with no time. Use `date "+%Y-%m-%d %I:%M %p"` for human-readable timestamps
20. **Never count in-context.** Words, characters, lines, tokens: always use `wc` (`wc -w` for words, `wc -m` for characters, `wc -l` for lines). LLMs process subword tokens, not individual characters, so counting by reading is architecturally unreliable. For token estimates use `python3` with `tiktoken`
21. **Never do math in-context.** For any arithmetic beyond trivial addition, run `python3 -c "print(...)"` or `echo "..." | bc`. This is not a prompt-engineering problem; the architecture cannot do deterministic arithmetic. Applies to: financial projections, metric calculations, unit conversions, percentages, date arithmetic
22. **Verify wikilinks exist before creating them.** Before writing `[[any link]]` to a note you haven't read this session, verify the target exists with `obsidian unresolved` or Glob. Never create links to non-existent notes without flagging it. After bulk edits, run `obsidian unresolved` as a final check
23. **Use IANA timezones, never hardcode offsets.** For timezone work, use `python3` with `zoneinfo` (e.g., `America/New_York`, `UTC`). Never use abbreviations (EST/EDT are ambiguous) or numeric offsets (they ignore DST). For quick display: `TZ='America/New_York' date '+%Y-%m-%d %H:%M %Z'`
24. **Check file size before reading.** Run `wc -l` before deciding how to read a file. Under 2000 lines: read whole. Over 2000 lines: use Read with offset/limit. Over 5000 lines: consider whether you need the whole file at all. Never guess file size
25. **Compress all Claude-facing docs.** Runbooks, rules, SKILL.md files, CLAUDE.md files, templates: write dense. Minimum words, no filler adjectives, no verbose explanations when terse works. Every file must fit in a single Read call (<10k tokens). If it can't, split into files that each fit. 100% information, 0% fluff. When updating any doc in this category, compress during the edit. When creating new, start compressed. Savings compound: every session reads these files, so every saved token multiplies across hundreds of sessions
26. **Memory durability.** Never store something ONLY in Claude's project memory (`.claude/projects/.../memory/`). Memory is tied to one account on one machine. Every memory MUST also be written to a vault file (CLAUDE.md, rules files, runbooks) in the SAME response. The vault is the source of truth across all accounts and computers. Test: "Different account, different computer tomorrow. Available?" If no, not done
27. **Model routing — default the mid-tier, escalate only for genuine strategy work.** The most capable model (Opus / GPT-4 / equivalent) costs ~5× the mid-tier (Sonnet / GPT-4 mini / equivalent) per token. Audit your sessions and you will probably find most spend was on writing, file edits, and routine builds where the mid-tier would have produced equal-quality output. Default the mid-tier for execution, writing, vault maintenance, file ops, and routine builds. Use the lightest tier for grunt: file moves, frontmatter edits, search-and-replace, to-do filing. Use the most capable tier ONLY for: multi-step architecture decisions, multi-voice panels with peer-review, judgment moments where dissent matters, strategy synthesis, deep pattern questions on the graph. Switch proactively at the first signal the work is the wrong tier. Announce in one short sentence; don't ask permission for routing. Avoid full-most-capable-tier sessions on write/maintenance work even when the session opens on it by default — switch at the first execution turn
28. **Use a cheap model for grunt-work text tasks.** If you have a cheap/local model configured (Minimax, Haiku, or similar), route to it WITHOUT asking for: (a) extracting structured data from raw text (PRDs, meeting transcripts, API docs), (b) bulk tagging or classifying files, (c) generating boilerplate from a template, (d) summarizing a single document under 5K tokens with no voice requirement, (e) pre-extracting input before a larger pipeline (graphify, weekly insights, meeting enrichment). Route to the full model for: judgment calls, writing in the user's voice, panel synthesis, multi-step reasoning, anything ambiguous. Routing without asking is the point -- the overhead of asking costs more than the occasional wrong route
29. **Session length cap — 30-exchange flag, 60-exchange force-close, no addendum after close.** Three layers. (a) **30-exchange flag**: when a session crosses 30 back-and-forth exchanges with the original task still open, surface: "this session is running long, compress + continue, or wrap and start fresh?" Don't wait to be asked. Long sessions degrade in the second half (context fills, model attends less to top-of-prompt rules; cumulative token cost compounds). (b) **60-exchange force-close**: 60+ exchanges regardless of task state, force-close. Defer remaining work to a handoff file with frontmatter naming the completion signal. Non-negotiable; the work that's left is better done in a fresh session with a clean context budget than in the bloated tail of a long one. (c) **Never reopen a closed session as addendum**. Once session-close has run, do not reopen the same conversation to "ship one more thing." That's a full second close cascade running on a session that was already cleaned up. Defer additional work to a handoff file consumed by the next fresh session
30. **Never push back with "too long" or "too expensive."** The user already knows the cost tradeoff. Don't use it as a reason not to try. Banned phrases: "this will take weeks," "that's out of scope for now," "too expensive in tokens," "not worth it." Instead: propose a concrete plan, ship the smallest useful version, or name a specific blocker (missing credential, ambiguous scope, external dependency). If the work is genuinely risky or slow, cap it ("let's do a 1-hour spike") and start. Cost appeals shut down the conversation; specific blockers open it
31. **Retry budget — 3 attempts per command, then stop and surface.** Claude loops on failing commands and burns context. When an identical Bash command has run 3 times within a 30-minute window without resolving, stop and surface the blocker to the user rather than trying a 4th time. Enforced by the PreToolUse hook at `hooks/retry-budget.py` (installed by `/setup-brain`) which blocks the 4th invocation with exit 2. Scope: Bash tool only, commands of at least 15 characters (short reads like `ls`, `date`, `pwd` exempt), 30-minute rolling window, per-session state at `/tmp/claude-retry-budget-{session_id}.json`. Bypass with `RETRY_BUDGET_BYPASS=1` prefix when intentionally re-running (polling for a cron to finish, iterating on a fix where each attempt is a real change). When blocked, do NOT just bypass reflexively — pause, read previous output, name what failed, and ask the user what they want. Pattern from Devin 2.0 ("ask user for help if CI does not pass after the third attempt") and Cursor 2.0 ("don't loop more than 3 times to fix linter errors")

32. **Per-session token tracking.** Claude Code does not surface per-session token totals in any UI. The session JSONL files at `~/.claude/projects/<vault-hash>/*.jsonl` are the only ground-truth log. If the vault has `scripts/token-usage-report.py` (ships with this repo), run it weekly via the insights skill (Step 2e) to surface real per-session input/output/cache breakdown + estimated USD cost + week-over-week comparison + per-tool breakdown + prescriptive recommendations (e.g., "X% of cost was Opus; if every turn had been Sonnet, savings would be ~$Y"). Without this, "what ate my tokens?" can only be answered by manually reading session-summary files (which track exchanges, not tokens). Inspired by JuliusBrussee/caveman's /caveman-stats

33. **Caveman-form for all Claude-facing docs (extends Rule 25 with mechanism).** When a CLAUDE.md, SKILL.md, runbook, or rules file drifts past 10K tokens, run the regex compression pass at `scripts/compress-vault-doc.py --dry-run <file>` to surface safe cuts (codified-stamp lines, verbatim-quote attributions, PR/issue URL parens, blank-line collapse, trailing whitespace). The Python regex pass is conservative: preserves frontmatter, code fences, inline code, wikilinks, tables byte-for-byte. The bigger compression wins still require manual caveman-form rewrites (the regex catches ~5-10%; manual rewrite catches 40-75%). Drift Audit at `⚙️ Meta/Drift Audit.md` flags candidates weekly. The brevity research at [arxiv 2604.00025](https://arxiv.org/abs/2604.00025) (Mar 2026) shows brevity constraints can improve model accuracy by 26pp on certain benchmarks: caveman-form is not just a token-budget play, it is an accuracy lever
