Record templates

Task and place

Task: give every package the same four record shapes, so a reviewer can walk any dossier blind. Place: companion to every pipeline stage. Scope writes the card, source work fills the inventory, modeling writes decision records, review writes the review record; this page defines the shapes once so the stage pages can point here.

Inputs

The four blanks: the scope card template, the source inventory template, the decision record template, and the review record template.
The filled EAI samples plus the field checker beside them (see Artifact below).
A plain Python 3 for the checker; it uses the standard library only.

Actions

Fill records in pipeline order: card first, inventory second, decision records as close calls surface, review record last. Each shape below states its purpose, its placement, and its relation to other record habits.

Scope card. Purpose: fix what the package answers and refuses before any rule exists. Placement: written at the scope stage, read at every later stage, reopened at revisit. Relation: this shape is a handbook convention for canon packages, not an import from another record system. Where a team already keeps its own planning notes, map them field to field onto the card and keep every required heading; the checker below reads headings, not team style.
Source inventory. Purpose: prove every content unit of the pinned bytes met an explicit fate — included, excluded, or unprocessed. Placement: written over the pinned edition before modeling, cited by rules and decisions. Relation: same convention status as the card. Teams that track coverage in their own ledgers keep the one rule that matters: no unit ends without a fate, and the counts reconcile.
Decision record. Purpose: capture each choice a later reader cannot re-derive from the pinned text, with the test that breaks if the position flips. Placement: one record per close call, written when the call surfaces, linked from the governed rules and tests. Relation: same convention status; the distinguishing field is the tripwire test, which no planning note can replace.
Review record. Purpose: state what was reviewed, how, what was found, and the verdict. Placement: written at review, read at release and revisit. Relation: same convention status; the findings table is the handover — a finding with no disposition row is still open.

The field checker reads each file for its title line and required headings, and additionally refuses TODO markers in filled records. Run it after every record edit; it reports one line per file plus a total.

Decisions

Which records a package needs: shared canon always carries all four shapes with every heading filled; a solo draft keeps the same shapes with lighter prose but never drops a heading.
One decision record per close call, or one per cluster: prefer one per call so each keeps its own tripwire test; cluster only calls that flip together.
Finding outcomes stay on the review record: fix now with a confirming re-run, or defer with a reason — never silence.

Artifact

Blanks for reuse:

Filled EAI samples:

filled EAI scope card (v1, whole-article lines — the before-state), its v2 revision (branch granularity, article 19 split — history), and the current v3 card (premium reads the insured sum)
filled EAI source inventory (v1), its v2 revision (history), and the current v3 inventory
filled EAI tariff decision
filled EAI threshold decision
filled EAI penalty decision
filled EAI premium-base decision (EAI-D4)
filled EAI review, the candidate review bound to the pre-R3 snapshot (history), and the current R3 review bound to the accepted snapshot

Plus the field checker, standard library only. The worked dossier that produced the filled samples is the end-to-end worked example.

EAI example

The EAI package filled all four shapes three times: whole-article granularity (the v1 before-state), branch granularity (the v2 confirmation, now history), and the corrected premium model (the current v3). The v1 card draws the four-article slice with case categories, limits, external data, and provenance; the v2 card splits article 19 into the insurer and employer branches with every other unit excluded by name; the v3 card keeps that split and moves the premium branch from payroll to the contract insured sum with the minimum floor. The inventory maps twenty-eight articles to four included, twenty-four excluded, zero unprocessed in v1, to six included units plus twenty excluded units plus zero unprocessed in v2, and to seven formalized plus two assumed plus seventeen excluded plus zero unprocessed in v3. Four decision records stand as filled samples — EAI-D1 for the tariff shape, EAI-D2 for the inclusive thirty boundary, EAI-D3 for the exact-penalty position with its fractional tripwire, and EAI-D4 for the premium base with its floor and boundary probes. The agent review carries finding EAI-R1 open; the candidate review closes it and binds the verdict to the pre-R3 snapshot 8e3297de…; the current R3 review closes EAI-R1 and EAI-R3 and binds the verdict to the accepted snapshot 7635d197….

Pitfall

Filling records after the fact from memory: the card then describes the model instead of constraining it, and the inventory quietly drops the articles nobody modeled. Write the card before rules, walk the inventory over the pinned bytes rather than recollection, and open each decision record when the close call surfaces — the tripwire test field forces the honest moment.

Verify

Observed run with Python 3.13.13, from the repo root:

$ python3 docs/handbook/files/check_templates.py docs/handbook/files/templates docs/handbook/files/filled
ok docs/handbook/files/templates/decision-record.md
ok docs/handbook/files/templates/review-record.md
ok docs/handbook/files/templates/scope-card.md
ok docs/handbook/files/templates/source-inventory.md
ok docs/handbook/files/filled/eai-decision-penalty.md
ok docs/handbook/files/filled/eai-decision-premium-base.md
ok docs/handbook/files/filled/eai-decision-tariff.md
ok docs/handbook/files/filled/eai-decision-threshold.md
ok docs/handbook/files/filled/eai-review-agent.md
ok docs/handbook/files/filled/eai-review-candidate-r3.md
ok docs/handbook/files/filled/eai-review-candidate.md
ok docs/handbook/files/filled/eai-scope-card-v2.md
ok docs/handbook/files/filled/eai-scope-card-v3.md
ok docs/handbook/files/filled/eai-scope-card.md
ok docs/handbook/files/filled/eai-source-inventory-v2.md
ok docs/handbook/files/filled/eai-source-inventory-v3.md
ok docs/handbook/files/filled/eai-source-inventory.md
total: 17 checked, 17 passed, 0 failed
exit=0

Two negative probes confirm the checker bites. A scratch review copy with its verdict heading removed:

$ python3 docs/handbook/files/check_templates.py /tmp/eai-records-broken/filled/eai-review-agent.md
FAIL /tmp/eai-records-broken/filled/eai-review-agent.md: missing ## Verdict
total: 1 checked, 0 passed, 1 failed
exit=1

A scratch scope copy with a leftover TODO marker:

$ python3 docs/handbook/files/check_templates.py /tmp/eai-records-todo/filled/eai-scope-card.md
FAIL /tmp/eai-records-todo/filled/eai-scope-card.md: filled record still carries a TODO marker
total: 1 checked, 0 passed, 1 failed
exit=1

A mistyped path fails loudly instead of passing vacuously — a re-review caught the old exit-0-on-missing behavior, and the collector now counts it:

$ python3 docs/handbook/files/check_templates.py docs/handbook/files/filled-eai
FAIL docs/handbook/files/filled-eai: no such file or directory
total: 0 checked, 0 passed, 0 failed
exit=1

Observed run; the mixed case (one good path plus one missing path) and the empty-directory case exit 1 the same way. Zero documents found is an error by policy: a mandatory record check that checks nothing must not read green.

Criterion: the full run reports seventeen checked with seventeen passed and zero failed, and each negative probe names its defect with a nonzero exit. Records pass here when their shape is complete; whether their claims are true stays a reviewer judgment. This count is the single source for the record-checker tally; other pages cite it, never restate it.

Limits

The checker reads presence, not truth: a complete card can still scope the wrong articles, and a complete review can still miss a finding. It does not read the model, the suite, or the pinned bytes — those belong to the law checks. Record shapes never substitute for the underlying evidence they point at.

Next step

Continue with Troubleshooting, which diagnoses a misbehaving package symptom by symptom.

Sources

Documentation for Arxo. Writings — blog.arxo.io.

Anonymous visit counts on stats.arxo.io, no cookies.