---
name: how
description:
  "Explain how a current code path, subsystem, feature, package boundary, state transition, or
  runtime architecture works from live repository evidence. Use for mechanics walkthroughs,
  ownership and layering questions, pre-change understanding, and 'where should this live'. Produce
  a bounded source map plus execution, data, and control flow, gotchas, and change surface. Stay
  read-only; use why for historical rationale or original design intent."
argument-hint: "<target / question>"
disable-model-invocation: true
---

# How

Build a working mental model from current code. Explain mechanics, not history, and remain
read-only.

## Route the question

- Use `how` for what executes now, where state lives, who owns each boundary, and what a change
  would touch.
- Use `why` for intent, historical tradeoffs, regressions, and commit or PR rationale.
- Use `standup` for broad current-state orientation.
- Use `production-support` when live behavior matters.

For a mixed question, establish the minimum mechanics needed to identify the decision point, then
route rationale to `why`. Label architecture recommendations as inference from current ownership.

## 1. Establish the target

State the exact symbol, route, user action, package, process, or boundary being traced. Resolve
discoverable ambiguity from the repository first. If several plausible targets produce materially
different flows, use the harness's structured question tool after one bounded search.

Do not expand a narrow mechanics question into a repository inventory.

## 2. Build a bounded source map

Search before reading broadly, and read the smallest set that can close the flow: the entry point,
its contract and central types, the handler, the state owner, any runtime adapter, and a decisive
test or fixture.

For cross-package flows, trace boundaries independently but do not create subagents merely because
several packages are involved. Each boundary needs its entry contract, exit contract, state owner,
and decisive source paths.

Read Scratchpad only when its active index points to a contract or WIP state needed to locate the
flow; verify mechanics against code, tests, generated artifacts, or runtime evidence. Use `cass`
only for explicitly requested session-only or uncommitted mechanics that the working tree cannot
recover.

## 3. Trace the flow

Trace only the dimensions needed by the question:

- **Execution:** trigger → dispatch → internal services → runtime boundary → terminal effect and
  caller-visible failure.
- **Data:** input and validation → authoritative representation → ownership transitions → persisted,
  serialized, or rendered output.
- **Control:** auth, flags, configuration, branches, retries, cancellation, transactions, caching,
  concurrency, background work, and error handling.

Verify registrations, calls, dependency wiring, and runtime composition. Imports and filenames alone
do not prove execution. Separate possible paths from the path proven active in the target
environment, and name every important type or ownership change.

## 4. Separate evidence from inference

Classify material claims:

- **Observed:** direct source, wiring, test, generated config, or runtime evidence.
- **Inferred:** the simplest explanation consistent with observed edges.
- **Unknown:** an unresolved edge or unavailable runtime condition.

Cite observed claims to exact files and useful line anchors. Tests establish expected behavior, not
current production state.

## 5. Identify gotchas and change surface

Call out only mechanics that can change outcomes: lazy initialization, environment-specific wiring,
generated code, stale caches, hidden writes, background completion, transaction boundaries,
fallbacks, or suppressed errors.

Group future change impact as:

- **Must change:** contracts and implementations directly on the traced path.
- **Likely changes:** callers, tests, generated artifacts, migrations, configuration, or docs
  coupled to it.
- **Conditional:** files needed only for a named behavior or environment.

State exact completion checks without implementing the change.

## Answer shape

Return the smallest useful subset:

1. **Mental model** — subsystem and owner in one compact explanation.
2. **Flow** — numbered execution with data/control transitions and file evidence.
3. **Source map** — only files actually used, with their roles.
4. **Gotchas** — non-obvious mechanics only.
5. **Change surface** — must/likely/conditional files and completion checks.
6. **Evidence gaps** — inferences and unknowns, or none.

Use a small diagram only when branching or three or more boundaries are materially clearer visually.

Stop when further reading would add detail without changing the mental model.