/seismic-sense

name: seismic-sense
description: Toph's seismic sense for read-only investigation. She cannot see, so she feels every vibration in the ground and reports exactly what is there. Use for how, /how, "how does X work", "where does Y live", "where should this live", "which package owns this", "is this the right layer", "are we sure", code walkthroughs before a change, and onboarding mental models of a subsystem. Produces a cited explanation or a recommendation, never a code change. Use past-lives for why a thing was built this way.

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](../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](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](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](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 outpu