Thread decomposition and PR-size discipline through the handbook - #124
Merged
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: |
12ccf4e
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://bd4a2394.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
…n CI A SKILL.md `description` over 1024 characters makes the skill fail to load — it goes silently missing rather than loudly broken. Adding the work- decomposition triggers pushed chainsafe-research-plan-implement from 1006 to 1211 characters, which disables the skill this PR was extending. Descriptions trimmed to fit (all trigger coverage retained; the budget came from compressed prose and redundant near-synonym triggers): chainsafe-research-plan-implement 1211 -> 964 chainsafe-zig-architect 1130 -> 1000 chainsafe-zig-developer 1128 -> 977 chainsafe-zig-reviewer 1059 -> 1003 The three zig skills were already over the limit on main; they are fixed here because the new gate would otherwise fail on main immediately. Enforcement: - scripts/check-skill-descriptions.sh — counts characters, not bytes (the descriptions are full of em-dashes; a byte count over-reports by ~40%). Follows check-skills-sync.sh conventions. - Wired into .github/workflows/skills-sync.yml. - AGENTS.md and workflows/skill-description-tuning.md state the limit as an authoring constraint. The tuning loop optimizes for triggering accuracy and has no notion of length, so it will return an over-limit best_description; appending triggers by hand to an already-long field is the other way to blow the limit. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ABTxxnA5MPevGBWVTQhi2i
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.