Skip to content

Commit d0924b2

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 f58c2bc commit d0924b2

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
@@ -296,59 +296,89 @@ These rules apply when authoring entries in `CHANGES`, which is rendered as the
296296
- Repository: https://github.com/vcs-python/g
297297
- Shared tooling (gp-libs): https://gp-libs.git-pull.com/
298298

299-
## Shipped vs. Branch-Internal Narrative
299+
## AI Slop Prevention
300+
301+
Treat AI slop as **review-hostile noise**, not as proof that text or
302+
code is wrong. The goal is to maximize information density by removing
303+
artifacts that make the repository harder to trust or navigate.
304+
305+
### The Anti-Slop Rubric
306+
307+
Before committing, audit all AI-assisted changes for these noise
308+
patterns:
309+
310+
- **AI Signatures:** Remove "Generated by", footers, conversational
311+
filler ("Certainly!", "Here is..."), unexplained emojis (🤖, ✨), and
312+
AI-tool metadata.
313+
- **Brittle References:** Avoid hard-coded line numbers, fragile
314+
file/test counts, dated "as of" claims, bare SHAs, and local
315+
absolute paths unless they are strict evidentiary artifacts (e.g.,
316+
benchmark logs).
317+
- **Diff Narration:** Do not restate what moved, was renamed, or was
318+
removed in artifacts the downstream reader holds: code, docstrings,
319+
README, CHANGES, PR descriptions, or release notes. The diff and
320+
commit message already carry this history.
321+
- **Branch-Internal Narrative:** Do not mention intermediate branch
322+
states, abandoned approaches, or "no longer" behavior unless users
323+
of a published release actually experienced the old state (**The
324+
Published-Release Test**).
325+
- **Low-Value Scaffolding:** Remove ownerless TODOs (`TODO: revisit`),
326+
unused future-proofing, debug artifacts, and defensive wrappers that
327+
do not protect a currently reachable failure mode.
328+
- **Prose Inflation:** Replace generic AI "tells" like *comprehensive,
329+
robust, seamless, production-ready, leverage, delve, tapestry,* and
330+
*best practices* with concrete descriptions of behavior,
331+
constraints, or trade-offs.
332+
333+
### Preservation & Context
334+
335+
**When unsure, leave the text in place and ask.** Subjective cleanup
336+
must never be a reason to remove load-bearing rationale.
337+
338+
- **Preserve the "Why":** You MUST NOT delete comments that document
339+
invariants, protocol constraints, platform quirks, security
340+
boundaries, and upstream workarounds.
341+
- **Evidence is Immune:** Preserve exact counts, dates, and SHAs when
342+
they serve as evidence in benchmark results, release notes, stack
343+
traces, or lockfiles.
344+
- **Behavior Over Inventory:** A useful description explains what
345+
changed for the *system or user*; it does not provide an inventory
346+
of files or functions the diff already shows.
347+
348+
### The Published-Release Test
300349

301350
Long-running branches accumulate tactical decisions — renames,
302-
refactors, attempts-then-reverts, intermediate states. Commit messages
303-
and the diff hold *what changed* and *why*. Do not restate either in
304-
artifacts the downstream reader holds: code, docstrings, README,
305-
CHANGES, PR descriptions, release notes, migration guides.
306-
307-
When deciding what counts as branch-internal, use trunk or the parent
308-
branch as the baseline — not intermediate states inside the current
309-
branch.
310-
311-
**The Published-Release Test**
312-
313-
Before adding rename history, "previously" / "formerly" / "no longer
314-
X" phrasing, "removed" / "moved" / "refactored" / "fixed" diff
315-
paraphrases, or `### Fixes` entries to a user-facing surface, ask:
351+
refactors, attempts-then-reverts. When deciding what counts as
352+
branch-internal, use trunk or the parent branch as the baseline — not
353+
intermediate states inside the current branch. Ask:
316354

317355
> Did users of the most recently published release ever experience
318356
> this old name, old behavior, or bug?
319357
320-
If the answer is no, it is branch-internal narrative. Move it to the
321-
commit message and describe only the current state in the artifact.
322-
323-
**Keep in shipped artifacts**
358+
If the answer is **no**, it is branch-internal narrative. Move it to
359+
the commit message and describe only the final state in the artifact.
324360

361+
**Keep in shipped artifacts:**
325362
- Deprecations and migration guides for symbols that actually shipped.
326363
- `### Fixes` entries for bugs that affected users of a published
327364
release.
328-
- Comments explaining *why the current code looks this way*
329-
invariants, platform quirks, upstream bug workarounds — that make
330-
sense to a reader who never saw the previous version.
331-
332-
**Default**: when in doubt, keep the artifact clean and put the story
333-
in the commit.
365+
- Comments explaining *why the current code looks this way*
366+
(invariants, platform quirks) that make sense to a reader who never
367+
saw the previous version.
334368

335369
### Cleanup in Hindsight
336370

337-
When applying this rule retroactively from inside a feature branch,
371+
When applying these rules retroactively from inside a feature branch,
338372
first establish scope by diffing against the parent branch (or trunk)
339373
to identify which commits this branch actually introduced. Then:
340374

341-
- **Commits introduced in this branch** — prompt the user with two
342-
options: `fixup!` commits with `git rebase --autosquash` to address
343-
each causal commit at its source, or a single cleanup commit at
344-
branch tip. User chooses.
345-
- **Commits already in trunk or a parent branch** — default to
346-
leaving them alone. Do not raise them as cleanup candidates; act
347-
only on explicit user instruction. If the user opts in, fold the
348-
cleanup into a single commit at branch tip and do not rewrite trunk
349-
or parent-branch history.
350-
- **Scope guard** — if cleaning in-branch bleed would touch a
351-
colleague's in-flight work or expand the branch beyond its stated
352-
goal, default to staying in lane: protect the project's current
353-
goal, leave prior bleed alone, and don't introduce new bleed in the
354-
current change.
375+
- **In-branch commits:** Prompt the user with two options: `fixup!`
376+
commits with `git rebase --autosquash` to address each causal commit
377+
at its source, or a single cleanup commit at branch tip.
378+
- **Trunk/Parent commits:** Default to leaving them alone. Act only on
379+
explicit user instruction. If the user opts in, fold the cleanup
380+
into a single commit at branch tip; do not rewrite shared history.
381+
- **Scope guard:** If cleaning prior slop would touch a colleague's
382+
work or expand the branch beyond its stated goal, stay in lane:
383+
protect the current goal and leave prior slop alone.
384+

0 commit comments

Comments
 (0)