yq-remove-reasoning-leaks

Trim Reasoning Leakage

Reasoning leakage is durable repository prose written from the authoring session's vantage rather than the project's current, resolvable state. It cites artifacts only that session could see, narrates a change instead of the resulting behavior, argues with a departed reviewer, or walks through reasoning already expressed by code.

The fix is not indiscriminate deletion. Technical prose standard owns the complete-proposition rule: restate every surviving factual clause so it stands at the current revision, then remove the transcript around it. Delete a passage outright only when it carries no durable proposition.

This is guidance, not a script. Pattern searches nominate candidates; semantic review decides them.

The one test

For every suspect passage ask:

Could a reader at the current revision, without the session transcript, review conversation, branch stack, or uncommitted draft, resolve every reference and verify every claim?

If not, restate the surviving facts from the repository's vantage and remove the unresolvable framing. If yes, the passage is not reasoning leakage merely because it mentions history. Current-state surfaces can still contain unnecessary change narration; move durable history to the repository's sanctioned decision, release-note, migration, or postmortem surface.

Taxonomy

1. Dead design-session citations — (decision 7), (audit C2), design §4.7, phase labels, “the design ledger,” or names of drafts not committed anywhere. Cite the real committed owner by name and path, or remove the citation while preserving its factual clause.
2. Branch, stack, and PR vantage — “a later PR in this stack,” “this PR adds,” “the previous commit.” State the resulting mechanism or extension point. When repository edits are authorized, put pending work in an owned TODO. Create or update an external issue only with explicit authorization; otherwise report the proposed deferral and owner.
3. Change narration and indexical version stamps — “used to,” “no longer,” “the old implementation,” “this cut,” “today,” or “now” contrasting with a deleted state. State present behavior. Turn a useful regression history into a present-tense counterfactual such as “without the byte-length guard, multibyte labels double-encode.”
4. Review choreography — “rejected in review,” “the reviewer confirmed,” draft ordinals, or round attributions. Keep the decision and rationale in the appropriate decision-record genre; remove who said it and when.
5. Reviewer-addressed justification — “the cast is safe—it simply…” or “this is correct because…”. State the invariant that makes the operation safe, or remove the comment when code/types already express it.
6. Restatement and derivation transcripts — control-flow narration, obvious proofs, test walkthroughs, and line-by-line previews. Keep only non-obvious contracts, invariants, or assertion rationale.
7. Hedges and ownerless planning residue — “probably fine for now,” “should be enough,” vague roadmap claims, and deferrals without an owner. State a measured bound and failure behavior. When repository edits are authorized, add a concrete owned TODO; create or update an external issue only with explicit authorization. Otherwise report the proposed marker, or delete the hedge when it carries no durable proposition.
8. Authoring-language slips — working-language fragments, private separators, and draft annotations embedded in prose of another language. Translate the durable fact or remove the residue.