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

scripts/estimates.py

View on GitHub
#!/usr/bin/env python3
"""Time estimates for a `.plan/`, and the actuals measured against them.

Four jobs, each a reading of files that already exist -- nothing here writes:

  plan       Sum the stage index's `estimate` column two ways: summed (every
             stage end to end) and elapsed (the longest `depends` chain, the
             floor when independent stages run in parallel). With the ledger
             beside it, also what is left: the stages not yet `done`/`skipped`.
  report     The usage report `/plan-close` shows: per stage, the estimate
             against the `Actuals:` lines its ledger notes block carries, and
             the plan's totals.
  check      Gate for the finish protocol: exit 1, naming the stage, when its
             ledger notes block has neither an `Actuals:` line nor an
             `Actuals waived: <reason>` line. Run before a stage is recorded `done`.
  calibrate  Read the effort log's `stage-run` rows that carry both an
             estimate and a measured span, and say by how much past estimates
             ran long or short. `/plan-stages` scales its judged ranges by it.

Why a script. Adding ranges across a dependency graph is arithmetic the model
gets wrong quietly; a stage table that says "elapsed 4-7h" must be the same
answer every time it is read.

Estimates are ranges in hours -- `1-2h`, `0.5–1h` (hyphen or en dash) or a
bare `2h`. A cell of `—` or `-` means "no estimate" and is counted, not
guessed at. Actuals include time spent waiting on the user; estimates do not.

Invoke as `python <path>/estimates.py <subcommand> ...`.

Exit codes: 0 printed (for `check`, the stage has its line or a waiver), 1
`check` found the stage with neither, 2 usage/IO failure or an unreadable plan.
"""

from __future__ import annotations

import argparse
import json
import os
import re
import statistics
import sys
from datetime import datetime
from pathlib import Path

RANGE_RE = re.compile(r"^\s*(\d+(?:\.\d+)?)\s*(?:[–-]\s*(\d+(?:\.\d+)?))?\s*h\s*$")
STAGE_RE = re.compile(r"^(S\d+[a-z]?|SF)\b")
DEP_RE = re.compile(r"S\d+[a-z]?|SF")
NO_VALUE = {"", "—", "-", "–"}
ACTUALS_RE = re.compile(
    r"Actuals:\s*(?P<start>\S+)\s*→\s*(?P<finish>\S+)\s*·\s*(?P<min>\d+|None)\s*min\s*·\s*"
    r"tokens in=(?P<in>\d+) out=(?P<out>\d+) cache_read=(?P<cr>\d+) cache_write=(?P<cw>\d+)"
)
# A stage whose usage cannot be measured (`effortlog.py usage` exits 2) records
# why instead; `check` accepts the line, `report` still counts the stage as
# not measured.
WAIVER_RE = re.compile(r"Actuals waived:\s*(?P<reason>\S.*)")
CLOSED = {"done", "skipped"}
MIN_ROWS = 3  # fewer calibrated rows than this say nothing a judgement doesn't


class PlanError(Exception):
    pass


def parse_range(cell: str) -> tuple[float, float] | None:
    if cell.strip() in NO_VALUE:
        return None
    m = RANGE_RE.match(cell)
    if not m:
        raise PlanError(f"estimate {cell!r} is not a range in hours such as 1-2h")
    lo = float(m.group(1))
    hi = float(m.group(2)) if m.group(2) else lo
    if hi < lo:
        raise PlanError(f"estimate {cell!r} runs high to low")
    return lo, hi


def split_row(line: str) -> list[str]:
    return [c.strip() for c in line.strip().strip("|").split("|")]


def parse_index(text: str) -> list[dict]:
    """Stage rows of `## Stage index`, columns found by header name."""
    lines = text.splitlines()
    start = next((i for i, l in enumerate(lines) if l.startswith("## Stage index")), None)
    if start is None:
        raise PlanError("PLAN.md has no '## Stage index' section")
    header, stages = None, []
    for line in lines[start + 1:]:
        if line.startswith("## "):
            break
        if not line.startswith("|"):
            if stages:
                break
            continue
        cells = split_row(line)
        if header is None:
            header = [c.lower() for c in cells]
            continue
        if set(cells[0]) <= set("-: "):
            continue
        m = STAGE_RE.match(cells[0])
        if not m:
            continue
        row = dict(zip(header, cells))
        depends = row.get("depends", "")
        stages.append({
            "id": m.group(1),
            "name": cells[0],
            "depends": [] if depends in NO_VALUE else DEP_RE.findall(depends),
            "estimate": parse_range(row.get("estimate", "")),
            "estimate_text": row.get("estimate", "—") or "—",
        })
    if header is None or not stages:
        raise PlanError("the stage index has no rows")
    if "estimate" not in header:
        raise PlanError("the stage index has no `estimate` column")
    return stages


def parse_ledger(text: str) -> tuple[dict, dict, dict]:
    """Statuses from `## Status`, and per notes block every `Actuals:` line
    and every `Actuals waived:` reason."""
    statuses, actuals, waived = {}, {}, {}
    section, block = None, None
    for line in text.splitlines():
        if line.startswith("## "):
            section, block = line[3:].strip(), None
            continue
        if line.startswith("### "):
            m = STAGE_RE.match(line[4:].strip())
            block = m.group(1) if m else None
            continue
        if section == "Status" and line.startswith("|"):
            cells = split_row(line)
            m = STAGE_RE.match(cells[0]) if len(cells) > 1 else None
            if m:
                statuses[m.group(1)] = cells[1].lower()
        if block:
            m = ACTUALS_RE.search(line)
            if m:
                actuals.setdefault(block, []).append(m)
            m = WAIVER_RE.search(line)
            if m:
                waived.setdefault(block, []).append(m["reason"].strip())
    return statuses, actuals, waived


def longest_path(stages: list[dict], end: int) -> float:
    """Longest `depends` chain, taking each stage's low (0) or high (1) end."""
    by_id = {s["id"]: s for s in stages}
    memo: dict[str, float] = {}

    def finish(sid: str, trail: tuple = ()) -> float:
        if sid in memo:
            return memo[sid]
        if sid in trail:
            raise PlanError(f"depends cycle through {sid}")
        stage = by_id.get(sid)
        if stage is None:
            return 0.0
        own = stage["estimate"][end] if stage["estimate"] else 0.0
        memo[sid] = own + max((finish(d, trail + (sid,)) for d in stage["depends"]), default=0.0)
        return memo[sid]

    return max((finish(s["id"]) for s in stages), default=0.0)


def totals(stages: list[dict]) -> dict:
    est = [s["estimate"] for s in stages if s["estimate"]]
    return {
        "summed": [sum(e[0] for e in est), sum(e[1] for e in est)],
        "elapsed": [longest_path(stages, 0), longest_path(stages, 1)],
        "unestimated": [s["id"] for s in stages if not s["estimate"]],
    }


def hours(pair: list[float]) -> str:
    lo, hi = (f"{v:g}" for v in pair)
    return f"{lo}h" if lo == hi else f"{lo}–{hi}h"


def total_line(label: str, t: dict) -> str:
    line = f"{label}: summed {hours(t['summed'])} · elapsed {hours(t['elapsed'])}"
    if t["unestimated"]:
        line += f" · no estimate: {', '.join(t['unestimated'])}"
    return line


def load(plan_dir: Path) -> tuple[list[dict], dict, dict, dict]:
    plan = plan_dir / "PLAN.md"
    if not plan.is_file():
        raise PlanError(f"no PLAN.md in {plan_dir}")
    stages = parse_index(plan.read_text(encoding="utf-8"))
    ledger = plan_dir / "LEDGER.md"
    statuses, actuals, waived = ({}, {}, {})
    if ledger.is_file():
        statuses, actuals, waived = parse_ledger(ledger.read_text(encoding="utf-8"))
    return stages, statuses, actuals, waived


def cmd_plan(args: argparse.Namespace) -> int:
    stages, statuses, _, _ = load(Path(args.plan_dir))
    out = {"plan": totals(stages)}
    out["line"] = total_line("Plan estimate", out["plan"])
    if statuses:
        open_ids = {s["id"] for s in stages if statuses.get(s["id"], "todo") not in CLOSED}
        left = [
            {**s, "depends": [d for d in s["depends"] if d in open_ids]}
            for s in stages if s["id"] in open_ids
        ]
        out["remaining"] = totals(left)
        out["remaining_line"] = total_line("Left", out["remaining"])
    print(json.dumps(out, indent=2, ensure_ascii=False))
    return 0


def stamp(text: str) -> datetime | None:
    try:
        return datetime.fromisoformat(text.replace("Z", "+00:00"))
    except ValueError:
        return None


def cmd_report(args: argparse.Namespace) -> int:
    stages, statuses, actuals, _ = load(Path(args.plan_dir))
    rows, grand = [], {"in": 0, "out": 0, "cache_read": 0, "cache_write": 0}
    spent_min, starts, finishes, measured = 0, [], [], 0
    for s in stages:
        lines = actuals.get(s["id"], [])
        minutes = sum(int(m["min"]) for m in lines if m["min"] != "None")
        tok = {
            "in": sum(int(m["in"]) for m in lines),
            "out": sum(int(m["out"]) for m in lines),
            "cache_read": sum(int(m["cr"]) for m in lines),
            "cache_write": sum(int(m["cw"]) for m in lines),
        }
        for k in grand:
            grand[k] += tok[k]
        spent_min += minutes
        if lines:
            measured += 1
        starts += [t for t in (stamp(m["start"]) for m in lines) if t]
        finishes += [t for t in (stamp(m["finish"]) for m in lines) if t]
        rows.append(
            f"| {s['name']} | {statuses.get(s['id'], '—')} | {s['estimate_text']} | "
            + (f"{minutes / 60:.1f}h | {tok['in'] + tok['cache_read'] + tok['cache_write']} | {tok['out']} | {len(lines)} |"
               if lines else "— | — | — | 0 |")
        )
    t = totals(stages)
    span = (max(finishes) - min(starts)).total_seconds() / 3600 if starts and finishes else None
    report = [
        "| Stage | Status | Estimate | Actual | Tokens in (incl. cache) | Tokens out | Sessions |",
        "|---|---|---|---|---|---|---|",
        *rows,
        "",
        f"- **Estimate:** {total_line('plan', t).split(': ', 1)[1]}.",
        f"- **Actual:** summed {spent_min / 60:.1f}h over {measured} measured stage(s)"
        + (f" · elapsed {span:.1f}h, first start to last finish" if span is not None else "")
        + ". Actuals include time waiting on the user; the estimate does not.",
        f"- **Tokens:** in {grand['in']} · out {grand['out']} · cache read {grand['cache_read']}"
        f" · cache write {grand['cache_write']}, subagents included.",
    ]
    unmeasured = [s["id"] for s in stages if s["id"] not in actuals]
    if unmeasured:
        report.append(f"- **Not measured:** {', '.join(unmeasured)} (no `Actuals:` line in the ledger).")
    print("\n".join(report))
    return 0


def cmd_check(args: argparse.Namespace) -> int:
    stages, _, actuals, waived = load(Path(args.plan_dir))
    sid = args.stage
    if sid not in {s["id"] for s in stages}:
        raise PlanError(f"{sid} is not a stage in the stage index")
    if actuals.get(sid):
        print(f"{sid}: {len(actuals[sid])} Actuals line(s) in its ledger notes block.")
        return 0
    if waived.get(sid):
        print(f"{sid}: Actuals waived -- {waived[sid][0]}")
        return 0
    print(
        f"estimates: {sid} has no `Actuals:` line in its LEDGER.md notes block. "
        "Add the line (effortlog.py usage), or `Actuals waived: <reason>` when usage cannot be measured.",
        file=sys.stderr,
    )
    return 1


def cmd_calibrate(args: argparse.Namespace) -> int:
    path = args.log or os.environ.get("CLAUDE_EFFORT_LOG")
    if not path or not Path(path).is_file():
        print(json.dumps({"rows": 0, "factor": None,
                          "line": "No effort log to calibrate from; use the reference ranges as written."}))
        return 0
    # A resumed stage logs one row per session, each a slice of one estimate:
    # sum a stage's sessions first, and count only stages that finished.
    stages: dict = {}
    for raw in Path(path).read_text(encoding="utf-8").splitlines():
        try:
            row = json.loads(raw)
        except ValueError:
            continue
        if row.get("source") != "stage-run" or not row.get("estimate") or not row.get("elapsed_minutes"):
            continue
        try:
            est = parse_range(str(row["estimate"]))
        except PlanError:
            continue
        if not est or sum(est) == 0:
            continue
        entry = stages.setdefault(row.get("target") or id(row), {"est": est, "minutes": 0, "done": False})
        entry["minutes"] += row["elapsed_minutes"]
        entry["done"] = entry["done"] or row.get("outcome") == "stage-done"
    ratios = [
        (e["minutes"] / 60) / (sum(e["est"]) / 2) for e in stages.values() if e["done"]
    ]
    if len(ratios) < MIN_ROWS:
        print(json.dumps({"rows": len(ratios), "factor": None,
                          "line": f"{len(ratios)} measured stage(s), fewer than {MIN_ROWS}; use the reference ranges as written."}))
        return 0
    factor = round(statistics.median(ratios), 2)
    print(json.dumps({
        "rows": len(ratios),
        "factor": factor,
        "line": f"Past stages took {factor}x their estimate's midpoint (median of {len(ratios)}); "
                f"scale judged ranges by {factor}.",
    }))
    return 0


def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(prog="estimates.py")
    sub = parser.add_subparsers(dest="command", required=True)
    plan = sub.add_parser("plan", help="the plan total, summed and elapsed, and what is left")
    plan.add_argument("--plan-dir", default=".plan")
    plan.set_defaults(func=cmd_plan)
    report = sub.add_parser("report", help="estimate against actuals, per stage and for the plan")
    report.add_argument("--plan-dir", default=".plan")
    report.set_defaults(func=cmd_report)
    check = sub.add_parser("check", help="exit 1 naming a stage whose ledger notes block has no Actuals line")
    check.add_argument("--plan-dir", default=".plan")
    check.add_argument("--stage", required=True, help="stage ID, e.g. S3")
    check.set_defaults(func=cmd_check)
    cal = sub.add_parser("calibrate", help="how far past estimates ran from their actuals")
    cal.add_argument("--log", help="NDJSON effort log; defaults to CLAUDE_EFFORT_LOG")
    cal.set_defaults(func=cmd_calibrate)
    return parser


def main(argv: list[str] | None = None) -> int:
    if hasattr(sys.stdout, "reconfigure"):
        sys.stdout.reconfigure(encoding="utf-8")
    args = build_parser().parse_args(argv)
    try:
        return args.func(args)
    except (PlanError, OSError) as exc:
        print(f"estimates: {exc}", file=sys.stderr)
        return 2


if __name__ == "__main__":
    sys.exit(main())
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