Repository navigation
Description
src/docs/labels-and-control-signals.md keeps being touched by pull requests that are open at the same time. In the last 7 days 6 distinct PRs changed it, 6 pairs of them were open concurrently, and 0 merge conflicts or rebase failures were blamed on it. Every concurrent pair is a rebase someone (or the merge train) has to redo, and a 2595-line file makes each of those rebases slower and riskier.
This is a document, so the split is by section: each top-level ## area becomes its own file under a directory named after this one, with a short index page that links them (the way docs/api-reference.md became docs/api-reference/<area>.md). Keep every heading anchor reachable from the index.
Evidence
| metric | value |
|---|---|
| window | 7 days |
| distinct PRs | 6 |
| concurrent PR pairs | 6 |
| conflicts attributed | 0 |
| lines | 2595 |
| kind | doc |
| score | 9.0 |
PRs in window: #15308, #15449, #15491, #15591, #15662, #15668
Sections
Blockers (hive:blockermarker)CategoriesConfig that changes label behaviorDecision glossaryDocumented inconsistencies and follow-upsFirst use: choose the controlHow labels reach agentsLabel axesLifecycle examplesMatching rulesNon-label equivalentsQuestion auto-closeReference tableRepo-card legend vocabularyStage labels (stage/NNN-*): the pipeline state machine
Split proposal
src/docs/labels-and-control-signals/README.md— index linking every sectionsrc/docs/labels-and-control-signals/blockers_hive_blocker_ma.md— section “Blockers (hive:blockermarker)”src/docs/labels-and-control-signals/categories.md— section “Categories”src/docs/labels-and-control-signals/config_that_changes_labe.md— section “Config that changes label behavior”src/docs/labels-and-control-signals/decision_glossary.md— section “Decision glossary” and the 11 remaining sections
Don't splinter
- At most 4 resulting files, each at least 150 lines; fewer is better.
- No behaviour change; the package, its exported API and every import path stay the same.
- Tests move with the code they cover; no new test helpers.
- One PR; land it when the file has no open PRs against it.
Filed by the hive's merge-hotspot advisor (GET /api/hotspots). It will not file another issue for this file while this one is open.
Activity
hivecommons-hive commentedon Oct 30, 2026
🔒 Claimed by agent
scanner(agent on hive hosted-available-oke-11-placeholder-r05x). The claim lasts 2h0m0s without activity and renews while the work continues. Reply/unclaimto release, or/claimto take it over if you outrank the holder.