| name | tbd |
| description | Use when the user wants to plan or implement a feature using trunk-based development (TBD) with short-lived feature branches and stacked PRs. Guides decomposition of features into an ordered PR stack where each PR is independently green. Triggers on: trunk-based development, TBD, feature branch, stacked PRs, plan feature with TBD, PR stack.
|
Trunk-Based Development Skill
Plan and implement features as a stack of short-lived, independently-green
pull requests that integrate into trunk frequently.
Non-Negotiables
- Trunk is always deployable — no PR merges if it breaks the build, fails
tests, or regresses UX
- Each PR is independently green — builds pass, tests pass, UX is intact,
even if the feature is not yet fully visible to users
- Plan the stack before writing code — map every PR in the stack upfront;
do not discover dependencies mid-implementation
The Green Gate Rule
Every PR in a stack must satisfy all three independently:
- Build: compiles/lints without errors
- Tests: all existing tests pass; new behaviour has tests
- UX: no visible regression — use feature flags to hide incomplete work
If any gate fails, the PR does not merge, and dependent PRs do not merge either.
Decomposition Strategy
Break a feature into layers, ordered from lowest dependency to highest:
1. Infrastructure / schema — migrations, new tables, config, env vars
2. Data / API layer — service methods, API endpoints, data access
3. Business logic — rules, validation, transformations
4. UI / presentation — components, pages, wiring
5. Integration / polish — end-to-end wiring, feature flag removal, cleanup
Rules for splitting:
- Each PR should change ~200 lines or fewer (excluding generated files)
- One logical concern per PR — reviewers should understand it without the rest
of the stack
- If a PR requires a change in a lower layer to be testable, split there first
- Prefer vertical slices (infra + logic + UI for one sub-feature) over
horizontal layers when the sub-feature is small enough to fit in one PR
Feature Flags
Use a feature flag when:
- The UI ships before the backend is complete
- A behaviour change would be visible to users before the stack is fully merged
- The feature needs a controlled rollout
Structure: wrap incomplete paths behind a flag from PR 1; remove the flag in
the final PR of the stack.
Planning Workflow
When a user requests a feature using TBD:
- Understand the full scope — ask clarifying questions until the feature
boundary is clear
- Identify layers — list the system components touched (DB, API, UI, etc.)
- Draft the stack — produce a numbered list of PRs with:
- A one-line description of what the PR does
- What it tests
- Whether it needs a feature flag
- Its dependency (which PR must merge first)
- Validate green-gate compliance — for each PR, confirm build + test + UX
are independently satisfiable
- Present the stack to the user for approval before writing any code
- Implement one PR at a time — start from PR 1 (lowest layer), get it
merged, then move to PR 2
VCS Workflow for a Stack
Each PR corresponds to a branch built on top of the previous one, not on trunk directly.
When working on a stack:
- Create each branch from the tip of the previous PR's branch, not from trunk
- Push each branch independently so it can be reviewed and merged on its own
- When a lower PR merges into trunk, rebase the remaining branches onto the updated trunk before continuing
- Keep your view of the full stack visible — know which branches are in flight and their order at all times
Stack Plan Template
Present this to the user when planning a feature:
Stack: <feature name>
PR 1 — <title>
Changes : <what files/systems>
Tests : <what is tested>
Gate : build ✓ / tests ✓ / UX ✓ (flag: none | <flag-name>)
PR 2 — <title>
Depends : PR 1
Changes : ...
Tests : ...
Gate : build ✓ / tests ✓ / UX ✓ (flag: none | <flag-name>)
...
PR N — remove feature flag / final wiring
Depends : PR N-1
Gate : build ✓ / tests ✓ / UX ✓ (flag: removed)
Anti-Patterns to Avoid
- One giant PR for the whole feature — impossible to review, high merge
conflict risk, violates TBD
- PRs that only pass tests when stacked — each PR must be green on its own
- Skipping the plan — starting implementation before the stack is mapped
leads to mid-stack redesigns
- Merging a red PR to unblock the next — this spreads the failure across
the stack; fix the gate failure first
- Feature flag sprawl — every flag must have a removal PR already planned
in the stack before the flag is introduced
