/content-allocation

name: content-allocation
description: "One topic, one home. Routes content to its canonical store (CLAUDE.md, PROJECT.md, MEMORY.md, docs/, memory/) and audits for duplication. TRIGGER when: auditing CLAUDE.md/PROJECT.md/MEMORY.md sizes, deduplicating docs, applying the content-allocation pattern to a new repo, running /align --content. DO NOT TRIGGER when: implementing features, writing tests, routine code edits, debugging."
allowed-tools: [Read, Write, Edit, Bash, Glob, Grep]

Content Allocation

A methodology for keeping project context lean and unambiguous. Every piece of content has exactly one canonical home; every other appearance is a one-line pointer.

Methodology: One Topic, One Home

**Core rule**: If a piece of content lives in two places, one of them is wrong. The canonical store owns the content; every other location is a one-line pointer to it.

Why this matters:

• `CLAUDE.md` and `MEMORY.md` are loaded **every turn**. Every line there has compounding cost across the project's lifetime.
• Duplication drifts. When the same fact lives in two files, the next edit will update one and leave the other stale.
• Readers (humans and assistants) waste tokens hunting through redundant copies for the authoritative version.

The pattern works in three moves:

1. **Identify the canonical home** for a topic using the routing table below. 2. **Move the content** to that home. Compress all other appearances to a single-line pointer (`See: docs/RUNBOOK.md`). 3. **Enforce size budgets** so the canonical home does not bloat into a second copy of the wider docs tree.

---

Routing Table

The canonical stores in a typical Claude Code project, in load-order:

| Store | Loaded | Owns | Does NOT own | |-------|--------|------|--------------| | `~/.claude/CLAUDE.md` (global) | every turn, every repo | Assistant default behaviour; user's machines, SSH, session history queries | Anything project-specific | | `CLAUDE.md` (project root) | every turn, this repo | Hard rules, gates, canonical paths, pointers, top-N gotchas | Vision, purpose, architecture, history, current state, deep reference | | `.claude/PROJECT.md` | session start | Purpose, GOALS, SCOPE, CONSTRAINTS, alignment criteria, project philosophy | Behaviour rules; operational sequences; full architecture diagrams; current state | | `memory/MEMORY.md` + `memory/*.md` | MEMORY auto-loaded; files retrievable | Durable lessons (with *why*), findings, calibration, active state | Hard rules; full architecture | | `docs/RUNBOOK.md` | on demand | Operational sequences (periodic maintenance, batch finalize, resumes, common queries) | Architecture; rules | | `docs/architecture/*.md` | on demand | High-level system architecture, layers, diagrams, ADRs | Behaviour rules; deep component internals | | `docs/<TOPIC>.md` (per-domain) | on demand | Deep reference per topic (testing, security, hooks, libraries) | Behaviour; vision | | Plugin user-facing `docs/*.md` | on demand | Shipped-with-plugin reference (commands, troubleshooting) | Maintainer-internal flows | | GitHub issues | on reference | Current/open/closed work, decision threads | Anything else |

If a topic spans two stores: the *narrative* lives in PROJECT.md or docs/; the *rule* lives in CLAUDE.md; both reference each other as 1-line pointers.

---

Routing Decision Algorithm

When you have new content to place, walk this 9-step ordered list and stop at the first match:

1. **Does it change behaviour every turn?** ("always do X / never do Y") → `CLAUDE.md` Critical Rules section. 2. **Does it describe scope, purpose, or architecture?** ("why this project exists, what's in/out of scope") → `.claude/PROJECT.md`. 3. **Is it a durable lesson + the *why*?** ("we learned X because Y") → `memory/feedback_*.md` (+ one-line index entry in `MEMORY.md`). 4. **Is it active state or a current finding?** ("session N discovered Z, still unresolved") → `memory/finding_*.md` (+ index entry). 5. **Is it an operational sequence?** ("how do I do X — the steps") → `docs/RUNBOOK.md`. 6. **Is it reference data?** (registries: hooks, agents, skills, libraries, commands) → `docs/<REGISTRY>.md`. User-facing command catalogue → plugin's `docs/COMMANDS.md`. 7. **Is it a pitfall or gotcha with a reproducer?** → memory if recent and repeatable; `docs/<TOPIC>.md` if catalogued. 8. **Is it deep architectural detail?** → `docs/<TOPIC>.md` (e.g. `HOOK-COMPOSITION.md`, `SECURITY.md`). 9. **Is it a plugin-user-facing fix?** → plugin's `docs/TROUBLESHOOTING.md`.

If you reach step 9 without a match, the content is probably scratch work or belongs in a GitHub issue.

---

Size Budgets

Auto-loaded files have hard ceilings. Exceed them and you pay the cost every turn.

| File | Target | Hard ceiling | Why | |------|--------|--------------|-----| | `CLAUDE.md` | ≤100 lines | 200 | Loaded every turn. A size-validation hook should warn above 200. | | `.claude/PROJECT.md` | ≤150 lines | 200 | Loaded at session start. Above 200 = operational drift, not architecture. | | `MEMORY.md` | ≤150 lines | 200 | Often truncated above 200 when auto-loaded. | | `memory/*.md` (individual) | 1–3 KB | 3 KB | >3 KB usually means it should be promoted to a `docs/` page. |

Rules of thumb:

• `MEMORY.md` entries should be **≤150 chars per line**. If you cannot summarise a finding in one line, the underlying file needs splitting.
• Memory files below **500 bytes** with no active finding should be compressed to an index entry or deleted.
• Never duplicate content between global and project `CLAUDE.md`. Global covers cross-repo assistant defaults; project covers this repo only.

---

Periodic Hygiene Sweep

Run after major refactors or every ~10 sessions:

1. **Audit for duplication** — search `memory/` for content now in `CLAUDE.md` or `PROJECT.md`. Compress duplicates to pointers. 2. **Resolve contradictions** — search for memory files that disagree with each other. The newer or more thoroughly grounded entry wins; the other becom