Add work decomposition and the oversized-PR gate - #123
Merged
Conversation
The handbook said PRs should be small and that agents stay inside operator-named scope, but nothing made either enforceable. There was no model for breaking planned work into tracked units, and no gate for a change that outgrew what a reviewer can absorb. A PR is only as small as the issue behind it, and that issue had nowhere to come from. Two concepts, both new normative content: - Work decomposition. workflows/work-decomposition.md defines epic -> milestone -> bite-sized issue by what each level guarantees: an epic is one recognizable outcome, a milestone leaves main releasable, an issue is closed by exactly one PR. Six tests for "bite-sized", and an explicit mapping from plan.md phases and tasks onto the tracker. The research-plan-implement skill gains a Decompose phase so the breakdown is produced and approved before implementation starts, plus two key rules. - Gate 10. Covers PRs that cannot be reviewed in one pass, close more than one issue, bundle concerns, or outgrow the approved plan slice. Cleared by proposing a split, or by an explicit operator approval recorded in the PR description. Agents never self-approve. The standard is deliberately reviewability, not a line count. Line thresholds are easy to satisfy and easy to game, so the bar is the handbook's existing ~10-minute one-reviewer-one-pass test. The rename/deletion/generated-code exemption is kept but narrowed to scope-width only: a large rename is fine, a rename plus a logic change is two PRs. llms.txt is updated in this commit per the same-PR index rule in mcp-and-llm-txt.md. That also corrects the gate count, which read "Eight" while nine already existed. Cross-references from pr-authoring, code-review, repo-and-ci-setup, the invariants, and the mirror skills follow in the next PR of this stack. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
dhyaniarun1993
left a comment
dhyaniarun1993
left a comment
Member
There was a problem hiding this comment.
We should add this to the reviewer skills as well
Member
Looks like this is covered in #124 |
dhyaniarun1993
approved these changes
Aug 14, 2026
Member
Author
|
@dhyaniarun1993 yes, I wanted to split the PRs in two so they are more of a bite-sized :) |
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
2 participants
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.
Description
Adds two concepts the handbook was missing: a model for decomposing planned work into tracked units, and a gate for changes that outgrow what a reviewer can absorb.
1 of 2 in a stack. This PR carries the new normative content. [PR 2] threads cross-references from the existing pages into it and asserts nothing new. Merge this one first.
What changed
workflows/work-decomposition.md. Defines epic → milestone → bite-sized issue by what each level guarantees: an epic is one recognizable outcome carrying the plan artifact, a milestone leavesmainreleasable, an issue is closed by exactly one PR. Gives six tests for "bite-sized" and mapsplan.mdphases and tasks onto the tracker.chainsafe-research-plan-implementskill. Pipeline becomes research → plan → annotate → decompose → implement. New Phase 3b produces the breakdown insideplan.mdfor operator approval; Phase 4 gains the one-issue-one-PR rule; two key rules added; description gains decomposition triggers.gates-and-escalation.md. Covers PRs that cannot be reviewed in one pass, close more than one issue, bundle concerns, or outgrow the approved plan slice. Cleared by proposing a split or by an explicit operator approval recorded in the PR description. Agents never self-approve. Escalation-matrix row added.llms.txt— new page entry, updated workflow-skill description, gate count corrected.