Skip to content

Template Diet — Feasibility Gates for Constraint Reform

Pattern

When tightening a template constraint that already has many existing instances in the repo, gate the reform on three independent feasibility checks before locking targets:

  1. Dogfood self-measurement — the spec's own artifact (produced via the new template) must satisfy the new targets.
  2. Calibration corpus — rewrite N representative historical artifacts in the new format; assert their measured metrics also satisfy the targets.
  3. Legacy bit-identity HARD gate — assert every pre-existing artifact under path/to/old/* is byte-identical to its pre-spec state. Mixed-format repo is acceptable; silent migration is not.

Each prong answers a different question, so all three are needed.

When to Apply

  • Reform proposes a quantitative budget (max lines, max boilerplate share, max field count) on a template
  • The repo holds ≥10 existing artifacts produced under the old template
  • The reform sounds reasonable but the team has no empirical baseline showing the budget is realistic on real-world content
  • Backward compatibility is explicit ("old artifacts stay as-is") — silent drift would erode the compat guarantee

Why Each Prong Is Independent

Prong Question it answers Failure if missing
Dogfood "Can a brand-new artifact under the new template hit the budget?" Targets sound right but the template emits something that itself fails the budget — circular blocker.
Calibration corpus "Are the targets realistic on real historical content, not just trivial new specs?" Targets pass dogfood but fail every real spec rewrite — budget is unachievable for the actual workload.
Legacy bit-identity "Did the reform leave old artifacts untouched?" An IDE format-on-save or an over-eager linter silently rewrites legacy files — backward-compat guarantee broken without anyone noticing.

How To Apply

  1. Pick the budget, but mark it provisional until all three gates pass.
  2. Dogfood: generate the spec's own artifact under the new template; record measured metrics in state.yaml.build_gate.dogfood_self_measurement (or equivalent). MUST pass the budget.
  3. Build a calibration corpus: rewrite ≥3 historical artifacts representative of the workload (small / medium / large spec; simple / complex feature). Store under specs/[N]-feature/calibration/. Assert median measured metric ≤ budget.
  4. Add legacy bit-identity test as a HARD GATE in the test suite: git diff <merge-base>..HEAD -- old/path/* ':!new/path/**' MUST return empty. Failing this test blocks the build_gate.
  5. Record all three results in state.yaml so audit is machine-readable, not narrative.
  6. Only after all three gates pass, lock the targets and ship the template change.

Example — SPEC-143

The reform tightened plan.md to median ≤100 lines and ≤8% boilerplate (down from 146 lines / 18%).

  • Dogfood: SPEC-143's own plan.md measured 75 lines / 0% boilerplate. Recorded in state.yaml.build_gate.dogfood_self_measurement.
  • Calibration corpus: SPEC-126, SPEC-127, SPEC-136 rewritten under the diet template, stored under specs/143-plan-md-template-diet/calibration/. Median 55–75 lines. Validated targets weren't accidentally tuned to a single easy case.
  • Legacy bit-identity: T4 HARD GATE in test-plan-md-diet.sh asserts git diff main..HEAD -- specs/*/plan.md ':!specs/143-plan-md-template-diet/**' is empty. Caught a near-miss during build (an editor-on-save would have silently re-flowed two legacy plan.md files).

Without the calibration corpus, the team would have shipped targets that passed dogfood (a trivial new spec) but would have failed on the next real-world plan. Without the bit-identity gate, FR-7 ("139 existing plan.md MUST NOT be touched") would have been a soft promise rather than a CI-enforced contract.

Relationship To Other Patterns

  • Complements dogfooding-meta-acceptance.md — that pattern dogfoods output correctness (text the user sees); this one dogfoods constraint feasibility (whether a budget is achievable). Both can apply to the same spec.
  • Complements heuristic-calibration-gate.md — that pattern calibrates detector FP rates against a real corpus; this one calibrates constraint budgets against a real corpus. Same corpus-based defence, different signal.
  • Pairs with wave-independent-shipping.md for reforms split into multiple slices — each wave's budget should pass its own three-prong feasibility check before that wave ships.

Anti-Patterns

  • ❌ "We measured one spec; ship it." — without a calibration corpus, the budget may be tuned to a non-representative case.
  • ❌ "We trust contributors won't accidentally rewrite legacy artifacts." — IDE format-on-save and well-meaning linters drift artifacts silently; only a CI gate catches it.
  • ❌ Calibration corpus = "the same three small specs every time" — pick a deliberate small / medium / large mix so the budget is stressed near its edge.
  • ❌ Recording feasibility outcomes only in prose (PR description, review comment) — audit must be machine-readable from state.yaml.

See Also

  • dogfooding-meta-acceptance.md — sister pattern for output-text correctness
  • heuristic-calibration-gate.md — sister pattern for detector accuracy
  • SPEC-143 state.yaml — example of dogfood + build_gate.verification.hard_gates_passed recording
  • SPEC-143 tests/test-plan-md-diet.sh — example of T4 legacy bit-identity HARD GATE