RomanNum3ral
/
gstack
mirror of https://github.com/garrytan/gstack.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

chore(plan-rollout): drop docs/designs/PLAN_ROLLOUT_V0.md from source tree 

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) <noreply@anthropic.com>
This commit is contained in:
Manas Srivastava 2026-05-11 11:39:55 +05:30
parent cfc14e4ac5
commit 6132e7f5ab
1 changed files with 0 additions and 81 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

81
docs/designs/PLAN_ROLLOUT_V0.md
View File

@ -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.