flow-brief
Produce a single-file HTML swimlane brief that walks a system, module, or upcoming feature past a non-specialist reader, with provenance badges that separate what is measured from what is merely intended. Use this whenever someone needs to explain how something works to people outside the team — a flow diagram, an architecture walkthrough, an onboarding page, a design-review handout, a 介绍图 or 泳道图 — and especially when they describe the need without naming a format: "explain this to my boss", "draw how the data moves", "something the new hire can read", "I have to present this next week".
shaokeyibb · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add shaokeyibb/flow-brief --skill flow-briefAbout this skill
name: flow-brief description: 'Produce a single-file HTML swimlane brief that walks a system, module, or upcoming feature past a non-specialist reader, with provenance badges that separate what is measured from what is merely intended. Use this whenever someone needs to explain how something works to people outside the team — a flow diagram, an architecture walkthrough, an onboarding page, a design-review handout, a 介绍图 or 泳道图 — and especially when they describe the need without naming a format: "explain this to my boss", "draw how the data moves", "something the new hire can read", "I have to present this next week".'
Flow Brief
Produce one self-contained .html file: a swimlane walkthrough that explains a system,
a module, or an upcoming feature to someone who does not work inside it. No build step,
no assets beyond one Google Fonts link, opens by double-click.
Match every reader-facing string to the language of the user's request (a Chinese request gets a Chinese page). Keep identifiers, file paths, commands, and error codes verbatim.
The reader is not your peer. A flow brief a fellow engineer enjoys is usually one a director abandons after three lines. Everything below exists to prevent that.
Fast path
- Frame it. From the one-line request pin three things: the subject boundary, the reader (default: competent, but does not work in this module), and the spine (where the flow enters, where it exits). Pick a row from the Scenario router.
- Count the modes — see Rule 1. Most subjects have one; decide before drafting.
- Collect by walking the call chain, not by reading docs. Code first, documents last:
documents lag behind implementations, and the gap between them is often the most
interesting thing you will put on the page. Details in
references/collecting.md. - Draft the artifact before polishing anything. Copy
templates/skeleton.htmland fill bands. Do not redesign the layout. The template owns geometry, color, theming, and responsiveness — that is what makes output stable across models and agents. - Self-check:
python <skill>/scripts/check_flow_brief.py <out.html>, then fix in the order the diagnostics list.
Do not read references/components.md before you have a draft — consult it when you need
a component you have not used yet. Do not invent CSS classes: every visual affordance you
need already exists in the template.
Scenario router
| Scenario | How to find the spine | How to apply the evidence ladder |
|---|---|---|
| Shipped system or module | Walk the call chain from the entry point | Mostly measured + code facts; illustrative only for sample payloads |
| Upcoming feature (no code yet) | Walk the existing upstream and downstream, then splice the design in between | Existing parts are measured/code facts; new parts are to build. The page then shows at a glance what already exists versus what must be built — exactly what a reviewer wants to know |
| Mixed (adding to a live system) | Spine follows the live path; new steps splice in | Both, visually separated. The gap color is reserved for unbuilt things |
For the upcoming-feature scenario the collection order reverses: read the design document first, then find the existing upstream/downstream in code, then mark the seam between them.
The five rules
Each rule exists because of a specific failure. Keep the failure in mind — it is how you tell whether you actually applied the rule.
Rule 1 · Separate the modes
Ask how many ways this flow can run. Most flows have exactly one. When that is the case, say so in a sentence and draw one mode — do not invent a second one to make the page look richer.
When there really is more than one, look for the split along one of these axes:
| Split axis | Typical shape |
|---|---|
| First time vs afterwards | cold start vs cache hit; index build vs query |
| Full vs incremental | bulk import vs delta sync |
| Build vs consume | index build vs query; compile vs run |
| Normal vs degraded | happy path vs fallback, retry, circuit-breaker |
| Sync vs async | answered inline vs queued for later |
| By actor | what an admin traverses vs what an end user does |
The test: if the two ways do different things at the same step, they are separate
modes and each gets its own swimlane section. If one merely skips steps the other
takes, it is not a mode — it is a branch, and it belongs inline as a .band alt.
Failure it prevents: merging two genuinely different runs into one linear flow. The reader can then never tell which steps happen every time and which happen only once — and that distinction usually drives every question they ask next.
Rule 2 · Node triad
Every step band ends with a .dflow strip answering exactly three questions:
what upstream handed me / what I produced this round / who picks it up.
All three, every band. "See above" is not an answer.
Failure it prevents: the most common swimlane failure — boxes and arrows everywhere, but no way to see how the data actually changes shape.
Rule 3 · Evidence ladder
Every factual claim on the page carries a provenance badge. Four rungs:
| Rung | Badge | Required backing |
|---|---|---|
| Measured | real pill | A run identifier, test case, or artifact path |
| Code fact | inline code | A file:line |
| Illustrative | plan pill | Shape is right, values invented — must be labeled |
| To build | gap pill | Not implemented yet — must be labeled |
Failure it prevents: the single most damaging failure in a brief written for leadership — drawing an intention as if it were the current state.
The point of forced labeling is not that the reader will verify you. It is that you cannot fool yourself: every cell demands a rung, and being unable to pick one is the signal that you have not collected enough. Go back to step 3.
Rule 4 · Three reading depths
On
Read the complete source ↗