agent-skills/skills/remove-reasoning-transcript-prose/SKILL.md

name, description

name	description
remove-reasoning-transcript-prose	Use when durable documentation or comments contain design-session narration, PR-stack references, reviewer commentary, change narration, dead draft citations, conversational control flow, or other prose that cannot be resolved and verified from the repository at HEAD.

Remove Reasoning-Transcript Prose

Durable prose must speak from the repository’s current, verifiable vantage. Remove the authoring-session transcript while preserving every factual clause a maintainer still needs.

The core test

For each passage ask:

Can a reader at HEAD resolve and verify every reference and claim without seeing the authoring session, PR thread, review conversation, or uncommitted draft?

If no, enumerate the passage’s facts, restate the surviving facts from HEAD’s vantage, and delete the transcript framing. If the passage contains no durable fact, delete it outright.

1. Set scope and exclusions

Require an explicit file/directory/diff scope. Read applicable repository instructions. Exclude vendored sources, generated artifacts whose owner is elsewhere, recorded model fixtures, and frozen archives unless the user explicitly requests those artifacts and they are editable.

For generated prose, edit the owning source or template and regenerate. Treat model-visible strings as behavior: require the appropriate snapshot or behavior test before changing them.

2. Audit read-only first

Use searches as recall probes, then read dense prose semantically:

rg -n --hidden -g '*.md' -g '*.{ts,tsx,js,jsx,py,go,rs,java}' \
  '(decision [A-Z0-9]+|audit [A-Z0-9]+|design §|plan §|this PR|this commit|later PR|previous commit|rejected in review|reviewer|used to|no longer|for now|should be enough|first we|then we)' <scope>

Also inspect module docs, JSDoc, comments around surprising invariants, READMEs, and decision records without a search pattern in mind. Patterns miss paraphrases and produce legitimate hits.

3. Classify each suspect passage

Dead session citations

Examples: (decision 7), audit C2, design §4.7, task-wave labels, “the design ledger.” Replace with a named committed link when one owns the fact; otherwise remove the citation and make the factual clause stand alone.

PR/stack vantage

Examples: “this PR adds,” “a later PR in the stack,” “the previous commit.” State the current mechanism. Put real deferred work in a resolvable issue or TODO(owner): marker.

Change narration

Examples: “used to,” “no longer,” “the old implementation,” “in this cut,” “now” as a release contrast. In current-state docs, state present behavior. Preserve a useful regression reason as a counterfactual:

Before: We used to delete the directory recursively, but now unlink junctions.
After: Unlink junctions; recursive removal can descend into the junction target.

Review choreography

Examples: “rejected in review,” “the reviewer confirmed,” “version 5 addresses feedback.” Keep the decision and rationale; remove who said it and in which round.

Reviewer-addressed justification

Examples: “this cast is safe because…” or “this is correct because…” State the invariant that makes it safe, or delete the comment when the code already makes it obvious.

Conversational control flow

Examples: “first we considered X, then we realized Y,” walkthroughs of obvious branches, or narration of how the author reasoned. Replace with the resulting contract, invariant, or consequence.

Hedges and planning residue

Examples: “probably fine for now,” “should be enough,” or an unowned deferral. Replace with the actual bound or a mechanically resolvable TODO/issue; otherwise delete.

4. Preserve complete propositions

Before editing, list internally every proposition:

• actor and action;
• condition, timing, and order;
• must, may, never, or other modality;
• negative guarantee and exception;
• ownership and side effect;
• failure mode and consequence;
• evidence or provenance that remains verifiable.

Rewrite only after every relevant proposition has a destination. Never delete a factual clause merely because it shares a sentence with transcript framing.

Worked example:

Original: Reviewer B confirmed in round 3 that we now close listeners before killing the child, because otherwise callbacks from the old implementation raced teardown.

Facts:
- listeners close before child termination;
- late callbacks can race teardown if listeners remain open.

Rewrite: Close listener registries before terminating the child so late completion callbacks cannot enter teardown state.

5. Preserve legitimate history and references

Do not remove:

• issue references and owned TODOs that resolve at HEAD;
• external standards citations;
• committed decision-record links;
• PR/issue evidence inside sanctioned postmortems or decision-history sections;
• suppression and empty-catch justifications;
• measured bounds with meaningful provenance;
• counterfactual-present regression warnings (“without X, Y occurs”);
• runtime old/new states (“the old connection drains before the new one accepts”);
• genuine alternatives-considered sections.

Resolvable history may still be misplaced in a current-state README; move unique causal history to a decision record or postmortem and keep the present contract locally.

6. Edit owner-first

For each candidate choose one outcome: keep, restate, delete, move, or defer.

• generated catalog → edit source documentation, regenerate;
• duplicated explanation → keep one authoritative home, retain essential local contract;
• current-state doc → present behavior and consequence;
• decision record → preserve unique rationale and alternatives;
• postmortem → preserve incident sequence, evidence, and causal chain;
• comment → retain only non-obvious invariant, ownership, failure, or rationale.

Do not optimize for word-count reduction. A shorter sentence that drops a precondition or negative guarantee is worse.

7. Verify the rewrite

Re-run the recall searches and inspect remaining hits. For each keep, explain why it is resolvable and appropriate to that document genre. Then check:

• every internal reference resolves at HEAD;
• no factual proposition disappeared in the diff;
• modal force and exceptions are unchanged;
• no hypothetical became a claim of shipped behavior;
• current-state docs no longer narrate PR/review chronology;
• generated or paired artifacts were updated through their owner;
• relevant link, docs, lint, and snapshot checks pass.

Report scope inspected, passages restated, passages deleted as fact-free narration, deliberate keeps, and any deferred model-visible or frozen artifact.