explaining-architecture

Files (4)

• SKILL.md
• openai.yaml · agents/
• critique-mode.md · references/
• skill-calls.md · shared/

SKILL.md (first lines)

# Explaining architecture

Answer "how does X work?" with the mental model a senior engineer needs to
start working in an unfamiliar subsystem: its architecture, flow, and sharp
edges, not annotated source code.

When the question is about motivation, rejected alternatives, or history
rather than mechanics, call the Skill tool with
`investigating-design-rationale` instead. If that skill is not installed, say
so and answer the mechanics only. Without a Skill tool, follow the
[skill call rules](shared/skill-calls.md).

The skill is read-only: it writes no files and changes no state. Describe what the code does, not what its docs claim, and report any disagreement per the [docs and code rules](shared/docs-vs-code.md).

## Input

The request names a subsystem, a feature flow, or a placement question ("where
should this validation live"). When it names none or is vague, infer the target
from conversation context and state your interpretation in one line before
exploring. Do not ask first.

## Explain

Read the implementation; never infer behavior from file or function names.
Trace each flow from trigger to effect. Where you cannot trace a link, say so
instead of inventing it. Claims about code carry `file:line`, and a flow step
names the function that runs it.

Adapt the answer to the question; use only the sections it needs:

- **Overview**: what it is, what it does, why it exists, in a paragraph or
  two.
- **Key Concepts**: the abstractions needed to follow the rest.
- **How It Works**: trigger, steps, data movement, decision points, in prose.
  Add a mermaid diagram only when the flow crosses several components.
- **Where Things Live**: the file map someone needs to start, not every file.
- **Gotchas**: surprising behavior, historical residue, sharp edges.

When something is complex, explain why. Leave out how you explored,
background the question did not raise, and restatement.

## Critique

Run only when the request asks for problems, issues, or improvements. Finish
the explanation first, then follow [critique mode](references/critique-mode.md).

From bostonaholic/skills, MIT.

More from bostonaholic/skills