---
name: how-it-works
description: A cited, read-only explanation of how a mechanism in a codebase works. Use when the user asks "how does X work in this code", "where is Y computed", "walk me through Z", or wants a reference implementation read to compare with their own, in a large or unfamiliar codebase. Not for a file or function already known (just read it), bug hunting or debugging, reviewing a diff, or changing code.
license: MIT
---

# How it works

> **Invoke:** `/how-it-works <codebase path> <question>`. Two stages run in sequence, normally as background agents - a
> map, then a dig - each followed by a gate the session runs itself. Both stages are read-only on the code; each
> writes only its own scratch file.

**Contract.** The skill produces one answer to a question about how existing code works: the mechanism in plain words,
with formulas, constants, order of operations and edge cases, each cited by file:line. It does not fix, refactor, review
or judge the code, and it does not run it. It ends when the checked answer is relayed. If the dig turns up a bug or a
change worth making, report it to the user as a separate finding, outside the answer, for a debugging or change
workflow to pick up; the pull to fix it is the signal to stop.

Finding the right code and reading it closely are different jobs. Deciding which few places in an unfamiliar
codebase answer the question, and ranking them, takes judgment, and a wrong map is likely the most expensive failure: it
sends the whole dig to the wrong place. So a strong model maps, in a short stage. Reading the mapped sections closely is
long but bounded work, which a cheaper model can do well inside the fence the map sets, keeping the strong model's time
short.

## Models

- **Map:** a strong model.
- **Dig:** a cheaper model.
- **Only one model available:** use it for both, still as two separate stages with a gate between them. The split
  bounds the dig's scope whatever the model.
- **No subagents:** run both stages yourself in sequence, writing `map.md` before reading any section closely.

## Output location

Both stages write to one scratch folder outside the project, such as the session's temporary or scratch directory,
named for the question (`<scratch>/how-it-works-<topic>/`). Never write into the codebase being probed or into the user's
project tree. Keep `map.md` there: a later question on the same codebase starts from it rather than mapping again.

## Running it

1. **Frame the question.** Split it into at most five sub-questions, each a mechanism plus the facts wanted (formula,
   constants, order of operations, edge cases). If the answer will be compared with another codebase, note the
   matching places there by file:line. Ask the user only what the request leaves open and only they know: which
   codebase or version, what the answer is for, what to compare against. One round, at most three questions, each
   with a suggested answer; if the request already says, ask nothing. No reply: proceed on the suggested answers
   and list each under open questions as an assumption.
2. **State the cost**, then start: the map takes about 10-15 minutes, the dig about 20-30. Give the expected finish
   time.
3. **Stage 1: map.** Brief the strong model with the map template below. It writes `map.md` in the map shape, or
   returns its content for you to save there if it cannot write files.
4. **Gate 1: confirm the map.** For each sub-question, open the top-ranked entry (and the second, if the first is
   thin) and check it holds what the map says. Tick each one in `map.md`'s gate line.
   - **No dig until every sub-question's top entry is confirmed against the code.**
   - An entry that fails: re-map that sub-question once with a narrower brief naming what was wrong. If the second map
     also fails, move the sub-question to open questions and say so in the relay.
5. **Stage 2: dig.** Brief the cheaper model with the dig template, `map.md`, and the confirmed sub-questions. It writes
   `dig.md` in the dig shape, or returns its content for you to save there.
6. **Gate 2: check the dig.** Open every citation a conclusion rests on, plus a spot check of two others. Mark each
   claim `read` (the line says it), `inferred` (follows from lines read but is not stated), or `wrong`.
   - **Nothing marked `wrong` or left unchecked is relayed as a finding.** Correct it from the source, or move it to
     open questions.
   - A dig that cites files the map never named, with no "Left the map" entry, goes back to the mapped sections.
7. **Relay** a short answer per sub-question, what was inferred rather than read, the open questions, and the path to
   `dig.md`.

### Skipping a gate

The thoughts that come before skipping one, and the answer to each:

- *"The map looks plausible."* A plausible wrong map can send the dig into the wrong file for half an hour.
  Opening one entry per sub-question takes a minute.
- *"The dig will notice if the map is wrong."* It is briefed to read what it is pointed at, and may explain the
  wrong code confidently.
- *"The citations came from a careful model."* Line numbers can drift and models may paraphrase; a citation is
  checked or it is not evidence.

Caught past a gate without running it: stop, run it, and redo whatever came after if the gate fails.

## Output shapes

Keep these structures; fill every slot, writing "none" where a slot is empty.

`map.md`:

```
# Map: <question>
Codebase: <path> @ <commit or version, if known>. Mapped by: <model tier>.

## 1. <sub-question>
Wanted: <formula | constants | order | edge cases>
| rank | file:line-line | symbol | why it matters |
|------|---------------|--------|----------------|
| 1    | ...           | ...    | ...            |
Call path: <a.Func> -> <b.Func> -> <c.Func>
Gate 1: [ ] top entry confirmed by the session

## Seen but not ranked
- <file:line> - <what it is>
## Guesses
- <claim> - <why it is a guess>
```

`dig.md`:

```
# Dig: <question>
Read from: map.md (confirmed entries). Dug by: <model tier>.

## 1. <sub-question>
Mechanism: <plain words, two to five sentences>
Formula: <expression, with each term named>
Constants:
| name | value | set at file:line |
Order: <step -> step -> step, each with file:line>
Edge cases: <case - behaviour - file:line>
Evidence (one line per load-bearing claim):
- [read | inferred] <claim> - <file:line> "<short quoted excerpt>"
Left the map: <file:line - why it was followed>, or none
Gate 2: [ ] every load-bearing citation opened by the session

## Comparison (only if asked)
| sub-question | this codebase file:line | other codebase file:line | what differs |

## Open questions
- <what could not be settled, and what would settle it>
## Map corrections
- <what the map got wrong>, or none
```

## Brief templates

Map:

```
You are mapping a codebase for a follow-up reader. Find where these mechanisms live; do not explain them beyond what
locating them needs.

Codebase: <path>. Language: <...>. No builds, no runs. Write only <scratch>/map.md and change nothing
else, in the codebase or anywhere. If you cannot write files, put map.md's full content in your final reply,
above the summary asked for below. About <N> minutes.
<Constraints, e.g. names that must not be written anywhere.> Prior map, if any: <path>.

Sub-questions:
1. <mechanism>: wanted <formula | constants | order | edge cases>.

Write <scratch>/map.md in exactly this shape: <paste the map shape>. Rank by how directly each entry answers the
sub-question. Mark guesses as guesses. Final reply: the top entry per sub-question, one line each.
```

Dig:

```
You are reading the sections in <scratch>/map.md closely, to answer the sub-questions below with evidence.

Codebase: <path>. No builds, no runs. Write only <scratch>/dig.md and change nothing else, in the codebase
or anywhere. If you cannot write files, put dig.md's full content in your final reply, above the summary asked
for below. About <N> minutes.
<Constraints.>

Read the mapped sections first. You may follow calls out of them; record each under "Left the map" with the reason.
Answer from the code only, not from how such code usually works. Cite file:line for every claim, with a short quoted
excerpt where the exact line matters, and mark each claim read or inferred. <If comparing: set each answer beside
<other file:line> in the comparison table and name what differs - compare formulas and units, not names.>

Write <scratch>/dig.md in exactly this shape: <paste the dig shape>. Final reply: the answer to each sub-question in
two or three lines, and anything the map got wrong.
```

## Pitfalls

- **Mapping and answering in one stage.** Symptom: `map.md` explains the first sub-question at length and leaves the
  rest thin. Instead, hold the mapper to the table and the call path; re-brief it if it drifts.
- **Comparison by name.** Two codebases can use one word for different things ("cost", "energy", "weight"). Compare
  formulas and units.