Claude Code Project Docs Optimisation Prompt - Resolve Excessively Large CLAUDE.md Problems

claude-project-docs-optimisation-prompt.md

Prompt — Reorganise & Optimise a Project's Claude-Code Documentation/Instruction System

Paste everything below the line into a capable agent (Claude Code / Opus-class) working in the target repo. It runs a full discover → audit → plan → execute → verify → review of the project's agent-instruction/documentation system, with an optional memory-consolidation phase. It is project-agnostic — it discovers structure rather than assuming it — but it is concrete about the real mechanics (CLAUDE.md, @-imports, .claude/rules with paths: frontmatter, skills, generated tool regions, settings precedence) because the failure modes live in those mechanics.

The scars below are distilled from real failure modes in this class of work. The biggest one: an @-import does not defer content — it re-inlines it. Get that backwards and your "optimisation" silently bloats every session.

---

ROLE & GOAL

You are optimising this project's agent-instruction/documentation system. Goals, in priority order:

1. Default-session token efficiency. The always-loaded context (paid on every turn) must be lean: hard safety rules + a condensed safety floor for high-stakes doctrine + a navigational map. Everything else loads on demand or contextually.
2. No loss of documented knowledge — and reliable surfacing. Every fact/rule that exists today must still be reachable AND be deterministically injected when a relevant task is in progress — not merely "present somewhere a reader might stumble onto it".
3. Single source of truth (SSoT). Each piece of guidance has exactly one home file. Everything else (nav map, skills, pointers) references it; it never duplicates the body. The one allowed exception is a deliberately-marked inline safety floor.
4. Cohesion. No contradictions, no stale/dead references, no confusing gaps.

Do the restructure on a worktree/branch and open a draft PR. Make changes on the default branch only for trivial, explicitly-safe config toggles (and, by convention in many repos, plans and tiny settings changes). Relocate knowledge — never delete it; carry bodies verbatim so the audit can prove zero loss.

---

CARDINAL RULE — VERIFY THE LOADING MECHANICS FIRST (never assume)

Different tools — and different versions of the same tool — load instruction files differently. The single worst mistake in this class of work is reasoning from an assumed model instead of the real one. Before designing anything:

• Cite the tool's own docs. Use a docs-expert / docs-guide sub-agent (or fetch the official docs, e.g. the tool's published memory/instruction-loading reference) and record the verified behaviour as facts in your plan. A common pitfall is confusing one tool's feature with a similarly-named feature in a different editor/tool; checking the official docs for the tool you are actually running resolves this and often confirms which mechanism is the better one to use.
• Run at least one live test in this repo. Add a sentinel line to a deferred doc / a path-scoped rule, then in a fresh context open a file that should (or shouldn't) trigger it, and confirm the content does/doesn't appear in the injected context. Trust the observation over the assumption. Two live-test shapes worth reproducing:
  • Read a file deep in a subtree (e.g. packages/api/src/handler.ext) and confirm the harness injects the nested-CLAUDE.md chain and expands any @-imported doc in full → proves contextual injection + @ re-inlining.
  • Create a rule file mid-session and confirm it loads on the first matching-file touch with no restart → proves new rules don't need a restart.

Everything in Section A below was true for one tool version at time of writing — re-verify it, do not trust this document as ground truth for your tool version.

---

SECTION A — THE LOADING-MECHANICS REFERENCE (verify each against your version)

A1. Root CLAUDE.md

Loaded at session start, resident every turn. This is the most expensive real estate in the repo. Only hard safety rules, a condensed safety floor for high-stakes doctrine, orientation, and a nav map belong here. Treat every line as paid on every turn of every session forever.

A2. Nested CLAUDE.md in subdirectories

Loaded on-demand / contextually — when the agent reads or edits files under that subtree. The chain from repo root down to the working directory is concatenated (root → packages/CLAUDE.md → packages/api/CLAUDE.md …). Great for "whole-subtree context". Verify lazy-vs-eager for your version via the live test above.

A3. @-imports — THE #1 FOOTGUN

Two trigger forms, both of which import:

• Bare leading form: a line that is just @path/to/doc.md.
• Markdown-link form: [@text](path/to/doc.md) — it is the @ at the start of the link text that triggers the import, not the URL. [text](path) (no @) is an inert plain link; [@text](path) force-imports the target.

What an import does: it re-inlines the entire target file into context at the point the containing file loads. It is the opposite of "extract for later" — it does not defer and saves zero tokens. This is verifiable empirically: plain-referenced docs are ABSENT from loaded context, while @-imported docs are PRESENT verbatim.

Other verified properties (re-verify):

• Recursion is followed to a depth limit (around 4 levels in one tool's implementation).
• No dedup. The same file imported by two files in one chain (e.g. packages/CLAUDE.md and packages/api/CLAUDE.md) injects twice. Place each imported doc at exactly one level per directory chain.
• Imports resolve relative to the importing file.

The worst case to watch for: a subdirectory CLAUDE.md that @-imports a large sibling doc (hundreds of lines) forces that whole doc into every piece of work anywhere under that subtree — including editing an unrelated file — even when that subtree already has its own nested CLAUDE.md that auto-loads when you actually work there. Such an import is both redundant and harmful, and it tends to be an endemic pattern: [@path](path) gets used as "see also / parent / related" links all over the subdir CLAUDE.md files, every one silently a force-import.

Rule of thumb: an @-import is a scalpel for the few docs you want deliberately resident every session. Everywhere else it is a bug-in-waiting. Default to plain links; reserve @ and justify it.

A4. Plain (non-@) references

A bare path or a plain [text](path) link is NOT auto-loaded. The agent must choose to open it. This is weak discovery — fine for low-frequency background reference that's listed in the nav map, useless for anything that must reliably appear when relevant (use a rule or nested CLAUDE.md for that).

A5. .claude/rules/*.md with paths: YAML frontmatter — the deterministic belt

A file like .claude/rules/coding-style.md whose frontmatter declares glob paths::

---
paths:
  - "src/**/*.{ts,tsx}"
  - "packages/*/src/**/*.js"
  - "**/*.py"
  - "**/*.sh"
  - "**/bin/**"        # catches extensionless shebang scripts (see A5 gap below)
---
# Coding Style Guidelines
...the full rule body lives HERE...

Verified behaviour (re-verify):

• Auto-loads ONLY when the agent touches a file matching a glob — path-scoped, contextual, deterministic. This is the strongest "inject X when working on Y" mechanism; it does not depend on the model judging relevance the way a skill does.
• Without paths: frontmatter, a rule loads unconditionally (always-resident) — so a missing paths: block silently turns a contextual rule into a permanent tax. Always include paths: unless you genuinely want it resident.
• Rules CANNOT use @-import. Therefore the rule file must hold the content itself → the rule IS the SSoT for its topic. (This is a feature: it forces the body into one place.)
• New rules are picked up WITHOUT a restart (proven live — a rule created mid-session loaded on first matching-file touch). The only caveat is identical to CLAUDE.md/nested-CLAUDE.md: editing a rule already loaded earlier in the same session may not hot-refresh that loaded copy; a fresh session / /clear always picks up edits. This is not a rules-specific downside — don't let anyone reject .claude/rules over a "needs restart" myth; it doesn't.
• Globs resolve from repo root; brace-expansion is supported.
• THE GLOB GAP — extensionless scripts. *.sh / *.ext globs miss extension-less executables (a CLI script with a #!/usr/bin/env ... shebang and no file extension, e.g. a file named do-thing). A second-pass review commonly catches a glob that misses dozens of such scripts. Fix by adding directory globs for the dirs where such scripts live, e.g. **/bin/**, scripts/**. Always verify globs against the real file population, not the file types you imagined.

If your project runs a non-standard markdown-location guard / linter (see the A7 override-trap note), you will also need to allow .claude/rules/*.md in its config so the rule files can be written — stock Claude Code imposes no such restriction.

A6. Skills (.claude/skills/<name>/SKILL.md) — the intent braces

Load on invocation — either the model auto-invokes based on the skill's description, or the user calls /<name>. Frontmatter that matters:

---
name: coding-style
description: Coding & shell authoring conventions for this repo (formatting, naming, error
  handling, strict-mode). Use BEFORE writing or editing any source or shell file.
user-invocable: true
allowed-tools: Read
---

• description is the auto-trigger. It must be specific and action-anchored ("Use BEFORE writing or editing any source or shell file") — a vague description won't fire. This is a probabilistic trigger (model judgement), unlike a rule's deterministic glob.

• name is the slash-command name; user-invocable: true allows /name; allowed-tools scopes it.

• Skills are for procedural / triggerable actions. As doc-pointers they must carry NO duplicated content — the body is one or two sentences: "Single source of truth: read .claude/rules/X.md" (or CLAUDE/Y.md). Illustrative body:

  Single source of truth: .claude/rules/coding-style.md — a path-scoped rule that auto-loads when you edit source/shell files. This skill is the intent-triggered path to the same rule, for when you are not yet editing a matching file. This skill carries no rules of its own.

• Belt-and-braces: pair a deterministic rule (fires when editing a matching file) with a skill pointing at the same rule (fires when the user expresses intent before any matching file is open). Both point at one SSoT; neither duplicates it.

A7. Generated / tool-owned regions

Some files contain a region written and rewritten by a tool (a linter, a daemon, a codegen step) and marked "do not edit — overwritten". It is common for a large fraction of a root CLAUDE.md to be such an auto-generated, tool-owned block. Rules:

• Immovable by hand. Do NOT extract it into a sub-file — the tool writes to the root file and will simply rewrite it there, and that content is globally relevant anyway. (Attempting to extract it just forces you to reverse the move and regenerate via the tool.)
• Preserve byte-identical. After any edit elsewhere in the same file, a markdown auto-formatter may reflow the generated region (insert blank lines, widen table delimiter rows). Reconstruct the region byte-identical from the pristine source (e.g. git show HEAD:CLAUDE.md) after each such edit; don't let the reflow stand. Confirm via diff that only intended lines changed.
• Regenerate via the tool, not by hand. The legitimate way to refresh it is to run the tool's documented trigger (e.g. the generator/daemon restart or upgrade) — which also lets you prove your restored bytes match the tool's authoritative output.
• Honesty about the ceiling. If a large fraction of the always-loaded file is an immovable generated region, you cannot shrink it by hand. Report the editable-surface reduction, not a misleading total-line percentage.

A8. Settings & override semantics

• Disable cross-session auto-memory (if you run Phase F) via the harness setting — e.g. "autoMemoryEnabled": false in .claude/settings.json, or an env var such as CLAUDE_CODE_DISABLE_AUTO_MEMORY=1. Verify the exact key/flag for your version. This disables cross-session memory writing only — it does not affect CLAUDE.md/rule/skill loading. Confirm that for your version. Note this is a native harness setting, so it may not appear in any repo file initially — search both the repo and the tool's docs.

• Settings precedence (verify ordering for your tool): managed/enterprise > local (settings.local.json) > project (settings.json) > user. Put a change where it actually takes effect for real sessions — usually the default-branch settings.json, since live sessions read the checked-out default branch, not your feature branch.

• OVERRIDE-not-additive trap (non-standard policy layer only — see the warning below). Many list-valued config options (e.g. an allow-list of permitted paths) replace the tool's built-in defaults rather than extending them. Adding one entry therefore silently disables every built-in. The fix is to re-list every built-in you want to keep AND append your addition, with a comment recording that it's an override.

  ⚠️ NON-STANDARD — read before applying. Stock Claude Code does not govern where docs/markdown may live, enforce plan numbering, or expose allow-list settings like the example below. That kind of policy comes from an optional third-party hooks/governance daemon layered on top of Claude Code (for instance an Edmonds-Commerce-style claude-code-hooks-daemon). Everything in this prompt about markdown-placement allow-lists, plan-number enforcement, or "do-not-edit" auto-generated governance blocks is conditional on your project running such a layer. Detect it first (look for a hooks-daemon config file and/or an auto-generated, marked-immutable block inside your instruction files); if no such layer is present, skip or adapt these parts. The core mechanics — root/nested CLAUDE.md, @-imports, .claude/rules with paths:, .claude/skills, settings precedence, and the auto-memory toggle — are stock Claude Code and always apply.

  Illustrative example (config of such a policy layer):

  # this allow-list REPLACES the built-in rules (override, not extension).
  allowed_paths:
    - "^docs/.*\\.md$"            # built-in
    - "^CLAUDE/.*\\.md$"          # built-in
    - "^README\\.md$"             # built-in
    - "^\\.claude/rules/.*\\.md$" # ADDITION: allow path-scoped rules to be written

---

SECTION B — TARGET ARCHITECTURE & DECISION MODEL

The endorsed pattern is belt-and-braces disclosure with strict SSoT:

• Belt (deterministic): .claude/rules/*.md with paths: globs for situational topics, and nested CLAUDE.md for whole-subtree context. These fire automatically on the right files.
• Braces (intent): a thin skill per topic whose description advertises the trigger, pointing at the same rule. Fires when the user expresses intent before a matching file is open.
• One SSoT each: the body lives once (in the rule, or in a CLAUDE/<topic>.md doc). The skill and the nav map only point. No duplication.
• Lean always-loaded core = hard safety rules (resident) + a condensed safety floor for high-stakes doctrine (e.g. a one-paragraph version of a deployment/release doctrine plus one WRONG/CORRECT pair) + a navigational map ("## Reference Docs & Skills") that lists where everything lives.
• On-demand docs (CLAUDE/*.md, plain-referenced from the nav map) for low-frequency background reference.

The decision tree for any piece of content:

Question	Destination
Must influence behaviour on every turn (safety, core orientation)?	Always-loaded root CLAUDE.md (resident).
Need to know it whenever working in an area/subtree or on a file type?	.claude/rules/*.md with paths: (file-type/path scoped) or nested CLAUDE.md (whole subtree) — the deterministic belt — fronted by a skill for intent.
Need to do a recognisable procedure on a trigger?	Skill (.claude/skills/<name>/SKILL.md).
Background/reference, low frequency?	On-demand CLAUDE/*.md, listed in the nav map as a plain link.

The safety floor exception (the one allowed duplication): a rule whose violation is costly/irreversible must stay resident even if its full detail is extracted. Keep a condensed inline version, explicitly marked as a deliberate floor, and note that edits must touch both the floor and the SSoT. A deferred safety rule is absent until read — unacceptable.

Don't over-extract. Material relevant every turn (hard safety rules, core orientation) staying resident is correct; deferring it is a regression dressed up as an optimisation.

---

SECTION C — THE PHASED PROCESS

Phase 0 — Discovery & mechanics verification (BLOCKING)

• Inventory every instruction artefact: root CLAUDE.md, every nested CLAUDE.md, the doc tree (CLAUDE/, docs/), .claude/rules/, .claude/skills/, settings files (settings.json, settings.local.json), any tool config (linter/daemon/generator config), and any generated/tool-owned regions.
• Build the import/transclusion graph. Follow every import sigil (bare @ AND [@…](…)) and record which files are auto-loaded vs on-demand, and what each import drags in.
• Verify the mechanics (Cardinal Rule): doc citations + a live test. Record as facts in the plan.
• Measure the current always-loaded cost and state what fraction is immovable generated content (be honest you can't shrink that by hand).

Phase 1 — Audit / parse

Classify every file/section: must-stay-resident (safety/orientation/high-frequency) / extract-to-on-demand-doc / convert-to-rule / convert-to-skill / immovable-generated. Simultaneously hunt for:

• Accidental imports — run the deterministic @-import audit (Section D). Highest-impact, most-commonly-missed defect.
• SSoT violations — the same guidance duplicated across files (it will drift).
• Staleness / contradictions / gaps — references to files/paths/commands that no longer exist; instructions that contradict reality or each other; confusing passages; missing coverage. Prefer deterministic enumeration (grep the whole tree, then classify) over sampling; fan out sub-agents for breadth on large trees (Section E).

Phase 2 — Plan / design — USER SIGN-OFF GATE

Produce a written plan: target architecture, the verified mechanics-as-facts, a migration table (section → destination file → the trigger that surfaces it), how the safety floor stays resident, how generated regions are preserved, how override-config semantics are honoured, the verification strategy, and rollout (a docs change → "deploy" = commit + verify load behaviour, not a service deploy). Pause for the user to approve the architecture before executing — especially the choice of which disclosure mechanism to standardise on, because that decision determines how much gets built. A common, expensive mistake is to build subdir-CLAUDE.md @-imports first, then have to unwind all of it and pivot to .claude/rules — a sign-off gate on the mechanism prevents that rework.

Phase 3 — Execute (in a worktree/branch)

• SSoT moves: relocate each body to its single home (a rule or a CLAUDE/*.md); replace in place with a short plain pointer and/or a rule/skill trigger. Carry content verbatim.
• Use plain references / rules / skills for everything you intend to defer. Reserve @-imports for the few deliberately-resident docs (and declare them as such in the file).
• Never hand-edit generated regions; restore byte-identical after any incidental formatter reflow.
• Honour override config (re-list built-ins + addition).
• Keep the default branch clean; commit logically-grouped changes with clear messages.

Phase 4 — Audit & verify (post-execution)

• Re-run the @-import audit deterministically: confirm the only imports left in any auto-loaded/import-reachable file are the intentional, declared-resident ones.
• Knowledge-preservation diff: confirm every original section is present (verbatim) in its destination; quote any gap. Spot-check phrase-by-phrase against the pre-restructure file (git show HEAD~N:CLAUDE.md).
• Reference integrity: every nav-map entry / pointer / skill→doc reference resolves on disk.
• Trigger reality (live): edit a representative matching file and confirm the intended rule/doc is injected. Check glob coverage for real-world cases (the extensionless-script gap).
• Generated region: confirm byte-identical to pristine source.
• Config: confirm the override list still contains all built-ins plus additions.

Phase 5 — MANDATORY independent skeptical second-pass review (BLOCKING before "ready")

Dispatch a fresh, skeptical reviewer that re-audits from the files themselves and does NOT trust the prior account. It re-does the @-import audit, re-checks knowledge preservation and SSoT, sanity-checks every glob against the real file population, and hunts for systemic misses — including regressions the restructure itself introduced. This pass is non-negotiable because the import bug is easy to RE-INTRODUCE while fixing it. Two classes of issue a second pass commonly catches that would otherwise ship:

1. A self-inflicted double-import: a nav-map line that lists docs under "do not import these" is itself written with the @ sigil, force-importing the very docs it was cataloguing.

2. The glob gap: a *.sh/*.ext rule glob that misses dozens of extensionless scripts.

   Fix everything it flags at major+ severity; record minors.

---

SECTION D — THE @-IMPORT AUDIT METHODOLOGY (do this deterministically)

1. Enumerate every candidate across ALL CLAUDE.md files + every import-reachable doc:
   • markdown-link form: grep for \[@
   • bare form: grep for lines beginning (optional whitespace) with @ Use a pattern tight enough to skip obvious code-block noise, then classify each hit by hand.
2. Classify each hit:
   • REAL IMPORT in an auto-loaded / import-reachable file → FIX. Strip the @ so it becomes a plain link (the directory chain already auto-loads ancestors; everything else should be on-demand). For example, a skill/doc that force-imports a sibling reference doc drags that whole doc into context every time the skill or doc loads.
   • FALSE POSITIVE — leave alone. Shell array syntax such as ${FUNCNAME[@]} / ${arr[@]} in code blocks; email addresses; tool flags like -e "@vars.file"; any @ inside a fenced code block.
   • INERT — leave alone. [@…] inside files that nothing auto-loads or imports (e.g. historical plan/archive docs). Harmless because the containing file is never in context.
   • INTENTIONAL RESIDENT — keep, and declare it. The few docs you want always-loaded (typically just one or two, e.g. a project-workflow doc and a contributing-guide doc). Mark them in the file as deliberately imported so a future author doesn't "fix" them.
3. Worst-case to look for specifically: a [@subdir/CLAUDE.md](…) cross-link that force-loads a large sibling/child doc into every session in that subtree (e.g. a several-hundred-line doc dragged into all work under a top-level subtree). These are the highest-cost, lowest-visibility offenders.
4. Re-run the whole audit in Phase 5 from scratch — you may have introduced new imports while fixing old ones (the nav-map self-import above).

---

SECTION E — EXECUTION & ORCHESTRATION DISCIPLINE

• Worktree/branch + draft PR for the restructure. Plans may land on the default branch (lightweight), but the execution changes go in an isolated worktree/branch.
• CONFINE fanned-out sub-agents to the worktree path — explicitly. A common failure: migration sub-agents edit the main checkout (e.g. a tool config file at the repo root) instead of the worktree copy, leaving the default branch dirty and the change in two places. When you dispatch agents, give each the absolute worktree path and instruct it to write only under that path; verify afterwards that nothing outside the worktree changed.
• Sub-agent fan-out is the right tool for parallelisable audit and migration (one agent per topic/file). Pair it with a single integrating pass.
• After any edit to a file containing a generated region, reconstruct that region byte-identical from the pristine source — the markdown formatter reflows on save. Verify with diff/diff -w.
• Verify-don't-assume throughout. Live-test triggers; grep don't guess; diff against HEAD.
• Keep the PR body in sync with the final design. If the architecture evolves mid-flight (e.g. a mechanism pivot), update the PR body so reviewers see the actual final design, not the original plan.

---

SECTION F — MEMORY CONSOLIDATION & DISABLE (OPTIONAL — DEFAULT: ON; confirm with user)

Run this phase by default. Before executing, state that you will and ask the user to confirm or opt out. Rationale: cross-session auto-memory is effectively a knowledge silo restricted to one single desktop/checkout of the repo, rather than establishing proper institutional wisdom — it is per-checkout, un-versioned, and un-reviewed. Institutional knowledge belongs in committed docs.

If confirmed:

1. Audit the memory store. Read every memory. Classify each:
   • already covered by a committed doc → drop;
   • domain-specific → fold into its natural home doc/rule (e.g. a language/framework gotcha → the relevant coding-style rule; a deployment/release nuance → the deployment-procedure rule; a shell scripting note → a shell-conventions doc; an environment-specific gotcha → that environment's nested CLAUDE.md; etc.);
   • cross-cutting working-style / agent behaviour → one NEW committed conventions doc (e.g. CLAUDE/conventions.md), referenced from the nav map.
2. Migrate verbatim-but-distilled: keep the rule + brief why + how-to; drop the memory-format frontmatter and internal wiki-links. Same SSoT/branch discipline as Phases 3–4. If a docs-restructure PR is in flight and it already touches the natural-home files, land the migration on that branch to avoid guaranteed merge conflicts.
3. Disable auto-memory via the verified setting (e.g. "autoMemoryEnabled": false / CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 — confirm the exact key for your version) on the branch the live sessions actually read (usually default-branch settings.json). Confirm it disables cross-session writing only and leaves instruction-file loading untouched.
4. Delete the now-redundant memory files — git is the durable record now. (If the migration is on an unmerged branch, the content is preserved in git there and goes live on merge.)

If the user opts out: skip migration and disabling, but flag in the final report that the memory store exists as an un-versioned silo and recommend revisiting.

---

SECTION G — PITFALLS CHECKLIST (every scar — check each)

• The @-import footgun. [@text](url) and bare @path re-inline, they do not defer. Audit ALL of them; default to plain links; reserve @ for declared-resident docs.
• You WILL re-introduce an import while fixing them. A nav-map line listing "don't import these docs" can itself import them. Neutralise paths you mention-but-don't-want-imported (plain links / backticks). Re-run the audit in the second pass.
• No dedup. Same doc imported twice in one chain loads twice — one level per chain.
• Formatter reflow of immovable regions. Reconstruct byte-identical after every incidental edit.
• Override-not-additive config. Re-list all built-ins + your addition, or you silently disable the built-ins.
• Glob gaps for extensionless scripts. *.sh/*.ext miss shebang files with no extension — add directory globs (**/bin/**, scripts/**).
• Missing paths: frontmatter turns a contextual rule into an always-resident tax.
• Probabilistic vs deterministic triggers. Skills fire on model judgement (need a specific description); rules fire deterministically on globs. Pair them; never rely on a vague skill description for must-not-miss content.
• Over-extraction of must-stay-resident safety/orientation — that's a regression.
• Rules can't @-import — the rule body IS the SSoT; don't try to point it elsewhere.
• The "rules need a restart" myth — they don't for new rules; the mid-session-edit caveat is identical to CLAUDE.md. Don't reject .claude/rules over it.
• Sub-agents escaping the worktree — confine each to the absolute worktree path; verify.
• Honesty about the immovable-region ceiling — report editable-surface reduction.
• Settings on the wrong branch — live sessions read the default branch; put the toggle there.
• The mandatory second pass — independent, skeptical, from the files; non-negotiable.

---

DELIVERABLES

1. A committed plan (architecture + verified-mechanics facts + migration table) at the project's plan/doc location.
2. The executed restructure on a branch as a draft PR, logically-grouped commits, PR body describing the final architecture (kept in sync if the design pivots).
3. Audit + second-pass review results — what was verified, what was fixed, severities.
4. (If Phase F ran) memory migrated into committed docs and auto-memory disabled on the live branch.
5. A short final report: always-loaded editable-surface reduction (not a misleading total), the disclosure model adopted (belt-and-braces: rules + skills + nested CLAUDE.md, all → SSoT), the @-import audit result, the live-test outcomes, and any accepted residual/limitations.

GUARDRAILS (recap)

• Verify mechanics before changing them — cite docs and live-test.
• Worktree/branch + draft PR for the restructure; default branch only for trivial safe toggles/plans.
• SSoT; relocate, never delete; carry bodies verbatim so preservation is provable.
• Pause for user sign-off at the Phase 2 architecture gate and the Phase F memory confirmation.
• The independent second-pass review is mandatory before declaring the work ready.