docs: add review-proven failure-path & async-state rules to AGENTS.md - #7061
Open
jedwards27 wants to merge 1 commit into
Open
docs: add review-proven failure-path & async-state rules to AGENTS.md#7061jedwards27 wants to merge 1 commit into
jedwards27 wants to merge 1 commit into
Conversation
Distills recurring review findings from the last 25 PRs into six imperative rules in AGENTS.md, plus one client-consumption invariant in ARCHITECTURE.md §5. Docs only. Signed-off-by: Jude Edwards <judeedwards@squareup.com>
🔐 Codex Security Review
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Mining the last 25 PRs' review threads (45 substantive findings, 11 reviewed PRs, avg 4.8 review rounds each) shows 53% of findings are repeats of five clusters: swallowed failures, stale-async-state races, tests that don't bind the production seam, unbounded resources/retry loops, and non-atomic multi-step persistence. PR #6956 alone burned 4 rounds converging on one of these classes.
This PR distills those clusters into six imperative rules in AGENTS.md so agents apply them before writing code, adds one client-consumption invariant to ARCHITECTURE.md §5, and places the test-quality rule in TESTING.md (per the team decision that testing docs are the canonical guide for review standards), cross-referenced from AGENTS.md. Each rule cites the PRs where it was litigated. Raw mining data:
reviews.jsonl/comments.jsonl(review-mining artifacts, not committed).No code changes. CLAUDE.md is a symlink to AGENTS.md and picks this up automatically.
🤖 Drafted by Jude's agent from automated mining of this repo's last 25 PRs' review threads; every rule cites the PRs where it was litigated. Jude reviews and owns the result. Mining method + raw cluster data available on request.