chained-pr

Files (1)

• SKILL.md

SKILL.md (first lines)

## When to Use

Use this skill when:

- A planned PR is likely to exceed **400 changed lines** (`additions + deletions`).
- An SDD tasks artifact forecasts `400-line budget risk: High` or `Chained PRs recommended: Yes`.
- A reviewer asks to split a PR for cognitive load, review fatigue, or burnout prevention.
- You need chained PRs, stacked PRs, or a feature branch with multiple reviewable slices.
- A change should be reviewed in roughly **60 minutes or less** per PR.

Do not use this skill for small fixes or single-purpose changes that fit comfortably under the review budget.

## Critical Rules

| Rule | Requirement |
|------|-------------|
| Review budget | **MUST split** when a PR exceeds **400 changed lines** (`additions + deletions`), unless it has maintainer-approved `size:exception` |
| Review time | Design each PR for an approximately **≤60-minute** human review |
| Review health | Optimize for sustainable maintainer attention, not just CI compliance |
| Start and finish | Every chained PR MUST state where it starts, where it ends, what came before, and what comes next |
| Autonomy | Every chained PR MUST be understandable and verifiable on its own |
| Scope | One deliverable work unit per PR; do not mix unrelated refactors, features, tests, or docs |
| Dependencies | State what each PR depends on and what follows next |
| Exceptions | Use `size:exception` only when a maintainer agrees the large diff is unavoidable |
| SDD handoff | If SDD forecasts a >400-line workload, honor `delivery_strategy`: ask, auto-chain, or require/record `size:exception` |
| Visual map | Every chained PR MUST include a dependency diagram that marks the current PR |
| Tracker PR | If the team chooses Feature Branch Chain, create a draft tracker PR that maps every child PR and stays draft/no-merge until final integration |
| Child PR base | In Feature Branch Chain, PR #1 targets the feature/tracker branch; every later child PR targets the immediate previous PR branch |
| Diff source of truth | If a child PR shows previous PR changes, its base is wrong; retarget/rebase until the diff contains only the current work unit |
| Strategy consistency | Once the user picks a chain strategy, follow it for the entire chain — do not mix stacked and feature branch patterns |

The goal is not bureaucracy. The goal is preventing reviewer burnout so maintainers can review with care instead of skimming exhausted. Big PRs create fatigue, hide defects, and slow merge velocity.

## Autonomy Requirements

Each chained PR must function as a complete review unit:

- **CI green**: checks pass for the PR branch in its intended base context.
- **Autonomous scope**: the PR has one clear deliverable outcome.
- **Reasonable rollback**: reverting this PR does not require reverting unrelated work.
- **Verification included**: tests, docs, or manual verification cover this unit.
- **Reviewable alone**: reviewers do not need to read future PRs to understand this one.

If a slice cannot meet these rules, split it differently. A chain is not a dumping ground for partial, unreviewable diffs.

## Choosing the Chain Strategy

When the workload exceeds 400 lines and chained PRs are needed, **ask the user** before proceeding:

```
This work exceeds the 400-line review budget. How do you want to split it?

1. Stacked PRs to main
  Each PR merges to main in order. Fast iteration, fix on the go.
  Best for: speed-first teams, startups, independent slices.

2. Feature Branch Chain (with tracker)
  Child PRs review against their immediate parent branch; the tracker branch accumulates the final feature and is the only branch that merges to main.
  Best for: rollback control, integration testing before main, coordinated releases.

3. size:exception
  Keep it as a single PR with maintainer approval.
  Best for: generated code, migrations, vendor diffs where splitting adds noise.
```

Cache the user's answer for the rest of the session. Do not ask again unless the user changes scope.

This is a **team decision**, not a technical one. Both strategies are valid — they reflect different priorities:

| | Stacked PRs to main | Feature Branch Chain |
|---|---|---|
| Speed | Each slice ships immediately | Waits until the chain is complete |
| Rollback | Revert individual PRs from main | Revert the whole feature branch |
| Risk | Partial features may land in main | Nothing lands until everything is ready |
| Fix flow | Fix on the go in main | Fix on the integration branch |
| Complexity | Simpler — rebase and retarget | Needs tracker PR, parent bases, and diff hygiene |
| Best for | Startups, fast-moving teams | Teams needing coordination and control |

## Chain Boundaries

Every PR in a chain needs explicit boundaries:

| Boundary | What to document |
|----------|------------------|
| Start | The branch, PR, or state this PR builds on |
| End | The finished unit this PR leaves behind |
| Before | Prior PRs reviewers can assume already exist |
| After | Follow-up PRs reviewers should ignore for now |
| Out of scope | Related work intentionally excluded from this review |

## Tracker PR Requirement

For any chain with more than two PRs, create a draft tracker PR before review starts. The tracker PR is not the review surface. It is the map.

It must include:

- every child PR in merge/review order,
- current status for each PR,
- one dependency diagram,
- explicit instruction not to review the aggregate diff,
- `size:exception` if the aggregate diff exceeds 400 changed lines,
- `no-merge` while the chain is incomplete.

## Diagram Requirement

Every child PR must show where it sits in the chain. Mark the current PR with `📍`.

```text
main
 └── #101 Foundation
   └── #102 Work-unit commits
      └── 📍 #103 This PR
        └── #104 Docs
           └── #105 Tracker
```

Pair the diagram with a status table:

| PR | Scope | Status |

From ntimpano/guild, Apache-2.0.

More from ntimpano/guild