Thread decomposition and PR-size discipline through the handbook - #124
Open
kalambet wants to merge 1 commit into
Open
Thread decomposition and PR-size discipline through the handbook#124kalambet wants to merge 1 commit into
kalambet wants to merge 1 commit into
Conversation
Follow-up to the previous commit, which added workflows/work-decomposition.md, the skill's Decompose phase, and gate 10. This wires the existing pages into them. No new rules — every change here points at content that already landed. - pr-authoring: "one issue, one PR" added to the small-focused-self-contained list, plus a "when a PR has to be bigger" section (stop before opening it, propose the split, record the approval in the description, agents never self-approve). States why the standard is reviewability rather than a line count, and narrows the rename/generated-code exemption to scope-width only. Two anti-patterns added. - code-review: size is now the first thing a reviewer checks, with guidance for handling an oversized PR in both reviewer modes. "Collapsed decomposition" added as a re-plan trigger — the most common way an agent produces an unreviewable diff while staying technically in scope. - repo-and-ci-setup: `epic` label, a work-tracking subsection covering milestones, and a note that Linear/Jira map the same three levels. - agent-era-invariants 1: notes that scope discipline alone does not guarantee reviewability, and points at decomposition and gate 10. - The pr-author and code-review skills mirror their source pages, per the existing source: metadata contract. llms.txt, README, and AGENTS indexes updated to match. The invariants entry read "Eight" while nine existed; corrected alongside. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
kalambet
force-pushed
the
peter/work-decomposition-references
branch
from
August 14, 2026 13:38
084a100 to
7431919
Compare
Deploying engineering-handbook with
|
| Latest commit: |
7431919
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://84d02913.engineering-handbook-8f2.pages.dev |
| Branch Preview URL: | https://peter-work-decomposition-ref.engineering-handbook-8f2.pages.dev |
dhyaniarun1993
approved these changes
Aug 14, 2026
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
Follow-up to the previous commit, which added workflows/work-decomposition.md, the skill's Decompose phase, and gate 10. This wires the existing pages into them. No new rules — every change here points at content that already landed.
pr-authoring: "one issue, one PR" added to the small-focused-self-contained list, plus a "when a PR has to be bigger" section (stop before opening it, propose the split, record the approval in the description, agents never self-approve). States why the standard is reviewability rather than a line count, and narrows the rename/generated-code exemption to scope-width only. Two anti-patterns added.
code-review: size is now the first thing a reviewer checks, with guidance for handling an oversized PR in both reviewer modes. "Collapsed decomposition" added as a re-plan trigger — the most common way an agent produces an unreviewable diff while staying technically in scope.
repo-and-ci-setup:
epiclabel, a work-tracking subsection covering milestones, and a note that Linear/Jira map the same three levels.agent-era-invariants 1: notes that scope discipline alone does not guarantee reviewability, and points at decomposition and gate 10.
The pr-author and code-review skills mirror their source pages, per the existing source: metadata contract.
llms.txt, README, and AGENTS indexes updated to match. The invariants entry read "Eight" while nine existed; corrected alongside.