Skip to content

by-carlos/plan-staged-rollout / skills/staged-rollout

staged-rollout

Unverified

Run a large build as many small, resumable sessions by decomposing it into a `.plan/` folder of dependency-ordered stages with an evidence ledger, then executing one stage per fresh session. Use when the user says "this is too big for one session", "plan a staged rollout", or describes a multi-day build that needs cross-session progress tracking.

FileKindSize
SKILL.mdskill md52.3 KB
references/decisions-format.mdmarkdown6.1 KB
references/estimates.mdmarkdown5.5 KB
references/plan-review.mdmarkdown7.4 KB
references/programme-format.mdmarkdown2.8 KB
references/remote-driver.mdmarkdown18.3 KB
references/templates/BRIEF.mdmarkdown3.0 KB
references/templates/LEDGER.mdmarkdown3.3 KB
references/templates/PLAN.mdmarkdown48.0 KB
references/templates/README.mdmarkdown8.2 KB
references/templates/RUNNER.mdmarkdown9.7 KB
references/templates/stage-N.mdmarkdown2.1 KB
references/templates/stage-f-review.mdmarkdown11.2 KB
scripts/artifacts_check.pyscript5.6 KB
scripts/effortlog.pyscript18.0 KB
scripts/estimates.pyscript14.4 KB
scripts/plan_run_local.pyscript31.4 KB
scripts/renumber_stages.pyscript13.2 KB
tests/fixtures/drift-plan/.plan/LEDGER.mdmarkdown1.0 KB
tests/fixtures/drift-plan/.plan/PLAN.mdmarkdown1.7 KB
tests/fixtures/live-plan/.plan/LEDGER.mdmarkdown564 B
tests/fixtures/live-plan/.plan/PLAN.mdmarkdown1.4 KB
tests/fixtures/live-plan/.plan/stage-0-scaffold.mdmarkdown90 B
tests/fixtures/live-plan/.plan/stage-1-build-api.mdmarkdown83 B
tests/fixtures/live-plan/.plan/stage-2-deploy-staging.mdmarkdown87 B
tests/fixtures/live-plan/.plan/stage-3-migrate-data.mdmarkdown97 B
tests/fixtures/live-plan/.plan/stage-4-warm-cache.mdmarkdown84 B
tests/fixtures/live-plan/.plan/stage-5-runbook.mdmarkdown87 B
tests/fixtures/live-plan/.plan/stage-f-review.mdmarkdown81 B
tests/test_artifacts_check.pyscript5.9 KB
tests/test_discovery_bound.pyscript2.3 KB
tests/test_estimates.pyscript10.7 KB
tests/test_plan_run_local.pyscript18.3 KB
tests/test_preflight_ahead.pyscript3.3 KB
tests/test_renumber_stages.pyscript17.0 KB

references/estimates.md

View on GitHub
# Estimates, actuals and the usage report

A plan carries a rough time estimate for every stage, records what each stage
really took, and reports the two side by side at closeout. This file is the
method: how the first estimates are made, how they are measured, and how later
plans learn from earlier ones.

**These are guesses, not promises.** An estimate covers the stage's own work
in a session. It leaves out waiting on the user, blockers and unknowns, so a
stage that stops at a gate will run over it.

## The estimate

- **Where it lives.** The stage index's `estimate` column, one cell per stage,
  and nowhere else (stage files never restate it, like every other column).
- **Its form.** A range in hours: `1–2h`, `0.5-1h` (en dash or hyphen), or a
  bare `2h` when there is no spread. `—` means "not estimated" and is reported
  as such, never counted as zero silently.
- **The plan total.** The `Plan estimate:` line under the plan flags, computed,
  never added up by hand:

  ```
  python "${CLAUDE_PLUGIN_ROOT}/skills/staged-rollout/scripts/estimates.py" plan --plan-dir .plan
  ```

  It prints two totals. **Summed** is every stage end to end, the session time
  the plan costs. **Elapsed** is the longest `depends` chain, the clock time
  when every wave runs in parallel; it is the floor no amount of parallelism
  removes. With a ledger beside it, the same command prints `remaining_line`:
  what is left once `done` and `skipped` stages drop out.

## The first rule: judged, anchored

Before any actuals exist, the planner judges each stage's range from its
Steps and Artifacts, against these anchors. They are starting values, meant
to be replaced (see *Calibration*).

| A stage that… | Range |
|---|---|
| edits one or two documents, no code | `0.25–0.5h` |
| changes one script or module, with its tests | `0.5–1.5h` |
| adds a component across several files, with tests | `1.5–3h` |
| builds a keystone others depend on, or crosses repos | `2–4h` |
| reviews the plan (`SF`) | `0.5–1h` |

Widen the range rather than raise its middle when a stage is uncertain, and
split a stage whose honest range runs past 4h. The `model` and `effort`
columns do not set the estimate: effort is reasoning depth, not amount of
work.

## Actuals

Each session that works on a stage, whether it finishes, stops `doing` or
stops `blocked`, adds one line to the stage's notes block in `LEDGER.md`:

```
python "${CLAUDE_PLUGIN_ROOT}/skills/staged-rollout/scripts/effortlog.py" usage
```

It prints JSON whose `line` is pasted as is:

```
Actuals: 2026-07-08T12:41:09Z → 2026-07-08T15:02:44Z · 142 min · tokens in=212 out=48310 cache_read=6120455 cache_write=301877 · subagents=1
```

- **Source.** The session's own transcript (`<session-id>.jsonl`), the only
  record present in the CLI, the desktop app and cloud sessions alike. Each
  streamed message is counted once; subagents' transcripts are included.
- **Time** is wall clock from the transcript's first entry to its last, so it
  includes time spent waiting on the user.
- **Tokens only.** No dollar cost and no share of a usage limit: cost needs a
  price table that goes stale and means nothing on a subscription, and a
  usage limit is the account's, shared with every other session.
- The fields are raw integers on purpose: `estimates.py report` reads them
  back. A resumed stage has one line per session, and the report sums them.
- **A stage is not recorded `done` without one.** The finish protocol runs
  `estimates.py check --plan-dir .plan --stage <ID>` first; it exits 1, naming
  the stage, when the notes block has no `Actuals:` line. Where `usage` itself
  cannot run (it exits 2: no session id, no transcript, or no usage yet), write
  `Actuals waived: <reason>` in the block instead. The check accepts it; the
  report still lists the stage as not measured.

## The usage report

`/plan-close` prints it and puts it in the final PR body, before `.plan/` is
removed:

```
python "${CLAUDE_PLUGIN_ROOT}/skills/staged-rollout/scripts/estimates.py" report --plan-dir .plan
```

Per stage: status, estimate, actual hours, tokens in (cache included), tokens
out and the number of measured sessions. Then the plan's estimate, its
actual summed and elapsed hours, its token totals, and every stage with no
`Actuals:` line, named rather than guessed.

## Calibration

The ledger is deleted at closeout, so what later plans learn from is the
effort log (`CLAUDE_EFFORT_LOG`, opt-in). Each `/stage-run` row carries the
stage's `estimate`, its measured `elapsed_minutes` and its `tokens`.
`/plan-stages` runs, before estimating:

```
python "${CLAUDE_PLUGIN_ROOT}/skills/staged-rollout/scripts/estimates.py" calibrate
```

- It groups the `stage-run` rows that carry both an estimate and a measured
  span by stage, sums each stage's sessions (a resumed stage logs one row per
  session), keeps only stages that reached `stage-done`, divides each one's
  actual hours by its estimate's midpoint, and reports the **median** ratio
  as `factor`.
- With fewer than three such rows, or no log, `factor` is null: use the
  anchors as written.
- Otherwise judge the range from the anchors as before, then multiply both
  ends by `factor`, and say so in the bootstrap's announcement ("estimates
  scaled by 1.4 from 12 past stages").
- Once the log is large enough to read by stage kind, replace the anchors'
  ranges here with the observed medians, in a pull request of their own.

A token estimate is not made yet. The log now records tokens per stage, and
one is added the same way once there are enough rows to base it on.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall