plan-cross-encoding-review git:20261019.b3a119bA

Immutable. This exact content never changes and is served at /api/v1/blob/b894b8da0e09b5b8.

---
name: plan-cross-encoding-review
description: >
  Use when reviewing an implementation plan, spec, or task breakdown before
  handing it to an implementer — catches the class of bug where one intent is
  encoded twice and the two encodings silently disagree. Triggers on "review
  this plan", "check this spec", "self-review the plan", "before I implement",
  "fixture values", "edge case in the plan", and writing task breakdowns with
  hardcoded fixtures or guards.
---

# Plan Cross-Encoding Review

**Type:** Open-source — client-agnostic methodology, no project-specific detail.

**Created by akbarsha — https://github.com/iamakbarsha1**

Distilled from plan-review failures where one intent was written down twice
and the two copies drifted apart.

**Licence:** Released under CC BY 4.0 — share and adapt for any purpose with
credit. Full text: `LICENSE` at the repository root.

**Feedback & Support:** If a rule here proves wrong or needs sharpening,
open an issue on the repository or contact the author at the profile link
above. If the problem is the agent not following a rule below rather than
the rule itself, that's an execution failure — acknowledge and correct it.

## The core rule

When a plan encodes one intent two ways, diff the two encodings against each
other before shipping the plan. Divergence between two representations of the
same intent is a latent bug that the implementer will resolve in the wrong
direction.

## When this fires

**Where:** Reviewing an implementation plan, spec, or task breakdown before an
implementer picks it up — especially one carrying hardcoded fixture pairs, a
count published in several places, or prose sitting next to a code block.

**The case this came from.** A plan's prose promised that a failed retry would
roll back its partial write; the pasted code skipped that step, and the
implementer transcribed the code. Same family: a fixture hardcoded a Unix
epoch and its human-readable date as an unchecked pair and the date was wrong,
and a catalogue count propagated by grepping the digit left a spelled-out
heading and one per-section subtotal still on the old value.

**Another shape it takes.** *(Illustrative: A plan states a rate limit as "60
requests per minute" in prose and `limit: 600` in the config snippet below it.
The implementer ships the snippet, the prose becomes the published
documentation, and support spends a quarter explaining the mismatch.)*

## Checks

- **Redundant-value agreement.** Any two hardcoded values related by a pure
  function (epoch↔date, hash↔slug, size↔count) are a latent contradiction
  unless one is computed from the other or the pair is explicitly verified.
  Reused magic pairs multiply the blast radius across tasks. *(A test fixture
  hardcoded a Unix epoch and its human date as an unchecked pair; the date was
  wrong, and the same pair reused across tasks would have multiplied the bug —
  a failing test caught it just before it shipped.)*
- **Count-across-surfaces agreement.** A quantity published in more than one
  place is one intent with N encodings, and it does not appear only as a digit:
  the same count shows up spelled out in a heading, and as per-section
  subtotals that have to sum to the whole. A grep for the old number proves
  none of those. Close it with a structural invariant — enumerate the real
  items, assert each section's declared count matches its contents and that the
  sections sum to the total — plus a sweep for the word form of both the old
  and the new count. *(A catalogue's count was propagated by grepping the
  digit; the badge, meta tags and install line all updated, while a spelled-out
  heading and one per-section subtotal kept the old value and shipped.)*
- **Prose-vs-code agreement.** When a task gives both a prose description of
  an edge case and the code, and they disagree, the implementer transcribes
  the code and silently ignores the prose. For every edge-case behaviour you
  describe in prose, point to the exact code line that implements it; if the
  code doesn't, fix the code or delete the prose claim. Never ship a plan
  whose prose promises behaviour the code block doesn't deliver — especially
  on data-loss or security edges. *(A task's prose promised a failed retry
  would roll back its partial write, but the pasted code skipped that step;
  the implementer copied the code as written, and partial writes silently
  landed on every retried failure.)*
- **Guard shape and ordering.** When a plan specifies a guard over
  machine-generated text that embeds user data, match the forbidden
  STRUCTURE (e.g. a specific trailer line), not bare keywords that also occur
  legitimately as data (e.g. reserved words appearing inside user-supplied
  names). And order side-effecting steps so the validating/throwing step runs
  BEFORE any durable state advance (validate → act → commit state last), so a
  failure is a safe retry rather than corruption. *(A guard blocked the bare
  word "reserved" meant to catch one trailer line, and also rejected a
  legitimate user name containing it; the check ran after the record was
  already committed, so the false rejection surfaced only after durable
  state had already changed.)*

## Pre-flight check — before you ship the plan

- [ ] Every pair of related hardcoded values is computed or explicitly
      verified against each other.
- [ ] Every published count is closed by a structural invariant (parts sum to
      the whole) and a word-form sweep, not by a grep for the digit.
- [ ] Every prose edge-case claim names the code line that implements it.
- [ ] Every guard matches a structure, not bare keywords, and validates
      before advancing durable state.

If any box is unchecked, the plan is not review-clean — fix it inline.