A general-purpose reference for structuring any feature, migration, or refactor using the tranche model. Drop this file into any project. Hand it to an agent or a new team member at the start of planning.
Every change ships in tranches. Every tranche produces a working, deployable system — never a broken in-between state.
A tranche is not a sprint. It is a vertical slice: after it merges and tags, the system is fully functional at a new capability level. No "we'll fix it in T2" for T1 regressions. Each tranche must pass all prior acceptance criteria before the next one begins.
Each feature or migration lives in its own self-contained folder:
roadmap/
<feature-slug>/
README.md ← overview, motivation, architecture, tranche index
t1.md
t2.md
t3.md
...
The folder name is the scope boundary. Everything needed to understand and implement the feature lives inside it.
The overview file. A person or agent reading only this file should understand what, why, and how — and know which tranche to start on.
# <Feature or Migration Title>
One paragraph: the problem this feature solves, or what is being replaced and why.
## Why
The motivation. Include the specific pain point or limitation that makes this necessary.
Be concrete — name the exact bug, API limitation, UX failure, or scaling constraint.
## Options Considered (if applicable)
| Option | Maintainer | Status | Verdict |
| :----- | :--------- | :----- | :------ |
| Option A | Team / Org | Active | ✅ Chosen |
| Option B | Community | Abandoned | ❌ Rejected |
> ⚠️ Include non-obvious gotchas, breaking changes, or import pattern differences here.
## Architecture
How the new system fits into the existing codebase.
What the public interface looks like (name the functions, modules, APIs that stay stable).
What the boundaries are — what does NOT change as a result of this work.
## Dependencies
```bash
# Remove (if replacing something)
<package-manager> remove <old-dependency>
# Add at T1
<package-manager> add <new-dependency>
# Add later (only if needed at a specific tranche)
# T3: <package-manager> add <optional-dependency>| File | Scope | Status |
|---|---|---|
| t1.md | Short scope description | planned |
| t2.md | Short scope description | planned |
| t3.md | Short scope description | planned |
Bullet list of non-obvious facts a developer or agent needs before touching the code:
- Naming traps, import quirks, version-specific gotchas
- Shared modules or interfaces that must not break
- Known acceptable bugs that should not be "fixed" as part of this work
- Any environment-specific behaviour (staging vs. prod, platform differences)
How to run the system locally or in CI to verify the work:
# Example — adapt to your stack
<start command>
<build command>
<test command>
---
## Sub-Tranche File — `tN.md`
One file per sub-tranche. Naming: `t1.md`, `t2.md`, etc. (lowercase, no prefix slug — the folder provides context). Aim for 3–7 tranches per feature. Split if a single tranche would take more than one working day.
```markdown
# T<N> — <Short Tranche Title>
**Status:** `planned` | `in-progress` | `done`
## Goal
What is true after this tranche that was not true before.
2–3 sentences. Focus on observable, user-facing or system-level outcomes — not a task list.
## Steps
### 1. <First major step>
Prose description of what to do. Include enough context that implementation does not require guessing.
```bash
# Shell commands if needed
// Key code or config to write or modify.
// Include the full relevant block, not just a diff hint.
// Implementers work directly from these blocks.
...
What to manually check or run before marking done. Include specific test cases and known failure modes.
All must be green before the next tranche begins.
- Specific, observable behaviour 1
- Specific, observable behaviour 2
- No regression:
- No regression:
---
## Status Values
Use exactly these values — nothing else:
| Value | Meaning |
| :---- | :------ |
| `planned` | Not started. Approved for implementation. |
| `in-progress` | Active work in a branch. |
| `done` | Merged. |
| `blocked` | Waiting on an external dependency or decision. Add a note explaining what and who. |
| `deferred` | Descoped. Moved to a future cycle. |
---
## Naming Conventions
| Thing | Convention | Example |
| :---- | :--------- | :------ |
| Feature folder | `<noun>` or `<noun>-<verb>` (lowercase, hyphenated) | `image-upload`, `export`, `dark-mode` |
| Migration folder | `migrate-to-<target>` or `migrate-<detail>` | `migrate-to-postgres`, `migrate-auth` |
| Sub-tranche file | `t<n>.md` (lowercase, no slug — folder provides context) | `t1.md`, `t4.md` |
---
## Dependency Rule
**A sub-tranche may not begin until all prior tranches in the same sequence are `done`.**
Feature folders can be worked on in parallel with each other, provided any shared prerequisites are complete.
Feature folders (can run in parallel once prerequisites are done): image-upload/ t1 → t2 → t3 (sequential within the folder)
export/ (can start in parallel with image-upload) t1 → t2
migrate-auth/ (blocked until image-upload t2 is done — example dependency) t1 → t2 → t3
If a feature depends on another feature, note it explicitly in the `README.md` under a `## Prerequisites` section.
---
## Rules for Implementers (Human or Agent)
1. **Read the feature `README.md` first** — never start a sub-tranche without reading the overview.
2. **Implement exactly one tranche at a time** — do not combine or skip tranches.
3. **Pass all acceptance criteria** before marking `done`.
4. **Stay within scope** — do not modify files outside the tranche's stated scope. No opportunistic refactors.
5. **Update status** from `planned` → `in-progress` at start, and `in-progress` → `done` on completion.
6. **Check for regressions** — if a shared module was touched, re-verify the acceptance criteria from all prior tranches that depend on it.
---
## Quick-Start Checklist (new feature or migration)
- [ ] Create `roadmap/<feature-slug>/` folder
- [ ] Write `README.md` using the template above
- [ ] Decide the number of tranches (aim for 3–7; if a tranche would take more than 1 day, split it)
- [ ] Write one `tN.md` per tranche — at minimum T1; write all if scope is already clear
- [ ] Add the feature to the master roadmap index with a link and one-line description
- [ ] Set all statuses to `planned`
- [ ] Note any prerequisite features or tranches that must be `done` first