Skip to content

docs: /deslop AGENTS.md without weakening its rules #921

Closed

Description

@mforce

Problem

AGENTS.md has accumulated dense incident history, repeated framing, long sentences, and prose that takes more work to parse than the rules themselves. The file is loaded into every agent session, so unclear wording costs both context and comprehension.

This is not a repeat of #413. That issue moved long rationale into decision records. This pass should improve the prose that remains without changing, weakening, or relocating any rule.

Scope

Run /deslop over AGENTS.md.

  • Remove AI-style filler, stock framing, repetition, and ornamental wording.
  • Split sentences that carry too many independent conditions.
  • Prefer direct rules and concrete failure modes over abstract shorthand.
  • Keep terminology consistent across sections.
  • Preserve every decision link, issue reference, command, identifier, exception, accepted risk, and enforcement boundary.
  • Keep each rule as one paragraph, as the file requires.

Acceptance criteria

  • Every section of AGENTS.md has been reviewed, not only recently changed text.
  • No rule, exception, accepted risk, command, link, or operational constraint changes meaning.
  • Repeated prose is removed only when the remaining text still states the full rule at its point of use.
  • Long or indirect sentences are rewritten in plain language where that improves comprehension.
  • The PR records the before-and-after word count and calls out any passage intentionally left unchanged because shortening it would weaken the rule.
  • Documentation links and commands referenced by the edited text still resolve or run.

Non-goals

  • Changing policy or architecture.
  • Moving rationale into new decision records.
  • Editing generated documentation or unrelated project docs.
  • Chasing a fixed word-count target at the cost of precision.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions