Write traced docs with diagrams and tables¶

Steps¶

1. Start the item's heading with its ID. A section number before it, bold or backticks around it, and a Pandoc attribute after the title are layout, not part of the ID or the title:

   ### 1.1 REQ-RCH-01 — Registration under a supplied client ID {#req-registration}
   ### 1.2 **REQ-RCH-02** — Only a caller with the key registers
   ### 2.2 `DSN-RCH-02` — Key guard
   

   An ID later in the heading — ## Key guard (DSN-RCH-02) — declares nothing.

2. Structure the item under its heading as you like. A deeper heading — #### Acceptance criteria, #### Flow — belongs to the item, and so do its tables and diagrams. They are the item's text: after a baseline, editing them is a change like rewording the statement. Renumbering the document is not.

3. Write each field and link as a line in the item's section — right under the heading, or in a sub-section such as #### Traceability:

   #### 2.1.2 Traceability
   
   Satisfies: REQ-RCH-01
   

   A Satisfies cell in a table is not read. Nor is a line outside every item's section.

4. Name IDs freely in tables, diagrams and prose — a summary of the requirements, a flow between elements. They link nothing. An ID of this repo's kind that nothing declares, later in a heading or at the start of a table row, is reported: it was probably meant as a declaration.

5. Plan test cases the same way, where the project keeps a Test Specification. A test case is a heading with its ID and a verifies: line; the automated tests that run it name its ID, not the requirement:

   ## TC-SVC-01.1 — A call without a valid key is refused
   verifies: REQ-SVC-01
   

6. Check.

   qmstrace check --strict
   

A design document written this way¶

It reads as an architecture guide, and every element in it is declared:

---
summary: The gateway's design, written to be traced.
---

# Gateway — design

## 1. Overview

```mermaid
flowchart LR
  A[Agent] -->|register| K[Key guard] --> R[Registry]
```

## 2. Elements

### 2.1 DSN-RCH-01 — Agent registry {#dsn-registry}

Keeps one record per client ID; registering again refreshes the record.

#### 2.1.1 Flow

```mermaid
sequenceDiagram
  Agent->>Registry: register(client_id)
  Registry-->>Agent: 200, as just seen
```

#### 2.1.2 Traceability

Satisfies: REQ-RCH-01

### 2.2 `DSN-RCH-02` — Key guard

Checks the API key before any handler runs.

| Key | Status |
|---|---|
| missing | 401 |
| wrong | 401 |

- Satisfies: REQ-RCH-02

qmstrace check --strict in that repo:

read: 2 requirements, 2 design elements

result: 0 violations, 0 gaps in 4 items · 0 suspects (informational) · exit 0 · gate: gaps fail

When something is not read¶

Three slips in the same repo — the link to REQ-RCH-02 moved into the key guard's table, a planned REQ-RCH-03 added to the summary table, and a heading that ends with (DSN-RCH-03):

read: 2 requirements, 2 design elements

violations — wrong at any stage; each fails the check:
  V16  docs/design/gateway-design.md:42  DSN-RCH-03 is in this heading but not first, so it declares nothing — and nothing else declares it. Fix: to declare it, start a heading with it — `### DSN-RCH-03 — <title>`, a section number before it is fine — where a design element is read (docs/design/*.md); if the heading only names it, correct the ID. Never invent the item to make the ID resolve.
  V16  docs/req/gateway-srs.md:36  REQ-RCH-03 starts a table row, but a table declares nothing — and nothing else declares it. Fix: to declare it, write a heading `### REQ-RCH-03 — <title>` where a requirement is read (docs/req/*-srs.md); if the row only lists it, correct the ID. Never invent the item to make the ID resolve.

gaps — coverage not met yet; only the gate (qmstrace check --strict) fails on them:
  G05  docs/design/gateway-design.md:32  DSN-RCH-02: satisfies no requirement — every design element points back to one. Fix: the 'Satisfies' table row at docs/design/gateway-design.md:40 is not read — a table declares nothing; write `Satisfies: …` as a line in the item's section.
  G01  docs/req/gateway-srs.md:21  REQ-RCH-02: no design element satisfies it yet. Fix: the 'Satisfies' table row at docs/design/gateway-design.md:40 is not read — a table declares nothing; write `Satisfies: …` as a line in the item's section.

result: 2 violations, 2 gaps in 4 items · 0 suspects (informational) · exit 1 · authoring: gaps do not fail — the gate is qmstrace check --strict

• The table row leaves two gaps, and both name it: the design element satisfies nothing, and the requirement has no design element. Write the link as a line in the section.
• An ID that nothing declares is V16. Declare it as a heading where its kind is read — or, if it only names a planned item, take it out of the table until the item exists.