/os-optimizer

name: os-optimizer
description: "Framework-driven audit and optimizer for any markdown vault. Applies 10 frameworks covering CLAUDE.md quality, wiki structure, compression, context rot, memory, progressive disclosure, hygiene, cross-file synthesis, architecture and discoverability, plus F10 Claude 5 rule rewriting. F9 walks the real discovery chain (root CLAUDE.md, routing, folder index, file) and audits routing tables against folder reality. F10 rewrites rules written for older Claude models into judgment plus the reason, and proposes the documented Claude Fable 5.1 vault guardrails where they are missing. Every finding ships a concrete fix; the user picks apply-now or save-to-plan per finding. TRIGGERS: os optimizer, optimize vault, vault audit, second brain audit, clean up vault, framework audit, discoverability check, architecture audit, reorg vault, rewrite my rules, audit my CLAUDE.md, my rules feel too strict. Run from vault root."
disable-model-invocation: true

Vault Optimizer

Apply 10 frameworks to every markdown file in the vault. For each framework, read its pass-implementation file, run every check, log findings, walk the user through fixes per item, apply (or save to a plan). Save one comprehensive HTML report grouped by framework. **Do not inline the HTML in chat — only the saved path and a one-paragraph summary.**

Operating philosophy — read carefully, this is what makes this skill different

1. **Every finding ships a concrete fix.** No flag-only. No "warn and forget." No manual-review pile. When the user runs apply-mode, every finding becomes either an applied edit, a saved migration step in a dated reorg plan, or (only if the user explicitly declines this finding in walk) a recorded decline. Nothing lingers as an open warning across runs. 2. **Severity is informational, not gating.** `fail` / `warn` / `info` describes how load-bearing the issue is; it does *not* gate whether a fix is offered. Every check produces fixes. 3. **Walk per item, user picks the target.** Bulk-apply is reserved for purely mechanical fixes (em dashes, duplicate H1). Anything semantic — wikilink repointing, merges, routing rewrites, Plot.md generation, reorganizations — is walk-only with the user confirming the destination/winner/wording per item. 4. **Two modes for every fix:** *apply now* (executes in this run) or *save to plan* (writes the change as a checklist step into the **plan file**, whose path is resolved from the role registry in Step 4.3). User picks per finding for high-blast-radius items. Smaller fixes default to apply-now. 5. **Visible progress, never silent.** Step 0.5 creates one TaskCreate entry per stage and per framework; tasks update `in_progress` → `completed` as the run unfolds. The user watches the audit walk through the vault rather than waiting for one big report at the end. 6. **Read and reason, don't just match.** Every framework's triggers surface candidates; every finding requires the agent to read context, judge alignment with the user's stated world, and produce reasoning specific to the case. No paraphrased rule restatements as "reasoning." 7. **Discover structure, never assume folder names.** Vaults vary. One user's curated layer is `Context/`; another's is `About/`, `Me/`, frontmatter on root, or scattered across topic folders. The optimizer runs Step 1.5 (role discovery) before any framework, and every framework references **roles** (context-equivalent, decisions-equivalent, daily-equivalent, folder-index convention…) discovered from content — never hardcoded names. If a role is missing, it surfaces as a finding with a proposed fix ("you have no decisions-equivalent folder; here's a recommendation"), not as a silent assumption. Static path references in pass files are always abstractions; the agent resolves them through the role registry at run time.

Frameworks

| # | Framework | Reference (the *why*) | Pass file (the *how*) | Applies to | |---|---|---|---|---| | F1 | Anthropic CLAUDE.md | `references/anthropic-claude-md.md` | `references/passes-anthropic-claude-md.md` | every `CLAUDE.md` | | F2 | Karpathy LLM Wiki | `references/karpathy-llm-wiki.md` | `references/passes-karpathy-wiki.md` | wiki content notes | | F3 | Caveman compression | `references/caveman-compression.md` | `references/passes-caveman.md` | instruction-layer files | | F4 | Chroma context rot | `references/chroma-context-rot.md` | `references/passes-chroma-context-rot.md` | every `.md` | | F5 | Anthropic Memory | `references/anthropic-managed-memory.md` | `references/passes-anthropic-memory.md` | every `.md` | | F6 | Progressive Disclosure | `references/progressive-disclosure.md` | `references/passes-progressive-disclosure.md` | every `SKILL.md` | | G7 | General Hygiene | (project rules + practitioner notes) | `references/passes-general-hygiene.md` | every `.md` | | F10 | Claude 5 Rule Rewriting | `references/claude-5-rules.md` | `references/passes-claude-5-rules.md` | every `CLAUDE.md`, `.claude/rules/`, and every `SKILL.md` | | F8 | Reflection (Anthropic Dreams) | `references/anthropic-dreams.md` | `references/passes-reflection.md` | every folder where `layer == "curated"` in the Step 1.5 registry; reads the session-layer folders as evidence | | F9 | Architecture & Discoverability | `references/anthropic-architecture.md` | `references/passes-architecture.md` | whole vault — root CLAUDE.md, routing, every folder's `Plot.md`, the navigation chain end-to-end |

When running a check, **read the pass-implementation file** and follow its regex / heuristic / finding format exactly. Don't paraphrase. Cite the framework reference in every finding.

Flow

1. **Verify the cwd looks like a vault** — light check (Step 0) 2. **Create the visible task list** — TaskCreate one task per stage + framework (Step 0.5) 3. **Discover & classify every `.md` file** — only technical skips (Step 1) 4. **Iterate frameworks F1 → F10**, applying each framework's lens with agent judgment; F10 = rule