diagram-flow
Draw the runtime sequence of one request or event, every arrow citing the file:line that makes the call, checked by citation-check. Use for "what happens when X runs", tracing a request or event end to end, or before changing a flow.
- License 许可
- MIT
- 最近更新
- 2026-11-04
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- diagram-flow
- metadata
- { "layer": "L3" }
- description
- Draw the runtime sequence of one request or event, every arrow citing the file:line that makes the call, checked by citation-check. Use for "what happens when X runs", tracing a request or event end to end, or before changing a flow.
03 SKILL.md 正文
Diagram flow
Trace one request or event from its entry point to its last effect and draw it as a sequence. You draw it; the code backs every arrow.
1. Pin the trigger
- One trigger per diagram: a route, a command, a message type, a scheduled job, a user action. If the request names several or none and the conversation doesn't settle it, ask which (as a multiple-choice question).
- Draw the common success path. A failure path is a second diagram.
- Map domain words to code names with
$(ven-profile path)/GLOSSARY.md.
2. Trace
- Find the entry point:
ven-profile adapter code.search --var pattern=<regex>printspath:line:text. On exit 3, use the built-in search tool and follow the no-adapter rule of the badge protocol in diagram-deps. - Read the entry point and follow each call that crosses a participant: a module, a process, a store, an external system. For each hop, write one claim row: what happens, and the
path:lineof the call. - Keep one zoom level. Participants are modules or containers, not every function. Helpers and pure functions fold into their caller.
- An async hop (a published message, a queued job, a callback) is two arrows: sender to the queue or bus, citing the send line, then queue or bus to the handler, citing where the handler is registered.
- Stop at the last effect: the response, the write, the emitted event. Past about 15 arrows, split into two diagrams at a natural seam.
- What you could not trace (dynamic dispatch, routing read from config) becomes a
Note overon the diagram, never an arrow. - Draw a return arrow only when it carries data the reader needs. It cites the line that returns or replies.
3. Draw
Number the arrows so they line up with the claim table that citation-check builds (E1 is arrow 1).
sequenceDiagram
autonumber
participant U as user
participant H as widget handler
participant S as widget store
participant Q as report queue
participant W as report worker
U->>H: create widget
H->>S: insert widget
H->>Q: enqueue report job
H-->>U: widget id
Q->>W: deliver report job
| id | claim, in words | citation |
|---|---|---|
| E1 | the route sends "create widget" to the handler | src/widgets/routes:12 |
| E2 | the handler inserts the widget | src/widgets/handler:40 |
| E3 | the handler enqueues a report job | src/widgets/handler:44 |
| E4 | the handler replies with the new id | src/widgets/handler:47 |
| E5 | the worker registers as the report job's handler | src/reports/worker:8 |
4. Check and badge
Run citation-check on the table. Fix the citation, redraw the arrow, or remove it until every row passes; then the caption is HYBRID (n/n edges cited). Save and reuse it per the badge protocol in diagram-deps, as flow-<trigger>.
Render it per Rendering in the badge protocol of diagram-deps. Under it, list what you folded away and what you could not trace, so the reader knows where the picture stops.
04 同仓库更多 Skills
yeet
Take every local change green through the repo's own checks, slice it into conventional commits, push, and with --pr open a pull request on the code host. Use only when the user explicitly asks to yeet, or to commit and push everything; never on your own initiative.
write-docs
Write or update documentation from the code: gather facts, pick the shape for the reader, write it plain, and prove every command and path in it. Use when asked to document a repo, module or feature, or to bring stale docs up to date.
why
Find why code is shaped the way it is (design rationale, trade-offs, regressions, odd thresholds) from history, tickets, docs and chat, citing every claim and stating its confidence. Use for 'why does X work this way', 'why did we pick Y', or before changing code whose purpose is unclear.
verify
Prove a change works with the check that matches its type, do the read-back, and log the pass against the exact tree. Use when a change is ready to call done, before review, commit or stopping, and whenever ven-decisions end refuses an unverified tree.
unslop
Cut AI writing tells (filler, model vocabulary, metaphor nouns, hedging, formatting tics) from text while keeping every fact. Use when editing or checking any prose before it ships: docs, PR bodies, reports, skill text.
type-discipline
Apply when designing types or data shapes, reviewing a signature, or handling outside data, in any language. Make wrong states fail early: in the compiler for typed languages, in validated runtime contracts for untyped ones.