@@ -517,59 +517,89 @@ When stuck in debugging loops:
5175173 . ** Document the issue** comprehensively for a fresh approach
5185184 . ** Format for portability** (using quadruple backticks)
519519
520- ## Shipped vs. Branch-Internal Narrative
520+ ## AI Slop Prevention
521+
522+ Treat AI slop as ** review-hostile noise** , not as proof that text or
523+ code is wrong. The goal is to maximize information density by removing
524+ artifacts that make the repository harder to trust or navigate.
525+
526+ ### The Anti-Slop Rubric
527+
528+ Before committing, audit all AI-assisted changes for these noise
529+ patterns:
530+
531+ - ** AI Signatures:** Remove "Generated by", footers, conversational
532+ filler ("Certainly!", "Here is..."), unexplained emojis (🤖, ✨), and
533+ AI-tool metadata.
534+ - ** Brittle References:** Avoid hard-coded line numbers, fragile
535+ file/test counts, dated "as of" claims, bare SHAs, and local
536+ absolute paths unless they are strict evidentiary artifacts (e.g.,
537+ benchmark logs).
538+ - ** Diff Narration:** Do not restate what moved, was renamed, or was
539+ removed in artifacts the downstream reader holds: code, docstrings,
540+ README, CHANGES, PR descriptions, or release notes. The diff and
541+ commit message already carry this history.
542+ - ** Branch-Internal Narrative:** Do not mention intermediate branch
543+ states, abandoned approaches, or "no longer" behavior unless users
544+ of a published release actually experienced the old state (** The
545+ Published-Release Test** ).
546+ - ** Low-Value Scaffolding:** Remove ownerless TODOs (` TODO: revisit ` ),
547+ unused future-proofing, debug artifacts, and defensive wrappers that
548+ do not protect a currently reachable failure mode.
549+ - ** Prose Inflation:** Replace generic AI "tells" like * comprehensive,
550+ robust, seamless, production-ready, leverage, delve, tapestry,* and
551+ * best practices* with concrete descriptions of behavior,
552+ constraints, or trade-offs.
553+
554+ ### Preservation & Context
555+
556+ ** When unsure, leave the text in place and ask.** Subjective cleanup
557+ must never be a reason to remove load-bearing rationale.
558+
559+ - ** Preserve the "Why":** You MUST NOT delete comments that document
560+ invariants, protocol constraints, platform quirks, security
561+ boundaries, and upstream workarounds.
562+ - ** Evidence is Immune:** Preserve exact counts, dates, and SHAs when
563+ they serve as evidence in benchmark results, release notes, stack
564+ traces, or lockfiles.
565+ - ** Behavior Over Inventory:** A useful description explains what
566+ changed for the * system or user* ; it does not provide an inventory
567+ of files or functions the diff already shows.
568+
569+ ### The Published-Release Test
521570
522571Long-running branches accumulate tactical decisions — renames,
523- refactors, attempts-then-reverts, intermediate states. Commit messages
524- and the diff hold * what changed* and * why* . Do not restate either in
525- artifacts the downstream reader holds: code, docstrings, README,
526- CHANGES, PR descriptions, release notes, migration guides.
527-
528- When deciding what counts as branch-internal, use trunk or the parent
529- branch as the baseline — not intermediate states inside the current
530- branch.
531-
532- ** The Published-Release Test**
533-
534- Before adding rename history, "previously" / "formerly" / "no longer
535- X" phrasing, "removed" / "moved" / "refactored" / "fixed" diff
536- paraphrases, or ` ### Fixes ` entries to a user-facing surface, ask:
572+ refactors, attempts-then-reverts. When deciding what counts as
573+ branch-internal, use trunk or the parent branch as the baseline — not
574+ intermediate states inside the current branch. Ask:
537575
538576> Did users of the most recently published release ever experience
539577> this old name, old behavior, or bug?
540578
541- If the answer is no, it is branch-internal narrative. Move it to the
542- commit message and describe only the current state in the artifact.
543-
544- ** Keep in shipped artifacts**
579+ If the answer is ** no** , it is branch-internal narrative. Move it to
580+ the commit message and describe only the final state in the artifact.
545581
582+ ** Keep in shipped artifacts:**
546583- Deprecations and migration guides for symbols that actually shipped.
547584- ` ### Fixes ` entries for bugs that affected users of a published
548585 release.
549- - Comments explaining * why the current code looks this way* —
550- invariants, platform quirks, upstream bug workarounds — that make
551- sense to a reader who never saw the previous version.
552-
553- ** Default** : when in doubt, keep the artifact clean and put the story
554- in the commit.
586+ - Comments explaining * why the current code looks this way*
587+ (invariants, platform quirks) that make sense to a reader who never
588+ saw the previous version.
555589
556590### Cleanup in Hindsight
557591
558- When applying this rule retroactively from inside a feature branch,
592+ When applying these rules retroactively from inside a feature branch,
559593first establish scope by diffing against the parent branch (or trunk)
560594to identify which commits this branch actually introduced. Then:
561595
562- - ** Commits introduced in this branch** — prompt the user with two
563- options: ` fixup! ` commits with ` git rebase --autosquash ` to address
564- each causal commit at its source, or a single cleanup commit at
565- branch tip. User chooses.
566- - ** Commits already in trunk or a parent branch** — default to
567- leaving them alone. Do not raise them as cleanup candidates; act
568- only on explicit user instruction. If the user opts in, fold the
569- cleanup into a single commit at branch tip and do not rewrite trunk
570- or parent-branch history.
571- - ** Scope guard** — if cleaning in-branch bleed would touch a
572- colleague's in-flight work or expand the branch beyond its stated
573- goal, default to staying in lane: protect the project's current
574- goal, leave prior bleed alone, and don't introduce new bleed in the
575- current change.
596+ - ** In-branch commits:** Prompt the user with two options: ` fixup! `
597+ commits with ` git rebase --autosquash ` to address each causal commit
598+ at its source, or a single cleanup commit at branch tip.
599+ - ** Trunk/Parent commits:** Default to leaving them alone. Act only on
600+ explicit user instruction. If the user opts in, fold the cleanup
601+ into a single commit at branch tip; do not rewrite shared history.
602+ - ** Scope guard:** If cleaning prior slop would touch a colleague's
603+ work or expand the branch beyond its stated goal, stay in lane:
604+ protect the current goal and leave prior slop alone.
605+
0 commit comments