From a53fb9917aae962e2b202ca81e1a85c41ad72a28 Mon Sep 17 00:00:00 2001 From: Joseph Dale Banares Date: Sat, 24 Oct 2026 23:20:44 +0800 Subject: [PATCH] docs(skill): fill the gaps an end-to-end run hit: edge evidence, remotes, node types, evidence check --- skill/SKILL.md | 10 +++++++--- skill/references/authoring-contract.md | 11 ++++++----- 2 files changed, 13 insertions(+), 8 deletions(-) diff --git a/skill/SKILL.md b/skill/SKILL.md index 9b7e54b..1bab5ba 100644 --- a/skill/SKILL.md +++ b/skill/SKILL.md @@ -14,7 +14,7 @@ You write a typed diagram JSON. `stackmap` validates it, lays it out (you never ## The CLI -Run it as one literal command (each shell call starts fresh, so don't rely on variables set earlier): +Run it as one literal command (each shell call starts fresh, so don't rely on shell variables you set in an earlier call; `STACKMAP_BIN` below is different, because it comes from the environment): ```bash npx -y @omsimos/stackmap@0.6.1 validate --json @@ -46,8 +46,12 @@ Unless the user names a location, each diagram lives in `.stackmap//` unde - **Stop rule:** if two consecutive rounds don't reduce the number of errors, stop, keep the last file, and report the remaining diagnostics verbatim instead of guessing. - Warnings don't block delivery. Fix the cheap ones (a misspelt brand, a node you forgot to connect); mention the ones you leave. 6. **Deliver** with `deliver --open`: it writes `diagram.html` and opens it in the user's browser. A warning that no browser could be opened is not a failure (a headless or remote machine): the file is written, so give its path. Exit 1: back to step 5. Exit 2: an environment problem — report it; don't edit the diagram to "fix" it. -7. **Check evidence** (repository diagrams): every `evidence[].file` must exist, e.g. `git ls-files --error-unmatch ` from the repo root. -8. **Report** the absolute path of `diagram.html`, the receipt line, and any warnings you left. Offer `serve` for iterating. Don't claim you looked at the rendering unless you did. +7. **Check evidence** (repository diagrams): every `evidence[].file` must be tracked. From the repo root, with your diagram's path in place of ``; exit 0 means they all are: + + ```bash + node -e 'const d = require(require("path").resolve(process.argv[1])); process.stdout.write([...new Set(d.nodes.flatMap((n) => (n.evidence ?? []).map((e) => e.file)))].join("\0"))' | xargs -0 git ls-files --error-unmatch -- + ``` +8. **Report** the absolute path of `diagram.html`, the receipt line (the one line `deliver` prints on stdout: `delivered · sha256 · bytes`), and any warnings you left. Offer `serve` for iterating. Don't claim you looked at the rendering unless you did. ## Editing an existing diagram diff --git a/skill/references/authoring-contract.md b/skill/references/authoring-contract.md index ecb54a1..7667124 100644 --- a/skill/references/authoring-contract.md +++ b/skill/references/authoring-contract.md @@ -66,7 +66,8 @@ Both are drawn as **swimlanes**: `lanes` are full-width rows in the order you li - **Phases** (`phases` with `nodes`) label the columns above the lanes: *Change → Build and verify → Promote*. Each phase starts after the previous one ends, so list them in order and put each node in at most one. - **Groups** in a lane frame a few neighbouring steps (*Blocking checks*); they can't span lanes or nest. `"tone": "security"` on a group marks a policy stop. - **Cards are compact:** `title`, `subtitle`, `brand` and a short `tag` pill (*human gate*, *owner: on-call*, *15 min stable*) — no rows, stats, footer or CTA. Put detail in `evidence` notes. -- **Workflow nodes** use the component types (who or what does the step). **Lifecycle nodes** use the state types: +- **Workflow nodes** use the component types, for who or what does the step: `client` for a person's step (open a pull request, merge), `service` for your own automation (a CI job, a script), `external` for a third party (a package registry, a hosting provider), and `security` for a gate that can block the flow (required checks, an approval). An outcome that ends or skips the flow (*No release*, *Build skipped*) takes the type of what decided it, sits in the exception lane, and says why in its `tag`. +- **Lifecycle nodes** use the state types: | type | use for | |---|---| @@ -115,7 +116,7 @@ One scenario, told in time. `nodes` are the participants, left to right in the o ## Cards -A full card (architecture and dataflow) is a fixed 280px-wide tile; a compact card is 176px wide (title ≈ 15 characters, subtitle ≈ 17, tag ≈ 14). Only `title` is required; add sections when they carry information the reader needs at a glance. +A full card (architecture and dataflow) is a fixed 280px-wide tile; a compact card is 176px wide (title ≈ 15 characters, subtitle ≈ 17, tag ≈ 14; the diagnostic's `maxChars` is exact). Only `title` is required; add sections when they carry information the reader needs at a glance. - `title` — the name people use (`orders-api`, `Orders`). `subtitle` — what it is (`PostgreSQL cluster`, `Payments API`). - `rows` (≤ 6) — key/value facts: size, port, runtime, schedule. `mono: true` for ports, IPs, paths. One row per label: two rows under the same label (a warning) usually means one fact split in two — merge the values (`file: hard · 16k: standard`). @@ -131,10 +132,10 @@ When the diagram must explain a real codebase, the source is the authority for r 1. **Map the slice.** Use manifests, entry points, route registrations, deployment/infra config (Dockerfiles, compose, Terraform, k8s, serverless configs) to find the runtime units. Read the entry, config and modules relevant to the request; follow imports and call sites until each responsibility reaches its real input, output or side effect. Read a connected slice, not the whole repo. 2. **Trace ownership.** Draw an edge only where you saw the call, publish, read or write at a call site (or the config that wires it). A package that is installed but never called on the normal path is not an edge. Distinguish the service that requests work from the worker that executes it and the store that receives the bytes. -3. **Record evidence while reading.** Put `evidence: [{ "file": "src/orders/db.ts", "line": 42, "note": "writes orders" }]` on nodes, with paths relative to the repo root (or the project root if it isn't a git repo). Notes are shared with the diagram: never quote secrets or internal hostnames in them. +3. **Record evidence while reading.** Put `evidence: [{ "file": "src/orders/db.ts", "line": 42, "note": "writes orders" }]` on nodes, with paths relative to the repo root (or the project root if it isn't a git repo). Notes are shared with the diagram: never quote secrets or internal hostnames in them. Edges have no `evidence`: cite the line that makes an edge on the node that calls, publishes or writes, with a `note` naming the target (`publishes to npm`), or in the diagram's `notes` when no single node owns it. **Links (`source.url`)** — set it only when all of these hold, otherwise omit `source` (evidence still shows as `file:line`): - - the remote is on **GitHub or GitLab** (`git remote get-url origin`). Convert `git@github.com:owner/repo.git` to `https://github.com/owner/repo`; drop any `user:token@` part. - - the commit is **on the remote**: `git branch -r --contains HEAD` prints something. Otherwise use the newest pushed commit (`git merge-base HEAD origin/HEAD`) — but then only cite files unchanged since it. + - the remote is on **GitHub or GitLab** (`git remote get-url origin`). Convert `git@github.com:owner/repo.git` or `https://github.com/owner/repo.git` to `https://github.com/owner/repo`; drop any `user:token@` part. + - the commit is **on the remote**: `git branch -r --contains HEAD` prints something. Otherwise use the newest pushed commit, `git merge-base HEAD origin/HEAD` (without an `origin/HEAD`, use the default branch, such as `origin/main`), and cite only files unchanged since it: `git diff --quiet -- ` exits 0. - use the commit sha, not a branch: `https://github.com///blob/` (GitLab: `https://gitlab.com///-/blob/`). - for a file with uncommitted changes (`git status --short`), leave out `line` — its numbers won't match the linked commit. 4. **Name uncertainty.** If you couldn't confirm something (durability, who reads a table), say so in the evidence note or your report rather than drawing it as fact.