From 4aed6e1724c30807fbe566d9e2c724a5d5718523 Mon Sep 17 00:00:00 2001 From: Manas Srivastava Date: Mon, 11 May 2026 11:01:09 +0530 Subject: [PATCH] fix(plan-rollout): drop /plan-pull-request cross-references MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit /plan-pull-request is not a gstack-shipped skill; it's a separately installed global skill. Referencing it as a sibling in our SKILL.md and docs/skills.md created a dangling dependency from the maintainer's perspective. The skill stands on its own: it reads a real diff and writes decomposition.md. Whatever pre-decision workflow the user runs beforehand is the user's setup, not this skill's documented contract. - Stripped "Relationship to /plan-pull-request" section from plan-rollout/SKILL.md.tmpl - Removed the "If invoked before code exists, point at /plan-pull-request" redirect — now a simple "nothing to decompose, write a slice first" exit - Reworded the docs/skills.md table row to describe what the skill does on its own, no external pairing claims - Tightened the description frontmatter accordingly Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/skills.md | 2 +- plan-rollout/SKILL.md | 40 ++++++++++++-------------------------- plan-rollout/SKILL.md.tmpl | 40 ++++++++++++-------------------------- 3 files changed, 25 insertions(+), 57 deletions(-) diff --git a/docs/skills.md b/docs/skills.md index 1ff072e27..f34dfa3f0 100644 --- a/docs/skills.md +++ b/docs/skills.md @@ -8,7 +8,7 @@ Detailed guides for every gstack skill — philosophy, workflow, and examples. | [`/plan-ceo-review`](#plan-ceo-review) | **CEO / Founder** | Rethink the problem. Find the 10-star product hiding inside the request. Four modes: Expansion, Selective Expansion, Hold Scope, Reduction. | | [`/plan-eng-review`](#plan-eng-review) | **Eng Manager** | Lock in architecture, data flow, diagrams, edge cases, and tests. Forces hidden assumptions into the open. | | [`/plan-design-review`](#plan-design-review) | **Senior Designer** | Interactive plan-mode design review. Rates each dimension 0-10, explains what a 10 looks like, fixes the plan. Works in plan mode. | -| [`/plan-rollout`](#plan-rollout) | **Decomposition Analyst** | Post-decision artifact: analyzes a real working diff (and `SYSTEM.md` if present), writes `decomposition.md` with per-slice file lists, reader-time estimates, and reconciliation flags. Pairs with `/plan-pull-request` (decide) → `/plan-rollout` (analyze). | +| [`/plan-rollout`](#plan-rollout) | **Decomposition Analyst** | Analyzes a real working diff (and `SYSTEM.md` if present), writes `decomposition.md` with per-slice file lists, reader-time estimates, dependency edges, and reconciliation flags. Runs against files that already exist — no slicing intentions, just analysis of what's there. | | [`/design-consultation`](#design-consultation) | **Design Partner** | Build a complete design system from scratch. Knows the landscape, proposes creative risks, generates realistic product mockups. Design at the heart of all other phases. | | [`/review`](#review) | **Staff Engineer** | Find the bugs that pass CI but blow up in production. Auto-fixes the obvious ones. Flags completeness gaps. | | [`/investigate`](#investigate) | **Debugger** | Systematic root-cause debugging. Iron Law: no fixes without investigation. Traces data flow, tests hypotheses, stops after 3 failed fixes. | diff --git a/plan-rollout/SKILL.md b/plan-rollout/SKILL.md index d0f06dadf..035512af4 100644 --- a/plan-rollout/SKILL.md +++ b/plan-rollout/SKILL.md @@ -7,11 +7,9 @@ description: | Decomposition-as-artifact. Given a real working diff (and `SYSTEM.md` if present), produces a written `decomposition.md` with per-slice file lists, reader-time estimates, dependency edges, and contract-graph reconciliation - flags. This is the post-decision consumer: it analyzes a diff that already - exists. For the pre-decision conversation ("should this be one PR or - many?"), use `/plan-pull-request` first. Use when asked to "decompose - the diff", "write a decomposition.md", "plan-rollout", or after - `/plan-pull-request` has already concluded the work should slice. (gstack) + flags. Runs after a diff exists — it analyzes actual files, not intentions. + Use when asked to "decompose the diff", "write a decomposition.md", or + "plan-rollout". (gstack) Voice triggers (speech-to-text aliases): "decompose the diff", "write a decomposition", "plan-rollout". allowed-tools: - Read @@ -755,38 +753,24 @@ You read a working diff (plus `SYSTEM.md` if present) and write You never write code, never split branches, never run `/ship`. The output is the artifact and only the artifact. -## Relationship to /plan-pull-request - -These are two halves of one workflow, not competitors. Run them in order: - -| Skill | When | Mode | Output | -|-------|------|------|--------| -| `/plan-pull-request` | Pre-code or early-code | Conversation | Decision: boil vs slice + a sketch | -| `/plan-rollout` | After a real diff exists | Analysis | `decomposition.md` artifact tied to actual files | - -If the user invokes `/plan-rollout` before any code has been written, stop -and tell them: "`/plan-pull-request` is the right skill for pre-code shape -decisions. Run that first; come back here when you have a real diff to -decompose." - -If the user invokes `/plan-pull-request`'s decision already concluded "boil -it — one PR," and they invoke `/plan-rollout` anyway, do the analysis -honestly — if the diff really is one PR's worth, the output's verdict -says so in one line and you stop. Don't manufacture slices. - ## When to invoke this skill Run when a diff already exists (committed or working tree) and either: - The user explicitly asks for `decomposition.md`. -- `/plan-pull-request` concluded "slice it" and the user wants an analysis - artifact tied to the actual files. +- The user has decided the work should ship as a stack and wants an + analysis artifact tied to the actual files. - A reviewer asked to see the change broken down before they read it. +If invoked before any code has been written, stop and say so: there is +nothing to decompose. Suggest writing the smallest end-to-end slice first +and re-running the skill against the real diff. + Don't run on single-component, sub-30-min-reader-time diffs unless the user -overrides — produce the one-line "this is one PR" verdict and stop. +overrides — produce the one-line "this is one PR" verdict and stop. False +slicing is worse than no slicing. Out of scope for v1: writing `rollout.md` (rollout/rollback strategy), -running `/spill-check` against in-progress diffs, integrating with `/ship` +running spill-check against in-progress diffs, integrating with `/ship` or `/review`, scaffolding `SYSTEM.md`. This skill produces decomposition.md and stops. diff --git a/plan-rollout/SKILL.md.tmpl b/plan-rollout/SKILL.md.tmpl index 0522a2a53..e64be790f 100644 --- a/plan-rollout/SKILL.md.tmpl +++ b/plan-rollout/SKILL.md.tmpl @@ -7,11 +7,9 @@ description: | Decomposition-as-artifact. Given a real working diff (and `SYSTEM.md` if present), produces a written `decomposition.md` with per-slice file lists, reader-time estimates, dependency edges, and contract-graph reconciliation - flags. This is the post-decision consumer: it analyzes a diff that already - exists. For the pre-decision conversation ("should this be one PR or - many?"), use `/plan-pull-request` first. Use when asked to "decompose - the diff", "write a decomposition.md", "plan-rollout", or after - `/plan-pull-request` has already concluded the work should slice. (gstack) + flags. Runs after a diff exists — it analyzes actual files, not intentions. + Use when asked to "decompose the diff", "write a decomposition.md", or + "plan-rollout". (gstack) voice-triggers: - "decompose the diff" - "write a decomposition" @@ -38,38 +36,24 @@ You read a working diff (plus `SYSTEM.md` if present) and write You never write code, never split branches, never run `/ship`. The output is the artifact and only the artifact. -## Relationship to /plan-pull-request - -These are two halves of one workflow, not competitors. Run them in order: - -| Skill | When | Mode | Output | -|-------|------|------|--------| -| `/plan-pull-request` | Pre-code or early-code | Conversation | Decision: boil vs slice + a sketch | -| `/plan-rollout` | After a real diff exists | Analysis | `decomposition.md` artifact tied to actual files | - -If the user invokes `/plan-rollout` before any code has been written, stop -and tell them: "`/plan-pull-request` is the right skill for pre-code shape -decisions. Run that first; come back here when you have a real diff to -decompose." - -If the user invokes `/plan-pull-request`'s decision already concluded "boil -it — one PR," and they invoke `/plan-rollout` anyway, do the analysis -honestly — if the diff really is one PR's worth, the output's verdict -says so in one line and you stop. Don't manufacture slices. - ## When to invoke this skill Run when a diff already exists (committed or working tree) and either: - The user explicitly asks for `decomposition.md`. -- `/plan-pull-request` concluded "slice it" and the user wants an analysis - artifact tied to the actual files. +- The user has decided the work should ship as a stack and wants an + analysis artifact tied to the actual files. - A reviewer asked to see the change broken down before they read it. +If invoked before any code has been written, stop and say so: there is +nothing to decompose. Suggest writing the smallest end-to-end slice first +and re-running the skill against the real diff. + Don't run on single-component, sub-30-min-reader-time diffs unless the user -overrides — produce the one-line "this is one PR" verdict and stop. +overrides — produce the one-line "this is one PR" verdict and stop. False +slicing is worse than no slicing. Out of scope for v1: writing `rollout.md` (rollout/rollback strategy), -running `/spill-check` against in-progress diffs, integrating with `/ship` +running spill-check against in-progress diffs, integrating with `/ship` or `/review`, scaffolding `SYSTEM.md`. This skill produces decomposition.md and stops.