From 6132e7f5ab5c59019753d639e70de3dadf7f55ad Mon Sep 17 00:00:00 2001 From: Manas Srivastava Date: Mon, 11 May 2026 11:39:55 +0530 Subject: [PATCH] chore(plan-rollout): drop docs/designs/PLAN_ROLLOUT_V0.md from source tree MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per OSS convention, design rationale and dogfood evidence live in the PR description, not as checked-in cruft. The V0.md content has been folded into PR #1424's description, where reviewers actually look. 81 lines off the reviewable diff. If long-form design rationale is wanted in-repo later, it can land as a follow-up — but only if a real consumer (a feature that depends on the rationale) ships at the same time. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/designs/PLAN_ROLLOUT_V0.md | 81 --------------------------------- 1 file changed, 81 deletions(-) delete mode 100644 docs/designs/PLAN_ROLLOUT_V0.md diff --git a/docs/designs/PLAN_ROLLOUT_V0.md b/docs/designs/PLAN_ROLLOUT_V0.md deleted file mode 100644 index 40f998682..000000000 --- a/docs/designs/PLAN_ROLLOUT_V0.md +++ /dev/null @@ -1,81 +0,0 @@ -# PLAN_ROLLOUT_V0 — decomposition-as-artifact - -**Status:** SHIPPED (v0.1.0) -**Skill:** `plan-rollout/SKILL.md.tmpl` -**Schema:** `docs/SYSTEM_MD.md` - -## Problem - -LLMs compress implementation 10-100x. They do not compress *review*. A -2,000-line diff is unreviewable — scope creeps, reviewers skim, bugs -ship. No existing skill asks of an actual diff: "one PR, or several?" - -## Design - -`/plan-rollout` reads the working diff + optional `SYSTEM.md`, writes -one artifact: `decomposition.md` (per-slice file lists, reader-time -estimates, dependency edges, reconciliation flags). Never splits -branches, never implements, never ships. - -Verdict-first: if the diff is one PR, the artifact says so in one line -and stops. False slicing is worse than no slicing. - -`SYSTEM.md` is optional input. Path heuristics + import discovery -when absent. - -## What v0 ships - -| File | Lines | Purpose | -|------|------:|---------| -| `plan-rollout/SKILL.md.tmpl` | 296 | Skill template | -| `plan-rollout/SKILL.md` | 1011 | Generated from template | -| `docs/SYSTEM_MD.md` | 129 | Schema spec (optional input) | -| `docs/designs/PLAN_ROLLOUT_V0.md` | (this file) | Design + dogfood | -| `AGENTS.md`, `docs/skills.md` | +2 | Registry | - -Out of v0 (deferred): `rollout.md`, spill-check skill, `/ship` and -`/review` integrations, `SYSTEM.md` scaffolder. Reverting v0 is -`git rm -r plan-rollout/ docs/SYSTEM_MD.md docs/designs/PLAN_ROLLOUT_V0.md`. - -## Dogfood: PR #1241 - -Target: [garrytan/gstack#1241](https://github.com/garrytan/gstack/pull/1241) -— 41 files, +661/-282. Manual walkthrough. - -Bucketing (no SYSTEM.md): - -| Bucket | Files | Lines | -|--------|------:|------:| -| `*/SKILL.md` regenerations | 36 | +576/-252 | -| `scripts/resolvers/preamble/` (the fix) | 1 | +16/-7 | -| `test/fixtures/golden/` regenerations | 3 | +54/-27 | -| `test/` | 2 | +31/-3 | - -Reader time: `ceil(943/80) + ceil(41/5) = 21 min`. Under 30-min cap. - -### Verdict - -**One PR.** 39 of 41 files are deterministic regenerations of one -source change in `scripts/resolvers/preamble/generate-ask-user-format.ts`. -Not independently shippable — splitting them would leave dependent -fragments. - -### Findings (v1.1 backlog) - -1. **Regeneration detector.** Path heuristics don't know `*/SKILL.md` - is mechanical output of `*/SKILL.md.tmpl`. Without it, a naive - operator might still ship "source + regenerations" as two PRs. Fix: - filename-pattern match + optional `regeneration-of:` in SYSTEM.md. -2. **Regen-multiplier on reader-time.** Lines in regenerated files - should count ~0.1x (skim speed). Today they count 1x. -3. **`--explain` mode.** When the verdict is "one PR," print the - rejected slicing alternatives and why each was rejected. -4. **Calibration loop.** Log predicted vs actual reader-time on the - first ~10 real invocations. Ground v2 heuristics in data. - -### Limit surfaced - -`SYSTEM.md` is **not** the right primitive for build-output coupling. -The signal needed is "file X is generated from file Y" — closer to a -Makefile dependency than a contract graph. Don't promise SYSTEM.md -solves regeneration cases.