Quest Plan

Vocabulary Drift · 4 levels · populated

Level 1 · Map the vocabulary

A word that means two things is a landmine, not a typo. Inventory the nouns and labels that appear in both your user-facing docs/UI and your agent-facing docs (CLAUDE.md, AGENTS.md, README, in-repo docs/, CLI help text, config keys). For each term, note every place it’s used and what it means there. Flag two specific failure shapes: a single word used for two unrelated concepts in two different layers of the system (a UI toggle and an unrelated setting elsewhere sharing a label like “manual mode”), and a single concept referred to by two or more different names across docs (so an agent grepping for one misses the other). Don’t stop at obviously overloaded words — check names that sound generic enough to be reused by accident: “surface”, “session”, “context”, “profile”, “sync”. Produce a plain list: term, every place it appears, every meaning it carries. When the vocabulary is mapped and every collision or synonym-split is named, run quest_level complete.

Level 2 · Verify every claim against reality

A doc is a claim about the code, and claims can be wrong. Go through every agent-facing doc line by line and check each concrete, checkable statement against the actual codebase or running product: a named UI element (tab, button, menu, panel) — does it exist, under that name, where the doc says it lives? A named config file or setting — does it exist at that path, with that key? A described feature or flag — does the code path it claims still exist, or was it removed/renamed since the doc was written? Pay special attention to claims about HOW a feature is reached — a doc that says a setting lives in a visible Settings UI when it’s actually only reachable via an undocumented CLI flag or a raw config edit is a claim that will send an agent hunting for a button that was never there. Also check for direct self-contradiction within one document (a feature described as paid-tier-only in one sentence and available to free accounts one sentence later). List every stale, wrong, or nonexistent claim you find, with the doc location and what’s actually true. When every concrete claim in the agent-facing docs has been checked against the code, run quest_level complete.

Level 3 · Read it as the agent that has to act on it

Skimming for typos is not the same job as acting on instructions. This is the level that actually catches what levels 1 and 2 miss: re-read every agent-facing doc from the top, but instead of proofreading, simulate being a fresh agent with no prior context that has just been told “follow this doc” and has to take real actions from it. For each instruction, sentence, or claim, ask: if I trusted this literally and acted on it right now, what would I do, and would it work? Look for the specific traps a human skims past but an agent walks straight into: an instruction that assumes undefined jargon the agent has no way to resolve (a term like “surface” or “shard” used before or without ever being defined anywhere the agent can reach); a claim that would make an agent try to use a feature, button, or file that doesn’t exist and then either hallucinate a substitute or burn a turn searching for it; two docs giving contradictory instructions for the same situation with no signal about which one wins; and an instruction that is technically true but leads to the wrong conclusion when read out of its original context (true when written, false now, still sitting there as if current). For every trap found, write down the exact sentence, the wrong action an agent would plausibly take, and why. This level is not done when you’ve reviewed the docs once — it’s done when you can point to at least one concrete “an agent would do X, and X is wrong” finding, or you have positively confirmed there isn’t one. When you’ve completed that pass and written down what an agent would actually do wrong, run quest_level complete.

Level 4 · Fix the worst offenders

Fix what would actually mislead an action, not what merely reads awkwardly. Take the findings from levels 1-3 and rank them by how badly they’d steer an agent wrong — a false claim about a feature that doesn’t exist and an undefined term that gates a decision outrank a naming inconsistency that’s merely ugly. Fix the doc text directly: correct wrong claims, replace ambiguous or overloaded terms with distinct names (or add an explicit “not to be confused with” note where renaming everywhere isn’t practical), define jargon on first use, and resolve any direct self-contradictions in favor of whichever statement matches the actual current behavior. Don’t just delete the wrong sentence — replace it with what’s actually true, since a gap reads to an agent as “unspecified” and a wrong-but-present claim reads as “ground truth.” When the worst offenders are fixed and the docs say what the system actually does, run quest_level complete.