Skip to content

Commit 73edcbd

Browse files
committed
docs(agents): simplify review scope and follow-up rounds
1 parent f633525 commit 73edcbd

2 files changed

Lines changed: 19 additions & 19 deletions

File tree

‎docs/agents/pull-requests.md‎

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -22,15 +22,14 @@ Do not wait for CI merely to report publication. Do not claim skipped integratio
2222

2323
## Self-review
2424

25-
Give a fresh reviewer the worktree, head, base ref, and this prompt. Do not supply an implementation summary.
26-
27-
> You did not write this change. Assume it has bugs and find them. Read AGENTS.md and docs/agents/review.md.
28-
> Read the full diff against the merge-base and untracked files. Open callers and siblings for each hunk.
29-
> Keep this checkout read-only. Run experiments only in a separate disposable checkout.
30-
> Report only findings with a triggering scenario: file:line, severity, what breaks, and the fix. If none, say so.
25+
Commit the change. Give an independent reviewer the worktree, merge-base SHA, head SHA, and task requirements.
26+
Keep the first review free of implementation summaries.
27+
Review that SHA range using AGENTS.md and [review guidance](review.md).
3128

29+
In later rounds, provide the previously reviewed SHA, findings, and dispositions. Review changes since that SHA and their affected interactions.
30+
After a rebase, compare the old and new branch ranges with `git range-diff`.
3231
Fix accepted findings and rerun affected checks. Record a reason for rejected findings.
33-
If no independent reviewer is available, reread the full diff cold and report that limitation.
32+
If no independent reviewer is available, review the diff yourself and report that limitation.
3433
An independent reviewer is required at the growth thresholds in [review guidance](review.md).
3534

3635
## Scope and commits

‎docs/agents/review.md‎

Lines changed: 13 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -4,18 +4,20 @@ Keep reviewed source read-only. Run checks in an isolated checkout if they can m
44

55
## Reviewing
66

7-
- Read linked dependencies and relevant ADRs. Resolve prerequisite conflicts first. Update or supersede conflicting decisions explicitly.
8-
- Trace routing and surface changes through daemon and backend. Helper tests bypassing the router do not prove dispatch.
9-
Check affected CLI, Node, daemon, MCP, help, and docs surfaces.
10-
- Trace typed errors from producers through normalization, transport, and sibling consumers. Do not replace lost reason codes with text matching.
11-
- Classify interaction paths in `packages/contracts/src/interaction-guarantees.ts`. Verify each claim against native code.
7+
Review for concrete regressions. Follow callers and siblings as needed to verify changed behavior.
8+
Apply each check only when the change affects its subject. Reopen a resolved concern only when new evidence changes the conclusion.
9+
10+
- Dependencies and ADRs: resolve prerequisite conflicts. Update or supersede conflicting decisions explicitly.
11+
- Routing and surfaces: trace through daemon and backend to affected entrypoints. Helper tests bypassing the router do not prove dispatch.
12+
- Typed errors: follow reasons from producers through normalization, transport, and consumers. Never replace them with text matching.
13+
- Interaction paths: verify `packages/contracts/src/interaction-guarantees.ts` claims against native code.
1214
Error-path delegation does not prove success-path parity. Prove both paths reachable before comparing performance.
13-
- A platform-family claim covers every backend, including Appium and ADB, or names the covered backends.
14-
- Keep snapshot-wide metadata at response level. Append warnings through the shared builder; never replace prior warnings.
15-
Check compact defaults, bounded arrays, and artifact paths for large evidence.
16-
- Before retaining compatibility, run `git tag --contains <commit>`. Unreleased shapes have no external compatibility obligation.
17-
- Require each new test to detect a credible production failure. Test doubles must fail at the same seam as production.
18-
- Find dead code, redundant guards, casts, narrating comments, and competing owners. Fix the owning rule, not only named sites.
15+
- Platform-family claims: cover every backend, including Appium and ADB, or name the covered backends.
16+
- Response shape: keep snapshot-wide metadata at response level. Append warnings through the shared builder.
17+
Preserve compact defaults, bounded arrays, and artifact paths for large evidence.
18+
- Retained compatibility: run `git tag --contains <commit>`. Unreleased shapes have no external compatibility obligation.
19+
- New tests: each must detect a credible production failure. Test doubles must fail at the same seam as production.
20+
- Changed code: flag dead code, redundant guards, casts, narrating comments, and competing owners.
1921

2022
Use CI Size evidence. At about 700 net production lines or 3 kB npm growth, require an independent reviewer to assess a smaller design.
2123
Also assess any new abstraction, dependency, seam, or ownership rule. Weigh gross churn for moves. Explain justified growth.
@@ -25,4 +27,3 @@ Also assess any new abstraction, dependency, seam, or ownership rule. Weigh gros
2527
Report only triggering scenarios: `file:line`, severity, what breaks, and the fix.
2628
If none, say so. Reject incorrect findings with evidence.
2729
Prove claims such as "one reader", "pure move", or "no shim left" with search or `git diff -M90%`.
28-
Encode repeated findings as types, structure, checks, or tests. Remove prose reminders once enforced.

0 commit comments

Comments
 (0)