Skip to content

Capability-Ladder Runbook

Operating runbook — instantiates Self-Hosted Bootstrap Construction

Lays out the ordered ladder of stages — what capability each rung must deliver, in what order, and at what budgeted cost — from the seed up to the self-hosted target.

A bootstrap needs a plan for the climb, not just a map of the dependencies. Capability-Ladder Runbook is that plan: an ordered ladder in which each rung is defined by the specific capability it must be able to hand upward, the rungs are sequenced so that each is buildable from the ones below it, and each carries a budget of the effort and resources it is expected to cost. Its defining move is expressing every stage as a capability contract — "rung 3 must be able to compile the standard library" — rather than as a list of tasks, so success at each rung is a testable property, not a checklist someone ticked. It is the forward-looking design document; it says where you are going and what each step must achieve, leaving the gating and rollback of the actual ascent to the promotion workflow.

Example

A platform team standing up a self-hosted Kubernetes cluster — one whose control plane ultimately runs as workloads on the very cluster it manages — writes the runbook first. The target state is stated plainly at the top: a fully self-hosted control plane, where the API server, scheduler, and controllers run as pods managed by the cluster itself, with no permanent external machine holding it up. Then the ladder is laid out — rung 0: a temporary bootstrap control plane (the kind kubeadm brings up from static manifests); rung 1: a working node and networking layer that rung 0 can schedule onto; rung 2: the control-plane components re-hosted as pods on that layer; rung 3: the bootstrap scaffold torn down so the cluster holds itself up — each rung annotated with the one capability it owes the next and a rough budget ("rung 2 ≈ two engineer-weeks, dominated by migrating etcd cleanly").

When work starts, the runbook is what keeps the effort from wandering. A tempting shortcut — leaving the external bootstrap control plane running permanently because the cluster is "basically up" — is visibly off the ladder, because rung 3's contract says the scaffold must be retired, not kept. The budgets, meanwhile, surface the real cost early: if rung 2 is already double its estimate, that is a signal to re-plan the climb, not to quietly keep leaning on the outside prop.

How it works

What distinguishes the runbook is that it is organized by capability owed upward, not by activity. Each rung specifies (a) the capability it must be able to provide to the rung above, (b) the rungs below it that must exist first, and © a budget for reaching it. That framing makes the ladder well-founded — every rung is reachable from lower ones — and makes "done" mean demonstrated capability, not tasks completed. It stops at the plan: it names the target and the contracts and costs, but it does not itself snapshot, gate, or roll back a stage. That execution belongs downstream.

Tuning parameters

  • Rung spacing — how much new capability each rung adds. Small rungs are safe and easy to verify but multiply the number of stages; large rungs move faster but risk a jump nothing below can actually support.
  • Contract tightness — how precisely each rung's required capability is specified. Tighter contracts make "ready" unambiguous; looser ones leave room to improvise but invite disputes about whether a rung is really done.
  • Budget granularity — a single top-line estimate versus per-rung budgets. Per-rung budgets localize overruns to a specific step but cost more to estimate and track.
  • Target ambition — where the ladder is declared finished (minimal self-rebuild versus a fully optimized, reproducible steady state). A nearer target ships sooner; a further one front-loads more rungs.

When it helps, and when it misleads

Its strength is that it makes the climb well-founded and legible: everyone can see the order, the goal, and the cost, and any proposed shortcut that skips a rung or imports from outside the ladder stands out immediately against the contracts. The budgets turn "this is taking forever" into a specific rung that blew its estimate.

Its failure mode is the plan diverging from the build — a runbook that is written once and not revised becomes an aspirational fiction while the real ascent improvises around it. Capability contracts can also be gamed: a rung declared "done" because a task list is complete, when the actual capability was never demonstrated. And optimistic budgets invite the planning fallacy, since bootstrap friction hides in exactly the rungs no one has climbed before. The discipline is to bind each rung's contract to a real readiness check at promotion time — the runbook proposes the capability, but Checkpointed Stage Promotion is where a rung earns the right to be called done.

How it implements the components

Capability-Ladder Runbook fills the archetype's forward-plan components — target, per-stage contracts, and budget:

  • transition_target_state — it states the self-hosted end state the whole ladder climbs toward, concretely enough to know when the climb is over.
  • stage_capability_contract — it defines each rung as the capability it must deliver upward, making stage success a testable property.
  • bootstrap_resource_budget — it assigns expected effort and resources to each rung, so overruns localize and the climb can be re-planned on evidence.

It does not gate or snapshot the actual ascent (that's Checkpointed Stage Promotion), declare the underlying dependency graph and seed (that's Bootstrap Dependency Manifest), or hand authority to the finished self-hosted system (that's Cross-Compiler-to-Self-Host Handoff).