docs(subagent-strategy): keep a standing roster across a multi-PR session - #53
Open
cristim wants to merge 1 commit into
Open
docs(subagent-strategy): keep a standing roster across a multi-PR session#53cristim wants to merge 1 commit into
cristim wants to merge 1 commit into
Conversation
…sion The existing reuse guidance optimises a single follow-up: same files, next round of the same loop, subsystem pooling. Over a long multi-PR session the compounding win is different and larger, and nothing described it. An agent that has worked several changes in one subsystem accumulates a model of how that subsystem fails, which no briefing transfers and no file cache substitutes for. Observed over a 30-PR session: an implementer applied a correction it had learned on one PR to the next PR's identical guard without being told, and a reviewer four PRs deep began finding defects in the fixes rather than in the original bugs. Adds four things the session showed were missing: - standing rosters, typically one reviewer and one implementer per active subsystem, routed by name for the session's duration - briefing the environment delta, not just the task delta. A long-lived agent's model of the world goes stale in ways its model of the code does not: the base moved, the CI contract changed, another agent holds a file, an earlier instruction was retracted. Every collision in that session traced to omitting one of these - a handoff contract that pins baselines in both directions. A handoff recording only the failing row of a mock/production divergence leads the successor to tighten until that row passes, swapping one wrong answer for another while staying green - permission to stop. Two agents flagged their own context depth and handed over cleanly; both framed it apologetically, and both were right, one because the remaining work was an open-ended fan-out where starting deep guarantees a mid-task handoff later Closes #51
Contributor
📝 WalkthroughWalkthroughThe strategy documentation adds guidance for maintaining named reviewer and implementer rosters across multiple pull requests. It defines subsystem routing, environmental delta briefings, independent roles, accumulated knowledge reuse, and structured handoffs. ChangesMulti-PR agent continuity
Estimated code review effort: 1 (Trivial) | ~5 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
🧹 Nitpick comments (1)
subagent-strategy.md (1)
65-74: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winMake environment and context status explicit handoff fields.
The guidance requires environment deltas in continuations and asks agents to report context-depth limits. The handoff contract does not explicitly require the successor report to include either item. Add mandatory fields for the environment delta and context status, including base-branch changes, CI contract changes, file ownership, retracted instructions, and the handoff trigger.
Proposed clarification
**Handoff contract.** When an agent winds down, its report must let a successor act without re-deriving: +- **Record the environment delta**, including base-branch, CI, ownership, and instruction changes. +- **Record context status**, including the context-depth limit or handoff trigger. - **Pin the baseline in both directions**, not only the failing one.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@subagent-strategy.md` around lines 65 - 74, Update the handoff contract in the “Handoff contract” section to require explicit fields for environment delta and context status. Ensure the environment field covers base-branch changes, CI contract changes, file ownership, and retracted instructions, while the context-status field records the handoff trigger, including context-depth limits or open-ended remaining work.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@subagent-strategy.md`:
- Around line 65-74: Update the handoff contract in the “Handoff contract”
section to require explicit fields for environment delta and context status.
Ensure the environment field covers base-branch changes, CI contract changes,
file ownership, and retracted instructions, while the context-status field
records the handoff trigger, including context-depth limits or open-ended
remaining work.
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.
Closes #51.
The existing reuse guidance optimises a single follow-up: same files, next round of the same loop, subsystem pooling. Over a long multi-PR session the compounding win is different, and larger. Nothing described it.
An agent that has worked several changes in one subsystem accumulates a model of how that subsystem fails, which no briefing transfers and no file cache substitutes for.
What prompted this
A session that shipped 30 PRs across an auth/permissions subsystem, a provider layer, and CI. Two things stood out:
len(x) == 0rather than anIsUnrestricted(x)helper, applied that unprompted to the next PRs identical guard. A fresh agent repeats the defect and costs another review round.What the section adds
Standing rosters — one reviewer and one implementer per active subsystem, routed by name for the session. Reviewer/implementer independence still binds; pooling is per subsystem, not per PR.
Environment deltas, not just task deltas. A long-lived agents model of the world goes stale in ways its model of the code does not: the base moved, the CI contract changed, another agent holds a file it is about to edit, an earlier instruction was retracted. Every collision in that session traced to omitting one of these, and they read as agent error when they are orchestration error.
A handoff contract. The most transferable part: pin the baseline in both directions. A handoff recording only the failing row of a mock/production divergence leads the successor to tighten until that row passes, swapping one wrong answer for another while staying green. Also: name the axis actually verified ("safe across packages; within-file scope unchecked", not "safe"), and state what was inspected and deliberately left alone, since a sweep reporting only its changes is indistinguishable from one that stopped early.
Permission to stop. Two agents flagged their own context depth and handed over cleanly. Both framed it apologetically; both were right. One declined an open-ended fan-out specifically because starting deep in context guarantees a mid-task handoff later, which is strictly worse than a clean one now.
Scope
Additive, nested under the existing "Reuse agents before spawning new ones" section. No existing guidance changed or contradicted.
Summary by CodeRabbit