Reference Doc Routing
A reference document tells you what someone intended. The code tells you what is true. Route documents so you get the intent without inheriting the drift.
Full detail: references/reference-doc-routing.md.
Workflow
- Identify what actually needs reference context. Much of a task is answerable from the code alone. Reading a document you did not need costs context the code needed.
- Find the candidates — global references under the Claude Code home, and repository docs.
- Classify each one:
- Authoritative — instructions make it the source of truth. Follow it; raise conflicts rather than deviating.
- Advisory — useful, but current code, tests, or user instructions override it.
- Historical — may describe decisions or behavior that no longer exist.
- Read narrowly.
Grep for the symbol, endpoint, table, or concept, then read around the hits. Read end to end only when the task really is about the whole subject.
- Check for drift. Does it reference files, symbols, or endpoints that no longer exist? Do its examples use an API shape the code has moved past? Does it predate a migration visible in the history? Does it contradict the tests?
- Verify anything implementation-relevant against the code before you rely on it.
- Report conflicts between a document and primary evidence. Do not silently pick one — work out whether the doc is stale, the code is a bug, or the code is deliberately working around something.
Passing documents to a subagent
A subagent has a fresh context and sees only what you send. Send the path, the section, and the label:
Reference documents:
- docs/api-contracts.md, "Checkout" section — authoritative. Follow these
request and response shapes exactly.
- docs/architecture.md, "Payments" section — advisory, last updated before the
Stripe migration. Verify anything you take from it against current code.
Verify implementation-relevant claims against the current code. Do not
summarize unrelated sections.
An unlabeled document is treated as truth. That is how you get back confident work built on a stale premise.
Ask for evidence, not agreement: the subagent should return the paths and symbols it checked, not a restatement of what you sent.
Primary evidence
Current code, tests, schemas, configuration, logs, build output, typecheck output, runtime behavior, and authoritative external documentation.
1---2name: reference-doc-routing3description: Use when a task might need architecture, testing, access-control, design-system, API, release, data-model, subagent, or worktree reference documents. Helps pick the ones that matter, judge how much authority each has, read only the relevant sections, and pass concise labeled context to subagents.4---56# Reference Doc Routing78A reference document tells you what someone intended. The code tells you what is true. Route documents so you get the intent without inheriting the drift.910Full detail: `references/reference-doc-routing.md`.1112## Workflow13141. **Identify what actually needs reference context.** Much of a task is answerable from the code alone. Reading a document you did not need costs context the code needed.152. **Find the candidates** — global references under the Claude Code home, and repository docs.163. **Classify each one:**17 - **Authoritative** — instructions make it the source of truth. Follow it; raise conflicts rather than deviating.18 - **Advisory** — useful, but current code, tests, or user instructions override it.19 - **Historical** — may describe decisions or behavior that no longer exist.204. **Read narrowly.** `Grep` for the symbol, endpoint, table, or concept, then read around the hits. Read end to end only when the task really is about the whole subject.215. **Check for drift.** Does it reference files, symbols, or endpoints that no longer exist? Do its examples use an API shape the code has moved past? Does it predate a migration visible in the history? Does it contradict the tests?226. **Verify anything implementation-relevant against the code** before you rely on it.237. **Report conflicts** between a document and primary evidence. Do not silently pick one — work out whether the doc is stale, the code is a bug, or the code is deliberately working around something.2425## Passing documents to a subagent2627A subagent has a fresh context and sees only what you send. Send the path, the section, and **the label**:2829```text30Reference documents:31- docs/api-contracts.md, "Checkout" section — authoritative. Follow these32 request and response shapes exactly.33- docs/architecture.md, "Payments" section — advisory, last updated before the34 Stripe migration. Verify anything you take from it against current code.3536Verify implementation-relevant claims against the current code. Do not37summarize unrelated sections.38```3940An unlabeled document is treated as truth. That is how you get back confident work built on a stale premise.4142Ask for evidence, not agreement: the subagent should return the paths and symbols it checked, not a restatement of what you sent.4344## Primary evidence4546Current code, tests, schemas, configuration, logs, build output, typecheck output, runtime behavior, and authoritative external documentation.
ArcanEdge-AI