garrytan · mastermanas805 · May 11, 2026 · May 11, 2026 · May 11, 2026 · May 11, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -19,6 +19,7 @@ Invoke them by name (e.g., `/office-hours`).
 | `/plan-design-review` | Rate each design dimension 0-10, explain what a 10 looks like. |
 | `/plan-devex-review` | DX-mode review: TTHW, magical moments, friction points, persona traces. |
 | `/plan-tune` | Self-tune AskUserQuestion sensitivity per question. |
+| `/plan-rollout` | Post-decision: analyze the real diff and write `decomposition.md`. |
 | `/autoplan` | One command runs CEO → design → eng → DX review. |
 | `/design-consultation` | Build a complete design system from scratch. |
 

diff --git a/docs/SYSTEM_MD.md b/docs/SYSTEM_MD.md
@@ -0,0 +1,129 @@
+# SYSTEM.md — the semantic contract graph
+
+`SYSTEM.md` is an optional repo-root file declaring what each component
+*is*, what it *owns*, and the role-level contracts between components.
+Its consumer is `/plan-rollout`. The skill reads it to sharpen slice
+ordering and surface coordinated-deploy edges; it falls back to path
+heuristics when absent.
+
+Not a package manifest. Not an import graph. Those are discovered at
+runtime (AST, grep, manifests) and would go stale within a week if
+declared. SYSTEM.md captures only what a human knows: "auth mints
+session tokens middleware enforces; session-format change without
+middleware redeploy breaks sessions."
+
+## Schema (v1 — intra-repo)
+
+```yaml
+---
+version: 1
+components:
+  - name: <unique identifier>
+    path: <repo-relative path>
+    kind: component            # or: leaf-util | types-only (default: component)
+    role: <one-line job description>
+    owns:
+      - <data surface, table, API, or feature this component owns>
+    contracts:
+      - with: <other component name>
+        nature: <plain-English relationship>
+        breaks-if: <specific human action that violates the contract>
+        rollout-edge: <hard | soft>
+        note: <runtime-only | types-only | legacy | free text>   # optional
+    rollout-order: <integer; lower ships first; equal = parallel>
+---
+
+# System Map
+
+<Free-form human notes: stability, anti-patterns, deploy-edge lessons
+from past incidents. Not parsed.>
+```
+
+### Field reference
+
+| Field | Meaning |
+|-------|---------|
+| `name` | Unique identifier referenced by other components' contracts. Renames cascade. |
+| `path` | File or dir under the repo root. Used for component-membership lookups. |
+| `kind` | `component` (default), `leaf-util` (utils dirs, no contracts), `types-only` (interfaces, no runtime). leaf/types are skipped during reconciliation. |
+| `role` | One sentence: what this component does in the system. Not what it contains. |
+| `owns` | Data surfaces / tables / APIs / features this component is source-of-truth for. Dual ownership is a design smell. |
+| `contracts[].with` | Other component's name. Must match a declared component. |
+| `contracts[].nature` | Plain-English description of the relationship. |
+| `contracts[].breaks-if` | Specific human action that violates the contract. This is what `/plan-rollout` reads to detect coordinated-deploy stages. |
+| `contracts[].rollout-edge` | `hard` = must deploy together. `soft` = can lag. |
+| `contracts[].note` | `runtime-only` (DB/HTTP/bus coupling — no import edge expected), `types-only`, `legacy`, or free text. |
+| `rollout-order` | Integer. Lower ships first. Equal values can ship in parallel. |
+
+## Example
+
+```yaml
+---
+version: 1
+components:
+  - name: auth
+    path: src/auth
+    role: authentication + session lifecycle
+    owns: [user table, session table, JWT minting]
+    contracts:
+      - with: middleware
+        nature: middleware enforces session tokens auth mints
+        breaks-if: session payload schema changes without middleware redeploy
+        rollout-edge: hard
+    rollout-order: 1
+
+  - name: middleware
+    path: src/middleware
+    role: request routing + auth enforcement
+    owns: [request context shape]
+    contracts:
+      - with: gateway
+        nature: gateway consumes req.user set by middleware
+        breaks-if: req.user shape changes without gateway redeploy
+        rollout-edge: hard
+    rollout-order: 2
+
+  - name: gateway
+    path: src/gateway
+    role: external HTTP surface
+    owns: [public API schema]
+    contracts: []
+    rollout-order: 3
+
+  - name: utils
+    path: src/utils
+    kind: leaf-util
+    role: shared helpers — imported freely without contracts
+    owns: []
+    contracts: []
+    rollout-order: 0
+---
+
+# System Map
+
+auth and middleware are the security boundary. Session-format or
+user-context shape changes are coordinated deploys (rollout-edge: hard).
+We learned this in Feb 2025 when a session serializer change shipped
+40 minutes ahead of middleware and logged everyone out.
+```
+
+## How /plan-rollout uses it
+
+1. **File → component mapping.** Changed files are bucketed into the
+   slice for their component (matched by `path`, longest-match wins).
+   Without SYSTEM.md, the skill falls back to top-level-dir bucketing.
+2. **Slice ordering.** Slices are sorted by `rollout-order`. `leaf-util`
+   and `types-only` components float to slice 0.
+3. **Hard-edge enforcement.** When a changed-file set spans both sides
+   of a `rollout-edge: hard` contract, those files merge into one slice
+   tagged "coordinated deploy required — \<breaks-if reason\>".
+4. **Reconciliation flags (informational).** Mismatches between declared
+   contracts and discovered imports surface in the output:
+   `import-without-contract`, `contract-without-imports`,
+   `rollout-order-inversion`. Never blocking.
+
+## Out of scope (v1)
+
+No scaffolder. Write SYSTEM.md by hand or copy the example. Scaffolding
+that walks top-level dirs and infers `role` from README/`package.json`
+is a v2 follow-up.
diff --git a/docs/skills.md b/docs/skills.md
@@ -8,6 +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** | 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. |