Shapeup

ShapeUp Skill — v2.1

Shape Up workflows for Claude Code — covering every stage from raw problem to wiring diagram to structured handoff documents. Run these before writing code.

Resource Files (Load On Demand)

This skill lazily loads detail from resource files. Read the relevant resource before executing any workflow:

Resource paths are relative to this skill's directory (resources/ beside this SKILL.md, wherever the plugin is installed). Multi-gate runs maintain a derived decision digest so each gate reads a compact slice instead of full prose — see resources/context-compaction.md and the "Run Workspace & Digest" section below.

Canonical Workflow Order

/shaping                    /breadboarding
─────────────────────────   ───────────────────────────────────
1. Problem frame             5. [optional] Fat marker sketch
2. Requirements (R)          6. Affordance tables + wiring
3. Solution shape (A)        7. SLICING → vertical scopes
4. Fit check (R ↔ A)
       ↓
   Spike docs
(for unknowns only)
       ↓
  breadboarding

The single most common mistake: putting slicing inside shaping. Slicing is the final phase of breadboarding — not shaping. Shaping ends at the fit check.

Which Sub-Command to Use

Invocation

# DEFAULT — no sub-command = runs full pipeline automatically
/shapeup

# Explicit full pipeline (same as default)
/shapeup full

# Individual phases
/shapeup shaping
/shapeup spike "Does zoneinfo cover our timezone needs, or do we need a network API?"
/shapeup breadboarding

# Document skills (team/collaborative contexts)
/shapeup framing-doc < transcript.md
/shapeup kickoff-doc < transcript.md

# Maintenance
/shapeup breadboard-reflection < breadboard.md

WORKFLOW 0 — /shapeup full (DEFAULT)

Purpose: End-to-end pipeline from raw idea to final shaping.md + breadboard.md. This is the default mode — if no sub-command is given, run this.

Load resources: Read resources/shaping.md, then resources/breadboarding.md before B-phases.

Three standing rules that apply for the entire pipeline:

RULE 1 — ASK, DON'T ASSUME
  Never fill gaps with assumptions. When information is missing or ambiguous,
  STOP and ask the user before proceeding. One focused question at a time.
  Gate questions are mandatory (see below). Ad-hoc questions fire whenever
  Claude would otherwise have to guess something that affects the output.

RULE 2 — SIMPLEST SOLUTION FIRST
  At every decision point, prefer the simpler option.
  If two shapes cover the requirements equally, pick the one with fewer parts.
  If an affordance can be removed without breaking coverage, remove it.
  Complexity must be justified by a requirement — never added speculatively.

RULE 3 — NON-REGRESSION
  Do not change, refactor, or re-interpret anything the user has already
  confirmed as correct. If S1–S2 are signed off, S3 must not rewrite the
  problem frame or requirements. Scope only forward.

Mandatory Gate Questions

At each gate below, Claude MUST pause and ask before continuing.

Digest discipline (see resources/context-compaction.md). On a multi-gate run, maintain a derived decision digest at .shapeup/[slug]/digest.md:

• On entry to each phase → overwrite-head: rebuild the digest's working head from the live source artifact.

• At each gate, to make the decision → read the gate's minimal slice (the consumer view), not full artifact prose:

  Gate	Minimal slice to read
  0	raw input only (nothing to compact)
  1	problem frame + R-list + appetite
  2	R-list (frozen) + shape + rationale + constraints
  3	R-list (frozen) + shape + fit map + spike results
  4	R-list (frozen) + places + affordance table (U/N)

• On gate confirm → promote-head: collapse the working head into a one-line + wikilink in the Confirmed (frozen) zone, then open a fresh head for the next phase. The frozen zone is append-only and immutable (RULE 3). The digest is a derived read model — never the source of truth, never hand-edited.

GATE 0 — Before starting (fires if input is vague OR appetite is missing)
  Ask (two parts, one at a time if both missing):
    Part A: "Who is the user experiencing this problem, and what are they
             trying to accomplish? What's broken or missing for them today?"
    Part B: "What's the right time budget for this? (e.g. 1 week, 2 weeks, 6 weeks)
             Appetite anchors scope — without it, the shape has no natural stopping point."
  Skip Part A if: input already contains a clear user + problem statement.
  Skip Part B if: input already states an appetite / time budget.

GATE 1 — After S2 (Requirements)
  Show the R-list. Ask:
  "Are these the right requirements? Anything missing or out of scope?"
  Wait for explicit confirmation before shaping.

GATE 2 — After S3 (Shape selection)
  Show the selected shape with rationale. Ask:
  "Does this direction feel right? Any constraints I should know about
   (tech stack, team size, existing systems, appetite/time budget)?"
  Wait for confirmation before fit check.

GATE 3 — After S4 (Fit Check) / before breadboarding
  Show the fit check table. If any ❌ or ⚠️ exist, resolve them first.
  Ask: "Ready to move to wiring, or is there anything to adjust?"

GATE 4 — After B3 (Affordance Tables) / before slicing
  Show the affordance tables. Ask:
  "Do these affordances look right? Anything missing from the wiring?"
  Wait before slicing.

Full Pipeline Execution Order

INPUT: raw idea / brief / feature description
   │
   ▼
[GATE 0] — ask if input is vague OR appetite is missing
   ▼
[S1] Problem Frame + Appetite
   │  → one-paragraph problem statement (no solution language)
   │  → appetite: e.g. "~1 week" or "~2 weeks" — anchors scope throughout
   ▼
[S2] Requirements (R)
   │  → R0..RN, observable, technology-agnostic
   ▼
[S2.5] Rabbit Holes
   │  → explicit list of known traps that could eat the appetite
   │  → no-goes: things explicitly outside this feature
   ▼
[GATE 1] ← PAUSE — confirm R-list + rabbit holes ───────┐
   ▼                                                      │ revise if needed
[S3] Solution Shape (A)                                   │
   │  → simplest shape that covers all R within appetite  │
   ▼                                                      │
[GATE 2] ← PAUSE — confirm shape + constraints ──────────┘
   ▼
[S4] Fit Check
   │  → every R mapped; ❌ items surface as gate blockers
   │
   ├─ unknowns? → SPIKE inline; if unresolvable → [SPIKE-UNRESOLVED] + continue
   │
   ▼
[GATE 3] ← PAUSE — confirm fit check, greenlight breadboarding
   ▼
[B0] Fat Marker Sketch (UI-heavy features only; skip otherwise)
   ▼
[B1] Identify Places
   ▼
[B2–B3] Map Affordances + Tables
   │  → keep affordance count minimal; remove any not required by an R
   ▼
[GATE 4] ← PAUSE — confirm affordance tables
   ▼
[B4] Wiring Verification (fix smells inline; do not stop)
   ▼
[B5] Slicing
   │  → ≤9 slices; each slice = one demonstrable capability
   ▼
[KICKOFF-READY] — assert before writing output files:
   ✅ appetite is set  ✅ all spikes resolved (or SPIKE-UNRESOLVED documented)
   ✅ rabbit holes listed  ✅ fit check clean  ✅ ≤9 slices
   ▼
OUTPUT: shaping.md + breadboard.md (+ spike-[part].md if applicable)
        → kicked-off pitch, ready for /ba-pitch-analyzer or /tech-lead

Progress Markers

▶ S1 — Problem Frame + Appetite
▶ S2 — Requirements
▶ S2.5 — Rabbit Holes + No-goes
⏸ GATE 1 — Confirming requirements + rabbit holes...
▶ S3 — Solution Shape
⏸ GATE 2 — Confirming shape + constraints...
▶ S4 — Fit Check
⏸ GATE 3 — Greenlight breadboarding...
▶ B1 — Places
▶ B2-B3 — Affordances
⏸ GATE 4 — Confirming affordance tables...
▶ B4 — Wiring Verification
▶ B5 — Slices
✅ KICKOFF-READY — shaping.md + breadboard.md written (kicked-off pitch)

WORKFLOW 1 — /shapeup shaping

Load resource: resources/shaping.md

Purpose: Iterate on both the problem (requirements) and solution (shapes) before committing to implementation. Stop here — do not slice yet.

Ends when: Every requirement maps to a shape part. Unknowns are flagged for spikes.

For full phase detail (S1→S4, output format, common mistakes) → read resources/shaping.md.

WORKFLOW 2 — /shapeup spike

Load resource: resources/spike.md

Purpose: De-risk an unknown before breadboarding. Time-boxed investigation that answers a specific question so the breadboard can be grounded in fact.

For full spike process, output format, and SPIKE-UNRESOLVED fallback → read resources/spike.md.

WORKFLOW 3 — /shapeup breadboarding

Load resource: resources/breadboarding.md

Purpose: Take the shaped solution and map every UI affordance, code affordance, and wiring relationship. Then slice into vertical implementation scopes.

Input required: A shaping.md with a completed fit check. All spikes resolved.

For full phase detail (B0→B5), core concepts (Places, affordances, wiring), Mermaid conventions, slicing rules, verification checks, and worked examples → read resources/breadboarding.md.

Key things in the resource:

• Blocking test for Places
• Place IDs + navigation wiring pattern
• Mermaid color conventions + classDef snippets
• Chunking pattern for complex subsystems
• Slice summary format + visualization
• Verification checklist

WORKFLOW 4 — /shapeup framing-doc

Load resource: resources/framing-doc.md

Purpose: Turn a conversation transcript into a structured framing document. GIGO warning applies — formats and distills only.

For full phases (F1→F3) and output template → read resources/framing-doc.md.

WORKFLOW 5 — /shapeup kickoff-doc

Load resource: resources/kickoff-doc.md

Purpose: Turn a shaped project kickoff transcript into a builder reference document. GIGO warning applies.

For full phases (K1→K3) and output template → read resources/kickoff-doc.md.

WORKFLOW 6 — /shapeup breadboard-reflection

Load resource: resources/breadboard-reflection.md

Purpose: Review an existing breadboard for design smells and structural issues. Fix wiring, naming, and causality problems before handing off to implementation.

For full smell catalog (naming / wiring / causality / scope) and review process → read resources/breadboard-reflection.md.

Document Structure

All shaping source documents go in: shapeup/[feature-slug]/shaping/

shapeup/[feature-slug]/shaping/
├── frame.md          ← /shapeup framing-doc (team context only)
├── shaping.md        ← /shapeup shaping  (problem + R + A + fit check)
├── spike-[part].md   ← /shapeup spike    (one file per unknown)
├── breadboard.md     ← /shapeup breadboarding  (affordances + slices)
└── kickoff.md        ← /shapeup kickoff-doc (team context only)

All source files must have shaping: true in YAML frontmatter so the ripple-check activates. Paths are project-relative (resolved from the project root / cwd) — never /mnt/..., which is the authoring sandbox and dies in a user repo.

Run Workspace & Digest

Two roots, separated by artifact nature (full design → resources/context-compaction.md). Both key off the feature <slug>:

• Shared root shapeup/[slug]/ = what the team contributes to (source + deliverable). Local root .shapeup/[slug]/ = per-run scratch, hidden and fully gitignorable. Add one line to .gitignore: .shapeup/. No carve-out needed — everything machine-written at run time, including the harvest shards .shapeup/metrics/*.jsonl, lives under the local root.
• digest.md is the run's derived decision context (the 4-field, two-zone read model the gates consume). It is never the source of truth and never crosses a skill boundary — ba-pitch-analyzer reads pitch.md/shaping.md, never the digest.
• Ripple-check rule (mandatory): the digest carries no shaping: true — it is a sink, not a node. The ripple-check must glob-exclude .shapeup/, or it will scan the digest as a source and ripple incorrectly.

Integration with ba-pitch-analyzer

/shapeup shaping          → shaping.md
/shapeup spike            → spike-[part].md  (as needed)
/shapeup breadboarding    → breadboard.md (with slices)
         ↓
/ba-pitch-analyzer shapeup/[feature-slug]/shaping/shaping.md
         ↓
shapeup/[feature-slug]/spec/  (domain model, contracts, use cases, tasks)

Reference affordance IDs (U[N], N[N]) in task descriptions and commit messages to maintain traceability: breadboard → task → commit.