---
digest-of: comparison-docs
last-synced: 2026-09-10
token-estimate: 600
---
# AGENTS
## Scope
The format for a document comparing one project against its alternatives. Covers the artifact model, table width and thematic splitting, the verdict vocabulary, and the two reference levels. It also covers the shape of a scenario and its evidence, dating and refresh, and the gates.
The documentation method itself (zones, specs, decision records, the markdown register) belongs to `../method/`. This shelf owns one genre inside it.
## How to use this shelf
Load this file, find the owning chapter below, then read that chapter. Do not read the shelf linearly. Building a comparison document from scratch means reading `model.md` first, then following `README.md` under Apply the genre.
## Where the rules live
| What is a verdict allowed to be based on? | `model.md` |
| How wide can the table be, and when do I split it? | `table-shape.md` |
| Which verdict do I put in this cell, and how is it written? | `verdicts.md` |
| Where can a link start, where does it land, how many? | `references.md` |
| What shape is the scenario and its result? | `scenarios.md` |
| How is the document dated and refreshed? | `freshness.md` |
| What command enforces this rule? | `gates.md` |
| What must pass before this merges? | `checklist.md` |
| Why does this rule exist? | `SOURCES.md` |
Template: `../templates/TEMPLATE-comparison.md`.
## Non-negotiables
- A verdict describes a run the author performed. A capability not run is `❓ untested`.
- The method is identical for every subject in its row.
- The document includes the rows where its own subject loses.
- The subject occupies the first data column, in every table.
- A cell holds one verdict from the fixed six, written as a symbol followed by its word.
- A cell is never empty and never a bare dash.
- A cell carries at most one reference, and that reference is a heading anchor.
- A row label links to the method. A verdict links to the evidence. The two never coincide.
- Every table carries a `Verified:` line with the run date and every subject version.
- A pipe inside a code span in a table row is escaped as `\|`, and the check for it runs before the markdown formatter.
- Use no bold or italics, and give every fenced block a language.
## Maintenance
- Regenerate when this shelf's chapters change.
- This digest is a router, never a rules home. The owning chapter wins on disagreement.