# How

> Explains how a subsystem works: architecture, runtime flow, onboarding mental models.

Explains how a subsystem works: architecture, runtime flow, onboarding mental models. Use for how does X work or code walkthroughs. Not for motivation.

- Page: https://ss33.ai/skills/shipshitdev/how-57150549285
- Publisher: shipshitdev
- Category: [Software Development](https://ss33.ai/skills/category/software-development-t44z8z) › [Developer docs & tooling](https://ss33.ai/skills/category/software-development-t44z8z/developer-docs-and-tooling-nich6w)
- License: MIT
- Source: https://github.com/shipshitdev/skills/blob/366150f6ff4abf908164df8b94a6a49d65f46295/skills/how/SKILL.md

## Skill

SKILL.md: https://ss33.ai/api/v1/ss33/download/shipshitdev/how-57150549285

# How

Explore the codebase to answer "how does X work?" Produce an architectural
explanation at the level of a senior engineer onboarding onto a subsystem.

Explain only. For adversarial review of an architecture or a diff, route to
`interrogate` or `structural-review`.

Companion to `why`. This skill answers what the code does. `why` answers
what forces led to its shape.

## Contract

Inputs:

- A how-question: subsystem, feature flow, architectural overview, or
  runtime trace

Outputs:

- The structured explanation below

Creates/Modifies:

- None

External Side Effects:

- None. Read-only exploration.

Confirmation Required:

- None

Delegates To:

- None. May spawn read-only explorer and explainer subagents.

## Explain

### Step 1. Understand the question

Parse the ask. If ambiguous, state the best-guess interpretation and
proceed. Do not ask. Let the user redirect.

**Simple** (one module, a narrow function): skip explorer agents. The
explainer explores and explains in one pass.

**Complex** (multiple files or services, a cross-cutting feature): spawn
2-4 parallel explorers, then one explainer. When in doubt, lean simple.

### Step 2a. Explore (complex only)

Decompose into 2-4 distinct slices so explorers do not duplicate work.
Spawn all explorers in one message on the fast cheap tier, read-only.
Each explorer gets [references/explorer-prompt.md](references/explorer-prompt.md)
plus its slice. Each traces input to output without hand-waving.

### Step 2b. Direct explain (simple)

Spawn one read-only explainer on the strongest judgment tier. It explores
and writes the explanation. Use
[references/explainer-prompt.md](references/explainer-prompt.md).

### Step 3. Synthesize (complex only)

Once explorers return, spawn one explainer on the strongest judgment
tier with all findings. It reconciles overlap and contradictions.

### Step 4. Present

Present the explainer's output. Light edits for clarity are fine. Do not
substantially rewrite.

## Output format

**Overview.** 1-2 paragraphs. What it is, what it does, why it exists.

**Key Concepts.** The types, services, or abstractions needed to follow
the rest.

**How It Works.** The flow: trigger, steps, data, decision points. Prose,
not pseudocode. Cite files and functions.

**Where Things Live.** A brief map of the relevant files.

**Gotchas.** Non-obvious edges and historical scars.

## How procedure

Read [how procedure](references/how-procedure.md) when running this workflow.
Apply the authorized scope and mode of this entry point to every step.
Resolve other skills through this distribution’s active catalog; resolve
resources relative to the installed skill directory.