Raw view: Explain a file
No invisible, zero-width, or bidi-control characters detected.
---
description: Explain what a source file does, its public API, how it is used, and what to watch out for
argument-hint: <path/to/file>
allowed-tools: Read, Grep, Glob, Bash(git log *)
---
Explain the file at `$0` to an engineer who is new to this codebase.
File contents:
@$0
Recent history:
!`git log --oneline -8 -- "$0"`
Procedure:
1. Find how it is used: Grep for its exported names and for imports of its path. Read one or two representative callers.
2. Find what it depends on: imports and the key external calls (DB, HTTP, FS).
3. Write the explanation below. Use the file's own names; link claims to line numbers.
Output:
## `$0`
**Purpose:** one or two sentences, in terms of the domain, not the syntax.
**Used by:** the main callers (file paths) and in what situation.
### Public surface
| Export | Signature (short) | What it does | Line |
|---|---|---|---|
### How it works
Walk through the main path in 4-8 bullets, in execution order. Name the branches that matter and skip boilerplate.
### Dependencies and side effects
- Reads/writes: ...
- Network/DB/FS: ...
- Globals or module state: ...
### Gotchas
- Non-obvious behaviors, implicit contracts, ordering requirements, error handling quirks, TODOs, and anything the recent history suggests is fragile.
### If you need to change it
- Where the tests are (path) and what they cover.
- The one place a change here is most likely to break something else.
Keep it under 60 lines. If the file is generated or trivially small, say so in a paragraph and stop.