Trim Session Leakage

trim-session-leakage — write from the repo's vantage, not the session's

An agent writing prose has two vantages available and only one of them survives:

• the session — what we just discussed, what the last attempt did, what a reviewer asked, what a later step will fix
• the repo at HEAD — what a stranger can read, resolve, and verify today

Prose written from the first vantage reads fine in the session that produced it and becomes unresolvable a week later. That's session leakage, and it's the characteristic decay of an agent-written codebase.

The one test. For every sentence:

Could a reader at HEAD, with no access to any session transcript, PR thread, or uncommitted draft, resolve every reference and verify every claim?

If no, the sentence is written from the wrong vantage. Rewrite it to describe what is true now, or delete it.

Method studied 2026-08-16 in deepseek-ai/deepseek-harness (dsh-trim-cot-leakage), which applies the same test across 688 agent-authored records. It is the natural mechanical companion to this repo's invariant that conversations never enter a repo: that rule keeps transcripts out, this skill keeps the vantage out.

The four leak classes

1. Dead references. Pointers to things a reader cannot open.

• ✗ as decided in the earlier analysis · per the approach we chose · (decision 3)
• ✓ name the file, the record, or the rule — per CLAUDE.md rule #12
• ✓ or state the fact directly and drop the citation

2. Change narration. Prose describing the edit rather than the state. The repo is not a diff; git already holds the history.

• ✗ this used to call the old parser · no longer needs the flag · now correctly handles…
• ✓ describe what it does: parses the frontmatter block
• Exception that matters: a comment recording the causal chain of a real defect is not narration — it is the highest-value comment there is. Keep "returns null here because an empty ledger must not read as success." Cut "changed this to return null."

3. Stack vantage. References to work that isn't at HEAD.

• ✗ a later PR in this stack adds validation · will be wired up next · pending the follow-up
• ✓ state today's limit as a limit: validation is not implemented; callers must pre-check
• This is where leakage and dishonesty overlap — future work described in present tense is the aspiration-as-fact failure the honest-copy rule bans.

4. Reviewer-addressed asides. Sentences aimed at one reader in one moment.

• ✗ as you suggested · to address the review comment · I kept this simple for now
• ✓ delete, or convert to a stated limitation with a reason

How to run it

1. Scope it. A PR's changed files, a docs folder, or one package. Whole-repo sweeps produce more findings than anyone acts on.
2. Grep the tells, then read around each hit — the patterns find candidates, not verdicts:

grep -rnE "\b(used to|no longer|previously|now correctly|as (we|you) (discussed|suggested|decided)|earlier (analysis|conversation)|a later (PR|step|commit)|will be (added|wired|fixed) (next|later)|for now|TODO\(follow-?up\))" --include="*.md" --include="*.ts" .

3. Apply the test to each hit. Most change-narration hits are cuts. Most dead references are either resolved to a real path or promoted to a stated fact.
4. Preserve causal chains. Before deleting any "why" comment, check whether it records a defect's cause. If it does, keep it and fix only its vantage.
5. Report what you changed and what you deliberately left — a sweep that silently rewrites prose is its own kind of leak.

Known limits

• Pattern-first, so it under-finds. The grep catches phrasing, not vantage. A sentence like "the registry handles this correctly" can be pure session vantage with no tell-tale words, and this skill will walk past it.
• It cannot tell a causal chain from narration by pattern. That judgement is human or model reading, every time — which is why step 4 is a read, not a rule.
• No autofix, deliberately. Rewriting prose from a vantage the tool cannot verify is how meaning gets destroyed quietly. This skill proposes; a person or a reviewed session applies.
• Not a substitute for the conversations-never-in-a-repo invariant. That rule is absolute and prevents transcripts from landing at all. This skill only cleans vantage from prose that legitimately belongs in the repo.
• Whole-repo sweeps are low-yield here. On a repo with heavy prose density the grep returns hundreds of hits, most of them legitimate. Scope it or the findings go unread.