Explain Flow
Produce a code-grounded, phase-by-phase walkthrough of how a sequential component actually
executes — not a paraphrase of file names, a trace of real control flow with citations.
Quick start
- Find the entry point (main class/function, script, cron handler, message consumer).
- Read it — and everything it directly calls — in full before writing a single line.
Never write from a partial read; for large files read in chunks until you've covered
the whole thing.
- Split the logic into phases using the taxonomy below, in true execution order.
- Write the walkthrough with the template below.
- Save it under the project's
docs/ folder (create the folder if missing) and print
the full walkthrough as your chat response — saving the file is not a substitute for
showing the content. Don't make the user open the file to read it.
Phase taxonomy
| Phase |
Covers |
Ask yourself |
| 0. Entry / Init |
What runs before real work starts: config load, connection setup, arg parsing |
What has to be true/loaded before step 1 can run? |
| 1. Input Acquisition |
Where source data enters: queries, file listing, queue read, API pull |
Is there more than one source/condition? (tabulate if so) |
| 2. Processing |
The core per-item logic, including branches and guard conditions |
What decides whether an item is skipped, retried, or processed? |
| 3. Output / Side Effects |
What gets written, sent, or uploaded, and in what format/contract |
What downstream system consumes this, and how does it know the output is complete? |
| 4. Wrap-up |
Cleanup, notifications, status/return codes, re-triggered jobs |
What does success vs. failure look like to whatever calls this? |
For multi-file or cross-service flows, treat each hop as a sub-phase nested under the phase
it belongs to (e.g. "2a. OrderService.charge()") — see REFERENCE.md for how
to find and bound the trace.
Rules
- Read before writing. Every phase description must be backed by code you've actually
opened — cite
File.ext:line or File.ext:startLine-endLine for every method/branch you
name. Don't infer behavior from a function name alone.
- Tabulate parallel sources. If a phase pulls from more than one source/condition (e.g.
three queries feeding one list), use a table: source | method/query | condition — not prose.
- Name mechanisms, don't fabricate values. If a step depends on external config (env var,
config file, secret), name the mechanism and where it's read from; don't guess the actual
value unless you've opened the file.
- ASCII diagram only. Close with a plain-text box-and-arrow diagram summarizing phases and
major branches — no Mermaid, so it renders anywhere the doc is opened.
- Always show the content, not just the save path. Output the full walkthrough in the
chat response (same content as the saved file) — never respond with only a confirmation
that a file was written.
- Stay descriptive. This skill documents what the flow is, not what's wrong with it. Skip
bug/code-smell commentary — that's a separate review task.
- Match the conversation's language for the output document (if the user asked in
Traditional Chinese, write the doc in Traditional Chinese, etc.). If the conversation
gives no clear signal either way, default to Traditional Chinese.
- Generic when teaching, specific when documenting. When explaining this skill's own use
(e.g. to a template or another user), use a generic example domain, never real project
internals.
Output template
# {ComponentName} 完整流程 / Complete Flow
> Entry point: `{path/to/entry/file}`
## 0. {Entry / Init phase name}
...
## 1. {Input Acquisition phase name}
| Source | Method/Query | Condition |
|---|---|---|
...
## 2. {Processing phase name}
1. ...
2. ...
## 3. {Output phase name}
...
## 4. {Wrap-up phase name}
...
## Flow Diagram
\```
[ASCII box-and-arrow diagram]
\```
{1-2 sentence closing paragraph translating the technical steps into the operational/business purpose}
See EXAMPLE.md for a complete worked example on a generic domain.
1---2name: explain-flow3description: Traces the end-to-end execution flow of a sequential/procedural component (batch job, script, pipeline, cron task, workflow, or request handler — spanning one file or several files/services) and writes it up as a structured Markdown walkthrough with phase-by-phase code references and an ASCII flow diagram, saved under the project's docs/ folder. Use when the user asks to explain or document how a batch job, script, task, or pipeline works end-to-end, wants a "完整流程" / "flow walkthrough" / "walk me through this", or needs to understand execution order across an entry point.4---56# Explain Flow78Produce a code-grounded, phase-by-phase walkthrough of how a sequential component actually9executes — not a paraphrase of file names, a trace of real control flow with citations.1011## Quick start12131. Find the entry point (main class/function, script, cron handler, message consumer).142. Read it — and everything it directly calls — **in full** before writing a single line.15 Never write from a partial read; for large files read in chunks until you've covered16 the whole thing.173. Split the logic into phases using the taxonomy below, in true execution order.184. Write the walkthrough with the template below.195. Save it under the project's `docs/` folder (create the folder if missing) **and** print20 the full walkthrough as your chat response — saving the file is not a substitute for21 showing the content. Don't make the user open the file to read it.2223## Phase taxonomy2425| Phase | Covers | Ask yourself |26|---|---|---|27| 0. Entry / Init | What runs before real work starts: config load, connection setup, arg parsing | What has to be true/loaded before step 1 can run? |28| 1. Input Acquisition | Where source data enters: queries, file listing, queue read, API pull | Is there more than one source/condition? (tabulate if so) |29| 2. Processing | The core per-item logic, including branches and guard conditions | What decides whether an item is skipped, retried, or processed? |30| 3. Output / Side Effects | What gets written, sent, or uploaded, and in what format/contract | What downstream system consumes this, and how does it know the output is complete? |31| 4. Wrap-up | Cleanup, notifications, status/return codes, re-triggered jobs | What does success vs. failure look like to whatever calls this? |3233For multi-file or cross-service flows, treat each hop as a sub-phase nested under the phase34it belongs to (e.g. "2a. OrderService.charge()") — see [REFERENCE.md](REFERENCE.md) for how35to find and bound the trace.3637## Rules3839- **Read before writing.** Every phase description must be backed by code you've actually40 opened — cite `File.ext:line` or `File.ext:startLine-endLine` for every method/branch you41 name. Don't infer behavior from a function name alone.42- **Tabulate parallel sources.** If a phase pulls from more than one source/condition (e.g.43 three queries feeding one list), use a table: source | method/query | condition — not prose.44- **Name mechanisms, don't fabricate values.** If a step depends on external config (env var,45 config file, secret), name the mechanism and where it's read from; don't guess the actual46 value unless you've opened the file.47- **ASCII diagram only.** Close with a plain-text box-and-arrow diagram summarizing phases and48 major branches — no Mermaid, so it renders anywhere the doc is opened.49- **Always show the content, not just the save path.** Output the full walkthrough in the50 chat response (same content as the saved file) — never respond with only a confirmation51 that a file was written.52- **Stay descriptive.** This skill documents what the flow *is*, not what's wrong with it. Skip53 bug/code-smell commentary — that's a separate review task.54- **Match the conversation's language** for the output document (if the user asked in55 Traditional Chinese, write the doc in Traditional Chinese, etc.). If the conversation56 gives no clear signal either way, **default to Traditional Chinese**.57- **Generic when teaching, specific when documenting.** When explaining this skill's own use58 (e.g. to a template or another user), use a generic example domain, never real project59 internals.6061## Output template6263```md64# {ComponentName} 完整流程 / Complete Flow6566> Entry point: `{path/to/entry/file}`6768## 0. {Entry / Init phase name}69...7071## 1. {Input Acquisition phase name}72| Source | Method/Query | Condition |73|---|---|---|74...7576## 2. {Processing phase name}771. ...782. ...7980## 3. {Output phase name}81...8283## 4. {Wrap-up phase name}84...8586## Flow Diagram87\```88[ASCII box-and-arrow diagram]89\```9091{1-2 sentence closing paragraph translating the technical steps into the operational/business purpose}92```9394See [EXAMPLE.md](EXAMPLE.md) for a complete worked example on a generic domain.
hsinhan-h