Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

docs: flag doc sentences that only announce a fixed edge case (#4283)

Worktrunk Bot69d02a03a7f6
diff --git a/.claude/skills/running-tend/references/review-pr.md b/.claude/skills/running-tend/references/review-pr.md
index f44786395..477a5aa46 100644
--- a/.claude/skills/running-tend/references/review-pr.md
+++ b/.claude/skills/running-tend/references/review-pr.md
@@ -63,6 +63,15 @@ When a PR changes behavior, check that related documentation still matches:
- Do inline TOML comments in config examples match the actual behavior?
- If a new feature was added, does the relevant help text mention it?
+**Documentation cruft:**
+
+LLM-generated PRs tend to add doc sentences that teach a reader nothing: a note
+that the edge case a fix covers now works, or a restatement of what the
+surrounding text already implies. For each added doc sentence, ask what a reader
+learns that they wouldn't already assume, and how many readers need it. When the
+answer is nothing, ask for its removal in the review rather than approving past
+it.
+
**Duplication search patterns (Rust-specific):**
```bash
diff --git a/AGENTS.md b/AGENTS.md
index 4a4bb558a..e60ea0511 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -28,6 +28,8 @@ Each worktree maps to one branch. Worktree arguments resolve branch first throug
Behavior changes require documentation updates. src/cli/mod.rs is primary for command help and generated command pages; docs/AGENTS.md explains sync. Check that --help matches behavior. Run cargo test --test integration test_docs_are_in_sync, then refresh help snapshots when help text changes.
+Docs describe behavior for a user, not the history of a fix. A fix that makes a feature work the way a reader already assumed needs no new doc sentence; do not add lines announcing that an edge case now works. LLM-generated changes add these often, so cut them in review.
+
## Plugin Layout
The loader paths, generated skills mirror, and cross-tool hook requirements are in plugins/worktrunk/AGENTS.md.