Skip to content

Commit 991d1c3

Browse files
committed
ai(rules[AGENTS]) add AI slop prevention standards
why: AI-assisted contributions need clear signals to reduce noise and preserve technical context beyond simple narrative bleed. what: - Expand narrative bleed rules into full AI Slop Prevention rubric - Add specific prohibitions for AI signatures and prose inflation - Include safety guardrails to preserve load-bearing context
1 parent d3ce780 commit 991d1c3

1 file changed

Lines changed: 70 additions & 40 deletions

File tree

AGENTS.md

Lines changed: 70 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -517,59 +517,89 @@ When stuck in debugging loops:
517517
3. **Document the issue** comprehensively for a fresh approach
518518
4. **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

522571
Long-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,
559593
first establish scope by diffing against the parent branch (or trunk)
560594
to 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

Comments
 (0)