document-what-shipped

Files (7)

• SKILL.md
• destinations.md · references/
• page-spines.md · references/
• register.md · references/
• anchored_edit.py · scripts/
• check_links.py · scripts/
• check_mermaid.py · scripts/

SKILL.md (first lines)

# Document what shipped

A decided design is not a shipped one. That sentence is the whole skill, and it is in the name
because it is the thing a session forgets at exactly the wrong moment - when a decision record,
a plan or an ADR describes the behaviour so clearly that reading the running system feels like
a formality.

It is not a formality. The draft this method replaced said the reject link *"asks for a reason
from a short list and closes the quote as lost"*. True in the decision record. Untrue in the
product: the link opened a page saying an Agent would be in touch, and closed nothing. Two more
claims in the same draft were false the same way, and one claim written by the agent doing the
measuring was false too - *"nothing notifies the Agent"*, written after reading the C# only,
while a CRM workflow had been sending that email all along, 16 seconds after the press.

So the deliverable is not a document. It is **one page whose every sentence a person can check**,
plus the record that says how each sentence was checked.

```
  ONE RUN = ONE PAGE
  ─────────────────────────────────────────────────────────────
  ⓪ FOUR ANSWERS      type · reader · system+environment · destination
  │                   any one missing → ask, do not assume
  ▼
  ① SHOT LIST         numbered pictures the page needs
  │                   gate opens ONLY on files, or a plain "no images"
  ▼
  ② FACT LEDGER       every fact × three places · live journey first
  │                   no place answers it → it is NOT BUILT, not a sentence
  ▼
  ③ DRAFT             one page, one spine, holes visible
  ▼
  ④ SNAPSHOT          live page + version token, before any write
  ▼
  ⑤ HAND OVER         and STOP. Only the owner says publish
  ▼
  ⑥ PUBLISH           If-Match / fast-forward · read back · probe
  ▼
  ⑦ PROVE IT          resolve EVERY link · publish record · one ticket comment
```

---

## ⓪ Four answers before anything is read

Ask all four at the start, in one message, and wait. Each one changes what gets measured, so
guessing any of them means measuring twice - and the second pass happens after a draft exists,
which is when measurement gets skipped.

| answer needed | how to ask it | if it is missing |
|---|---|---|
| **Which type of page?** | offer the five spines by the reader's question, plus *other* | ask. Never infer from the request wording |
| **Who reads it?** | propose from the type and destination: *"Reader: management, on the GlassHull wiki. Correct?"* | ask |
| **Which system, which environment?** | name the product and the environment you will measure | **stop.** See ① below |
| **Where does it get published?** | name the destination and the parent page | ask |

Read `references/page-spines.md` for the five spines and their sections, and
`references/register.md` once the reader is named.

**An unnamed environment stops the run.** Not a caveat banner - a stop, with a question. In this
repo the trunk carries 390 of the tree's frontend and api files while the delivery ref that was
actually deployed carries 753, so "the code" is not one thing and a page written from the wrong
one describes a product that does not exist. A manual whose subject cannot be identified cannot be
re-checked by anybody, including you next month.

**The type may be one the five spines do not cover.** Then take *other*: ask for the reader's
question, propose a spine from it, and at the end of the run **write that spine into
`references/page-spines.md`** marked unproven. A type answered once should never be improvised
twice.

---

## ① The shot list, before the draft exists

Hand over a numbered list of the pictures the page intends to show - one row per step, saying what
each picture must contain. "Do you have screenshots?" is not answerable; this is.

```
  1. the Send dialog, showing the voyage list and the Send button
  2. the email as the customer receives it, showing one button per voyage
  3. the confirm page, showing the vessel and the departure date
```

**The gate opens only on an explicit answer.** Files handed over, or a plain *"no images"* /
*"the diagram is enough"*. Silence, "later", "maybe", and simply moving on to another instruction
all leave it closed - ask once more. An absent answer is not a decline.

**Once the files are handed over, read them through `read-picture`.** Load the `read-picture`
skill via your harness's mechanism, asking kind `on-screen-text` for the words this page will
quote - button labels, page titles, status names. It answers from the project's picture record
when that picture has already been read for the same question, and opens the image when it has
not. Carry its not-re-checked flag into ② - a row whose bytes could not be confirmed is not
evidence for a sentence on a published page.

**A diagram may replace a picture, and it does not replace what the picture proved.** A screenshot
is evidence the thing exists and carries the exact words on the button; a diagram shows order,
branch and state, and proves nothing about what shipped. So when a step is covered by a diagram
instead:

- quote its on-screen names - button labels, page titles, status words - from the **measurement**,
  never from memory, because the picture that would have caught a wrong label is not there;
- make sure the diagram actually carries **that step**, not merely sits near it.

**A step with neither stays a visible hole in the draft**, written as a line on the page:
`> Screenshot needed: the Send dialog showing the voyage list.` Recording the gap in a side file
is what happened before, and no reader of a wiki opens the side file - a thin section reads as a
complete one.

---

## ② The fact ledger - every fact, three places

For each fact the page will state, read all three places that can answer it:

| place | what it answers | how it lies |
|---|---|---|
| **authored code** | what we wrote | it is silent about everything the platform does for us |
| **the platform's own automation** | workflows, plug-ins, triggers, jobs, rules, integrations | a sweep of one storage column misses a whole family - reading only classic definitions missed 129 cloud flows whose definition lives elsewhere |
| **a live observation** | *does this ship* | it is a sample. One run does not prove the second branch |

From ThodsaphonSonthiphin/workflow-daily-work, MIT.

More from ThodsaphonSonthiphin/workflow-daily-work