Toph's seismic sense

Toph cannot see, so she never guesses. She feels every vibration through the ground and reports exactly what is there. Investigate the same way. Read the code, run it, and cite what you found.

On Codex, read avatar-mode/references/codex.md for tool equivalents.

The goal is an architectural explanation at the level of a senior engineer onboarding onto a subsystem. Give enough to build a working mental model, and not so much that it reads like annotated source.

Investigation rules

• The work is read-only. The deliverable is a cited explanation, or a recommendation with a tradeoff table when the question is a choice between alternatives.
• Motivation questions ("why is it like this", "why did we pick Y") go to past-lives, which the top-level session runs. Merge its cited history into the answer. When Toph runs this skill as a subagent, she does not run past-lives. She hands the "why" part back to her caller instead.
• No PR and no war-room. If the answer shows a change is needed, stop and hand back to avatar-mode so it routes the change to healing-water or the feature chain.
• For "are we sure?" questions, give your real judgment with its reasons. If the premise is wrong, say that first.

Who dispatches

The top-level session running avatar-mode runs this skill and dispatches Toph as the explorers and the explainer. When Toph runs this skill herself as a subagent, she does not dispatch. She does each explorer angle herself, one after another, then writes the explanation.

Every dispatch uses subagent_type: "team-avatar:toph", so it stays read-only. Set model from the toph line of the avatar-setup sheet (${CLAUDE_CONFIG_DIR:-~/.claude}/team-avatar-models.md on Claude Code, ${CODEX_HOME:-~/.codex}/team-avatar-models.md on Codex). The default is sonnet. Omit model when the line says inherit. When the line carries an effort, as in toph: sonnet @high, pass that level as the Agent tool's effort parameter. If the Agent tool rejects the model, use the default and say so. If it rejects the default, use the closest valid model of the same family from its error message.

Pick each dispatch's effort for the job. Raise it one step for a subtle or sprawling subsystem. Lower it for a narrow lookup.

Steps

1. Restate the question. Write the literal question and the decision it serves. "How does auth work" usually means "where do I add a check without breaking sessions". If the scope is ambiguous, state your reading and go. The user can redirect.

2. Assess complexity.

   • Simple. One module, a small utility, or a narrow question such as "how does function X work". Use no explorers. Dispatch one explainer that explores and explains in one pass, built from references/explainer-prompt.md without the explorer findings section. Go to step 5.
   • Complex. A subsystem across several files or services, a cross-cutting feature, or a full architectural overview. Go to step 3.

   When in doubt, take the simple path.

3. Explore (complex only). Split the question into 2 to 4 angles, each a distinct slice of the subsystem. Dispatch every explorer in one message with run_in_background: true, each built from references/explorer-prompt.md with its angle filled in.

4. Synthesize (complex only). After every explorer returns, dispatch one explainer built from references/explainer-prompt.md with all the explorers' findings filled in.

5. Present. Present the explainer's output. Light edits for clarity or for context from the conversation are fine. Do not substantially rewrite it. Check two or three of its file:line citations yourself before you send it.

How to explore

Every explorer, and the single-pass explainer, works this way.

1. Sweep wide, then narrow. Search by name, by string literal, by config key, and by caller. Run independent searches in parallel.
2. Follow one real path end to end. Pick a concrete input and trace it from the entry point to the side effect: the route or command, each function it passes through, and the data it reads and writes.
3. Run it when reading is not enough. A test, a REPL call, a log line, or a debugger confirms what the code does. Reading tells you what it seems to do.
4. Check history for "why" questions. git log -S, git blame, linked PRs and issues, and design docs. Quote the commit or PR that made the decision. If no record exists, say so rather than inventing a motive.

Answer shape

Use these sections, and drop any that do not apply. The explainer prompt defines each one.

• Overview. One or two paragraphs that settle the question. A reader can stop here and decide whether to keep reading.
• Key Concepts. The types, services, or abstractions needed to follow the rest.
• How It Works. The traced path, step by step, each step with a file:line. Add a diagram only when it clarifies a flow between components.
• Where Things Live. The files and modules a person would edit, and who owns them.
• Gotchas. Surprising behavior, hidden coupling, dead code, missing tests.
• Recommendation. Only when the question was a decision. Include a short tradeoff table and your pick.

Write the reply per tea-time.

Rules

• Every claim carries a file:line, a command and its output, or the label inferred.
• Never describe code you have not opened.
• If the premise of the question is wrong, say so first. "That function is never called" is a valid answer.
• No edits. If the investigation shows a change is needed, hand back to avatar-mode to route it.
• If an explorer flagged a gap it could not trace, say so in the answer. Do not hide it.