Refactor Instructions

Refactor a monolithic CLAUDE.md or AGENTS.md into a small, focused root file that points to topic-specific files via progressive disclosure.

Why this matters

• The root file loads on every agent request. A bloated file steals tokens from the actual task and pushes the agent past its effective instruction budget (~150–200 rules before attention drops).
• Stale docs poison context. File paths rot fastest — if the root says "auth lives in src/auth/handlers.ts" and that file moved, the agent confidently looks in the wrong place. Describe capabilities, not structure.
• Instruction files grow as balls of mud when rules are added reactively after every agent misstep. Small and focused beats comprehensive. Reference nested docs instead of inlining.

Process

1. Detect target files. Run ls CLAUDE.md AGENTS.md at the repo root. Handle whichever exist. In monorepos, also check **/AGENTS.md and **/CLAUDE.md — nested files merge with the root at their scope. If both CLAUDE.md and AGENTS.md exist with different content, surface this to the user: they may want a symlink (ln -s AGENTS.md CLAUDE.md) so every tool sees the same file.

2. Read every target file in full before proposing anything. Do not rely on skimming.

3. Find contradictions. List every pair of instructions that conflict. For each, use AskUserQuestion to ask which version to keep. Do not silently pick.