Skip to content

From RFC to plan to epics

Simone Baracchi edited this page Nov 12, 2026 · 4 revisions

From RFC to plan to epics

This page summarizes the planning process added in PR #3524. If this page and the skill files differ, the skill files are the authority. PR #3524 is not merged yet, so the links to its files work only once it lands on develop.

What this is for

An RFC says what to build. Before code starts, the team turns it into a plan, then turns each epic into an epic document when that epic starts. The repository ships this process as two agent skills, rfc-to-epic-plan and epic-breakdown, with two checker scripts. A person breaking an epic down by hand follows the same skill.

The three levels

Level File Owns
RFC docs/internals/rfcs/rfc-<n>-<slug>.md what to build
Plan docs/internals/planning/rfc-<n>-<slug>-plan.md epics, estimates, dependencies, tracks
Epic document docs/internals/planning/rfc-<n>-<slug>-epic<k>.md one epic's requirements and subtasks

Conventions for both documents:

  • Epic and subtask, nothing else. Never task, ticket, story, step, phase, stage, milestone, work package or work item. A subtask id is <epic>.<n>: write subtask 4.3 or T4.3, never E4-3, 4-3 or T3.
  • A track (A, B or C) is one line of work through the epics; a synchronization point (S1, S2, ...) is where the team converges. v1 is the component that exists today, v2 the one the RFC describes.
  • Decisions, not progress. No status, checkboxes or "TBD" placeholders. A document changes, through a pull request, only when a decision does.
  • Graphs are Mermaid, never ASCII art.

The lifecycle, and where the truth lives

Documents decide; issues track. A document changes only through a pull request, so once the work is under way its current figures live on GitHub, where they can change without one. This section is newer than the skills: until they catch up, it wins on when issues are created and where estimates and dependencies are read.

  1. RFC. Says what to build. It carries no estimates and no dependencies.
  2. Roadmap epic. An issue labeled roadmap and rfc-<n>-<slug>, on the release's milestone. From here the RFC appears on the burn-up dashboard, with no scope yet.
  3. Plan. Splits the RFC into epics, with a first estimate of each and the dependencies between them. Reviewed and approved as a pull request.
  4. Plan merged. The epic issues are created as sub-issues of the roadmap epic, each with its Estimate and its dependencies on other epics as GitHub "blocked by" links. The plan is now the sum of its epics: the dashboard shows its estimate and each epic.
  5. Epic document. Breaks epic k down into subtasks, with their estimates and dependencies, when the epic is about to start. Reviewed and approved as a pull request.
  6. Epic document merged. The subtask issues are created as sub-issues of the epic issue, each with its Estimate and its dependencies on other subtasks as "blocked by" links. The epic is now the sum of its subtasks, and the plan's figure for it starts to drift: expected, and never corrected in the plan.
  7. During the work. Subtasks are added, split or withdrawn, and dependencies and blockers change, on the issues alone. The epic's own Estimate then drifts from the sum of its subtasks, and the documents from both; none of them needs a pull request to catch up. A pull request names each subtask issue it finishes with Closes #N, which is how the dashboard credits it.

Which source wins

Each estimate and each dependency is read from the most specific source that states it:

  1. The subtask issue: its Estimate and its "blocked by" links.
  2. The epic issue: its Estimate and its "blocked by" links; where the issue has none, the epic document's estimate line and Depends on.
  3. The plan: its estimate line and the Blocks column of its epics table, in the markdown only.
  4. The RFC defines neither, so it is never read for them.

So an epic with subtask issues counts as the sum of their estimates; one without counts at its own Estimate, else at its document's or the plan's figure. To change an estimate once its issue exists, change the issue. A later revision of the document does not override it: the sync after a revision fills only an Estimate that is empty, and reports a figure that differs.

Dependencies an issue does not state are read from the level below it: no "blocked by" links means "not stated here", not "depends on nothing", while a document line saying none means none. The first subtask of each epic waits on its own blockers and on everything its epic waits on. That wait is implied: it is not linked on GitHub, but the dashboard, and anyone planning the work, counts it. A subtask with nothing stated anywhere waits on what its epic waits on.

Sync points (S1, S2, …, defined in the plan's §3) are named points where the team converges: a set of epics or subtasks done, or an agreement outside the repository. A document may name one in a Depends on line for brevity, or for reasons beyond dependencies. GitHub has none, so on the issues each becomes links to what it stands for: the subtask issues it lists, or the epic issues of the epics it waits on. One with nothing in the repository to link (an agreement with another team) stays a **Waits on:** line in the issue's body.

Making a plan

Inputs

Planning starts only when these are settled: the RFC; whether it replaces an existing component, and if so the transition policy (offline switch refused while v1 holds uncommitted state, fresh installs only, a migration tool, or other); how far each related RFC is in scope (fully, only the parts this RFC cannot work without, or constraints only); and the program that stages the work (or a note that there is none). The plan's header states every default used.

The epics

  • E1 Interfaces: the public surface only (exact signatures, the error set), with stub bodies.
  • E2 Red e2e suite and test foundations: e2e tests for every use case that can be named, run by CI from the first pull request; each red test is a known failure in its suite's known.yaml. Shared fakes go here too.
  • Middle epics (E3 onward): cut along the RFC's own seams (on-disk format, index, recovery); each builds and unit-tests on its own.
  • Integration: wire v2 in as the program stages it.
  • E2E green: empty known.yaml; add soak tests and benchmarks.
  • Dashboards: optional, only if the RFC or the requester asks.

Start from N = round(RFC line count / 400) middle epics, clamped to 3..8: a sanity check, not a quota. If the real count differs by more than one, §2 says why. Every middle epic belongs to one of exactly three tracks, A, B and C, which have no owner.

Estimates

The plan estimates epics, not subtasks. The unit is man-days of one engineer, in multiples of 0.25: effort, not calendar time, including tests, doc comments and review fixes. Numbers are plain: no ~, no ranges, no comma.

Man-days Typical work
0.25 a comment, a one-line default
0.5 a type or constant set with tests; a config key
1 a small codec, or one well-specified function with edge-case tests
2 a component with a few interacting rules
3 concurrency, crash safety or on-disk ordering in one component
5 a subsystem's core algorithm under race or crash testing; the ceiling for one subtask

Weight upward for durability, lock ordering and per-OS code; downward for pure declarations.

Each epic in §5 opens with exactly one estimate line, and the total sits under the §2 table:

**Epic 4 estimate: 11 subtasks, 17.5 man-days.**
**Epic 11 estimate: planned after S4a.**
**Plan estimate: 108 subtasks, 172 man-days, not counting epic 11.**

"Planned after Sx" replaces the estimate of an epic that waits on an interface someone else owns, and the plan estimate line names that epic.

Sections

Section numbers are fixed so plans can be compared:

  1. Introduction, ending with 1.5, the general rules
  2. Epics at a glance: # | Epic | Content | Subtasks | Man-days | Track | Blocks, a total row, the plan estimate line
  3. Dependencies: a graph, what each synchronization point (🔀) unblocks, which epic blocks (⛔) which and why, each track's path
  4. Directory layout proposed for epic 1
  5. The epics in detail, one ### Epic <n> heading each
  6. Risks and open points, each undecided one with its options and pending #NNN
  7. RFC coverage: which epic owns each RFC section

§1.5 holds twelve general rules, for example "v2 ignores v1" and "a test must be able to fail". Each epic document copies them word for word, so they never mention the plan.

Breaking an epic down

An epic is broken down when it is about to start. The result is a document, not code. Never overwrite an existing epic document without asking: someone may be working from it.

Requirements

Every obligation the RFC places on the epic appears exactly once, numbered R1 to Rn. Candidates are RFC 2119 key words in either case, bold lead sentences, prose invariants (never, always) and numbers such as cost bounds and limits; each is judged on what its sentence says.

| # | Requirement | Kind | Source | Subtasks |

Kind is MUST, MUST NOT, SHOULD (adopted), invariant, bound or test row. Numbers are never reused or renumbered; a dropped requirement stays, marked "withdrawn" with the reason. Every requirement needs a subtask and a test that can fail; every subtask covers a requirement or says why not.

Subtasks

  • Slice vertically where possible: one operation end to end with its tests, not all types first.
  • Size: one engineer, ideally up to 5 man-days: a ceiling, not a target. A subtask over 5 says why it cannot be split.
  • Order: dependencies first, high-risk work early.
  • Stable ids: keep the plan's ids, split with a letter suffix (T4.3a, T4.3b), and never reuse or drop an id a pull request has cited.

Each subtask has a ### T<k>.<n> <title> heading, one estimate line (**Subtask T4.2 estimate: 2.5 man-days.**), then Covers (requirements), Deliverables, Acceptance criteria, Tests (each with the bug it catches) and how it meets the rules.

Sections

The header carries Sources, Track, the **Epic <k> estimate: ...** line, Depends on and Blocks. Then: 1 Goal, 2 General rules (copied), 3 Requirements, 4 Decisions, 5 Target tree, 6 Subtasks, 7 Order of work, 8 Suggested pull requests, 9 Open points. The document stands alone and never refers to the plan. Its estimate supersedes the plan's figure for that epic.

Suggested pull requests

A subtask is not a pull request. §8 only suggests a grouping, with each pull request ideally up to 15 man-days; the owner may follow it, regroup, or open one per subtask.

| PR | Subtasks | Man-days | After | Why together |

Each pull request builds, passes its tests and leaves nothing half-wired. Its description names the RFC and each subtask it delivers (RFC 1, T4.1, T4.2).

Issues

Issues link to the documents without copying them. Epic issues are created when the plan merges, subtask issues when the epic document merges (see the lifecycle above).

  • The epic issue is labeled epic, rfc-<n>-<slug> and rfc-<n>-epic-<k>.
  • Subtask issues wait until the epic document has merged. Each is a sub-issue of the epic issue, with the last two labels only.
  • All join the project board; epic and subtask issues fill its Estimate field.
  • The release is the milestone of the RFC's roadmap epic, an issue labeled roadmap and rfc-<n>-<slug>. Epic issues and their subtask issues copy its milestone.

Checking a document

From the repository root:

awk -f .claude/skills/rfc-to-epic-plan/plan-check.awk <plan>
awk -f .claude/skills/epic-breakdown/epic-check.awk <epic-doc>

Each sums the estimate lines, so totals are never added by hand. Only a TOTAL line may print, matching the plan's estimate line and §2 total row, or the epic document's header line. Anything else is a defect: a malformed line (21,5, ~20, 0.3), a heading without exactly one estimate line, or a total that disagrees.

Check by hand: every in-scope RFC section has an owner, there are exactly three tracks, every requirement has a test, the suggested pull requests cover every subtask once, and nothing tracks progress.

Where the files are