majiayu000 How
Contract
| Field | Bound contract |
|---|---|
| Trigger | User asks to explain how a code path or subsystem works |
| Authority | Read-only: no file, VCS, credential, paid, published, deployed, or remote mutation |
| Side effect | Chat output only; read-only investigation |
| Done | Grounded architecture walkthrough and gotchas returned |
Inputs
- Target: the specific code path, function, module, class, or subsystem the user names. Required.
- User question: the full natural-language phrasing of the how request. Required.
Procedure
- Identify the named target and confirm the scope implied by the user's phrasing. If the target is ambiguous, ask one clarifying question before proceeding.
- Locate the entry point of the target in the codebase. Use structural read operations (declaration-only summaries, line-range reads) to identify the primary file and its dependencies. Do not open every file blindly.
- Trace the control flow from the entry point: identify which functions, classes, or modules are called, in what order, and under what conditions. Map data that flows through the path.
- Identify architectural seams: where the code delegates to an external library, makes a system call, crosses a process or network boundary, or performs I/O.
- For each major step, note the behavior that a caller or newcomer would find surprising: implicit assumptions, edge conditions handled silently, global state relied upon, error paths that behave differently from happy paths, and performance characteristics that are not obvious from signatures alone.
- Turn the findings into a grounded walkthrough of the architecture as it exists, not as intended or documented. Cite concrete files and line ranges for key decisions.
- Return a structured chat report containing the walkthrough and gotchas.
Failure and recovery
- Target not found: the named path, symbol, or module does not exist in the codebase. Return
no-evidenceand state exactly which target was not found. Do not guess or infer the target's location. - Ambiguous target: the name matches multiple distinct locations. Ask the user to specify which one they mean. Do not proceed on multiple targets simultaneously.
- Insufficient evidence: the target exists but its implementation is behind an opaque boundary (binary blob, generated code without source, external service). State that the evidence is unavailable and end with
inconclusive.
Output
A grounded architecture walkthrough describing:
- The entry point and control flow
- Data that moves through the path
- Architectural seams and their consequences
- Gotchas: surprising behaviors, silent edge cases, and non-obvious assumptions
Output ends with done or one of the named failure states: no-evidence, inconclusive.