Skip to content

Count Reconciliation to a Single Authoritative Source

Problem

Numbers embedded in prose are duplicated far more widely than code constants. When a refactor changes such a number, the change lands in the one place that does the work (a script, a manifest) but the number lives on — stale — in frontmatter descriptions, body text, diagram comments, gate templates, and generated docs.

Two failure modes compound:

  1. Wide drift. SPEC-145 replaced /vt-c-4-review's fixed "6 parallel reviewers" fan-out with a diff-scoped selector. The selector shipped correctly, but the literal string "6 parallel reviewers" survived in the SKILL.md frontmatter, five body locations, and the orchestrator's worked example. Three separate reviewers (pattern, document-quality, performance) each independently re-flagged it.

  2. Wrong-source reconciliation. A later finalize pass tried to "fix" the core-standards skill count and set it to 124 — the raw count of SKILL.md folders on disk — on the false premise that the new vt-c-pov skill took the count from 123 to 124. In reality pov was already registered (123), and the 124th folder was 0-init, a pre-existing skill that is not in the deploy manifest and therefore never ships. The "fix" made plugin.json (124) disagree with the manifest (123) — it propagated a wrong value that looked authoritative.

Solution

Treat any count-changing refactor as a reconciliation problem with one declared source of truth, and verify against it mechanically:

  1. Pick the authoritative source deliberately. For "how many skills does this plugin have," the answer is what deploys — the skill-symlinks.manifest — not the raw folder count. Raw folders can include unregistered/half-shipped artifacts (0-init). Declared counts (plugin.json, README, macros) reconcile to the manifest, never to find | wc -l.

  2. Grep the literal after the refactor. Once a number changes, grep -rn the old literal across the repo ("6 parallel", the old count) and confirm every hit is either updated or is a deliberate historical reference (e.g. a CHANGELOG or a "not a fixed 6" corrective line). Prefer non-numeric phrasing in prose that a selector now controls ("the selected reviewers", not "6 reviewers") so it can't drift again.

  3. Assert cross-source agreement, not just self-consistency. A count that is internally consistent within one file can still disagree with its authoritative twin. After reconciliation, print all sources side by side: declared == manifest, registry.version == plugin.version. A one-line shell check catches the divergence a prose read misses.

  4. Don't let an unrelated gap ride in on a version bump. If reconciliation surfaces a pre-existing discrepancy (the 0-init registration gap), name it, keep the declared count honest to the authoritative source, and file the gap separately — do not silently absorb it into the current spec's accounting by bumping the number to match raw folders.

Evidence

SPEC-145: the fixed-6→selected-N doc-drift was auto-fixed during review Step 4.5 (7 locations, re-verified by grep + green tests). The finalize-pass 123→124 over-correction was caught during /vt-c-complete verification and reverted; the authoritative source was declared to be the manifest (123 = deployed), with the 0-init folder gap logged as a separate pre-existing bug. See specs/145-compound-engineering-pattern-adoption-wave-1/review-triage.md and the commit trail 8e06fb1b (review) / b05af030 (finalize reconciliation).

When to Apply

  • Any refactor that turns a fixed count into a dynamic one, or that adds/removes a counted component (skills, agents, reviewers, phases).
  • Any doc-sync or finalize step that "reconciles" a count — confirm the source it reconciles to is the authoritative one, and that it isn't papering over an unrelated gap.