Skill: borahm/shaping (version 1.0.0)

--- name: shaping description: Shape Up methodology for product and feature development. Use when collaboratively shaping a solution — iterating on problem definition (requirements) and solution options (shapes), breadboarding systems into affordances and wiring, and slicing into vertical implementation increments. Triggers include "shape this feature", "breadboard the system", "let's shape", "slice this into increments", "fit check", "define requirements", or any product/feature scoping discussion using Shape Up methodology. --- # Shaping & Breadboarding Structured methodology for defining problems, exploring solutions, and planning implementation. Based on [Shape Up](https://basecamp.com/shapeup) adapted for working with an LLM. Source: [rjs/shaping-skills](https://github.com/rjs/shaping-skills) by [@rjs](https://github.com/rjs) (Ryan Singer, author of [Shape Up](https://basecamp.com/shapeup)) ## Two Skills in One **Shaping** — Iterate on problem (requirements) and solution (shapes) before committing to implementation. Separates what you need from how you might build it, with fit checks to see what's solved and what isn't. **Breadboarding** — Map a system into UI affordances, code affordances, and wiring. Shows what users can do and how it works underneath in one view. Good for slicing into vertical scopes. ## When to Use - Exploring a new feature or product direction - Comparing solution approaches before building - Mapping an existing system to understand where changes land - Breaking a selected solution into vertical implementation slices - Any "should we build X or Y?" discussion ## Entry Points - **Start from R (Requirements)** — Describe the problem, pain points, constraints. Build up requirements and let shapes emerge. - **Start from S (Shapes)** — Sketch a solution already in mind. Capture it as a shape and extract requirements as you go. No required order. R and S inform each other throughout. ## Core Notation | Level | Notation | Meaning | Relationship | |-------|----------|---------|--------------| | Requirements | R0, R1, R2... | Problem constraints | Members of set R | | Shapes | A, B, C... | Solution options | Pick one from S | | Components | C1, C2, C3... | Parts of a shape | Combine within shape | | Alternatives | C3-A, C3-B... | Approaches to a component | Pick one per component | ## Phases ``` Shaping → Slicing ``` - **Shaping**: Explore problem/solution space, select and detail a shape - **Slicing**: Break down for implementation into vertical slices with demo-able UI ## Key Actions - **Populate R** — Gather requirements as they emerge - **Sketch a shape** — Propose a high-level approach - **Detail** — Break shape into components or concrete affordances - **Check fit** — Build decision matrix (R × S), binary ✅/❌ only - **Breadboard** — Map to UI/Code affordances with wiring - **Spike** — Investigate unknowns - **Slice** — Break breadboarded shape into vertical increments ## Detailed Reference For the complete methodology, notation rules, examples, and procedures: - **Shaping reference**: See [references/shaping.md](references/shaping.md) — Full shaping methodology including fit checks, parts, spikes, documents, multi-level consistency - **Breadboarding reference**: See [references/breadboarding.md](references/breadboarding.md) — Complete breadboarding procedure, affordance tables, places, wiring, Mermaid conventions, chunking, slicing Load the relevant reference when entering that phase of work. ## Quick Reference: Fit Check Format ```markdown | Req | Requirement | Status | A | B | C | |-----|-------------|--------|---|---|---| | R0 | Full requirement text | Core goal | ✅ | ✅ | ✅ | | R1 | Full requirement text | Must-have | ✅ | ❌ | ✅ | ``` - Always show full requirement text, never abbreviate - Binary only: ✅ or ❌. No ⚠️ in fit checks - Explanations go in Notes section below the table ## Quick Reference: Affordance Tables **UI Affordances**: `# | Place | Component | Affordance | Control | Wires Out | Returns To` **Code Affordances**: Same columns **Controls**: click, type, call, observe, write, render **Wires Out** (solid →): Control flow — calls, triggers, writes **Returns To** (dashed -.->): Data flow — return values, reads ## Quick Reference: Slicing - Every slice must end in **demo-able UI** - Max 9 slices - Each slice demonstrates a mechanism working - Format: `V1: Name` — affordances, demo statement

path: references/breadboarding.md
content: # Breadboarding Reference

Transform workflow descriptions into affordance tables showing UI and Code affordances with their wiring.

## Table of Contents

1. Core Concepts (Places, Affordances, Wiring)
2. Affordance Tables Format
3. Procedure: Mapping Existing System
4. Procedure: Designing from Shaped Parts
5. Places Deep Dive
6. Verification Checks
7. Mermaid Visualization
8. Chunking
9. Slicing

## Core Concepts

### Places

A Place is a bounded context of interaction. While in a Place, you have specific affordances and cannot interact outside that boundary.

**Blocking Test**: Can you interact with what's behind? No → different Place. Yes → same Place.

| UI Element | Place? | Why |
|------------|--------|-----|
| Modal | Yes | Can't interact with page behind |
| Edit mode (whole screen) | Yes | All affordances changed |
| Dropdown menu | No | Can click away |
| Checkbox reveals fields | No | Surroundings unchanged |

### Place IDs

| # | Place | Description |
|---|-------|-------------|
| P1 | Page Name | Standard page |
| P2 | Page (Edit Mode) | Mode variant |
| P2.1 | widget-name | Subplace within P2 |
| P3 | Modal Name | Modal dialog |

### Affordances

- **UI (U)**: inputs, buttons, displays, scroll regions
- **Code (N)**: methods, subscriptions, stores, framework mechanisms
- **Data Store (S)**: state that persists and is read/written

### Wiring

- **Wires Out** (solid →): Control flow — calls, triggers, writes, navigation
- **Returns To** (dashed -.->): Data flow — return values, reads

Navigate to Places, not affordances inside: `N1 → P2` not `N1 → U3`.

## Affordance Tables

### UI Affordances

| # | Place | Component | Affordance | Control | Wires Out | Returns To |
|---|-------|-----------|------------|---------|-----------|------------|
| U1 | P1 | search | search input | type | → N1 | — |
| U2 | P1 | search | loading spinner | render | — | — |

### Code Affordances

| # | Place | Component | Affordance | Control | Wires Out | Returns To |
|---|-------|-----------|------------|---------|-----------|------------|
| N1 | P1 | search | activeQuery.next() | call | → N2 | — |
| N2 | P1 | search | performSearch() | call | → N3, → S1 | — |

### Data Stores

| # | Place | Store | Description |
|---|-------|-------|-------------|
| S1 | P1 | results | Array of search results |

### Controls

click, type, call, observe, write, render, config, conditional, signal

## Procedure: Mapping Existing System

1. Identify the flow to analyze (specific user journey)
2. List all places involved
3. Trace through code to find components
4. For each component, list affordances
5. Name the actual thing (never abstractions)
6. Fill Control, Wires Out, Returns To
7. Add data stores and framework mechanisms
8. Verify against code

## Procedure: Designing from Shaped Parts

1. List each part from shape
2. Translate parts into affordances (UI + Code)
3. Verify every U has a supporting N
4. Classify places as existing or new
5. Wire affordances (Wires Out + Returns To)
6. Connect to existing system if applicable
7. Check completeness

## Key Principles

- **Tables are truth** — Mermaid diagrams are optional visualizations
- **Never use memory** — scan Wires Out column systematically
- **Every affordance name must exist** (when mapping) — point to real code
- **Mechanisms aren't affordances** — skip wrappers, transforms, navigation utilities
- **Every U displaying data needs a source** (S or N returning to it)
- **Every N must connect** — handlers need Wires Out, queries need Returns To
- **Side effects need stores** — Browser URL, localStorage, Clipboard as external stores
- **Place stores where consumed**, not where written

### Not Affordances

| Type | Example | Why |
|------|---------|-----|
| Visual containers | modal-frame | Can't act on a wrapper |
| Internal transforms | dataTransform() | Implementation detail |
| Navigation mechanisms | modalService.open() | Just "how" of getting somewhere |

Wire directly to destination instead.

## Place References

When nested place is complex, detach it:
1. Put reference node in parent: `_letter-browser`
2. Define full place separately
3. Wire: `_letter-browser --> letter-browser`

Style with dashed border: `stroke-dasharray:5 5`

## Modes as Places

Edit mode transforms entire screen → separate Places. Use place reference to show composition:
```
P3: component (Read) — base state
P4: component (Edit) — contains _component (Read) + new affordances
```

## Subplaces

Hierarchical IDs: P2.1, P2.2 for subsets within P2. Use placeholder for out-of-scope content:
```
otherContent[["... other page content ..."]]
```

## Verification Checks

| Check | Question |
|-------|----------|
| Every U displaying data | Has incoming wire? |
| Every N | Has Wires Out or Returns To? |
| Every S | Something reads from it? |
| Navigation mechanisms | Wire to Place directly? |
| N with side effects | External store modeled? |

## Chunking

Collapse subsystem with one wire in, one wire out, many internals into single node.

Stadium-shaped node: `dynamicForm[["CHUNK: dynamic-form"]]`
Separate detail diagram with boundary markers: `input([formDefinition])`, `output(["valid$"])`

## Mermaid Conventions

### Line Styles

| Style | Syntax | Use |
|-------|--------|-----|
| Solid | `-->` | Wires Out |
| Dashed | `-.->` | Returns To |
| Labeled | `-.->|...|` | Abbreviated flow |

### Colors

| Type | Color | Hex |
|------|-------|-----|
| UI (U) | Pink | `#ffb6c1` |
| Code (N) | Grey | `#d3d3d3` |
| Store (S) | Lavender | `#e6e6fa` |
| Chunk | Light blue | `#b3e5fc` |

```
classDef ui fill:#ffb6c1,stroke:#d87093,color:#000
classDef nonui fill:#d3d3d3,stroke:#808080,color:#000
classDef store fill:#e6e6fa,stroke:#9370db,color:#000
```

### Subgraph IDs

Use Place ID as subgraph ID: `subgraph P1["P1: Page Name"]`

## Slicing

Break breadboard into vertical implementation increments.

### Rules

- Every slice must have **demo-able UI** (no horizontal layers)
- Max 9 slices
- Each demonstrates a mechanism working

### Procedure

1. Identify minimal demo-able increment → V1
2. Layer capabilities as slices (each demonstrates a mechanism)
3. Assign affordances to slices
4. Create per-slice affordance tables
5. Write demo statement for each slice

### Slice Summary Format

| # | Slice | Mechanism | Affordances | Demo |
|---|-------|-----------|-------------|------|
| V1 | Widget with data | F1, F4 | U2-U5, N3-N8 | "Shows real data" |
| V2 | Search works | F3 | U1, N1, N2 | "Type to filter" |

### Visualizing Slices

| Category | Style |
|----------|-------|
| This slice | Bright color |
| Already built | Solid grey |
| Future | Transparent, dashed |

Slice colors: V1 `#e8f5e9` green, V2 `#e3f2fd` blue, V3 `#fff3e0` orange, V4 `#f3e5f5` purple, V5 `#fff8e1` yellow, V6 `#fce4ec` pink

### Sliced Breadboard

Wrap affordances in colored slice subgraphs. Use invisible links for ordering: `slice1 ~~~ slice2`. Make nested subgraphs transparent.


path: references/shaping.md
content: # Shaping Reference

Complete methodology for collaboratively defining problems and exploring solution options.

## Table of Contents

1. Multi-Level Consistency
2. Starting a Session
3. Requirements (R)
4. Shapes (S)
5. Fit Check
6. Shape Parts
7. Spikes
8. Documents
9. Big Picture

## Multi-Level Consistency

Shaping produces documents at different levels of abstraction. Truth must stay consistent across all levels.

### Document Hierarchy (high to low)

1. **Big Picture** — highest level, quick context acquisition
2. **Shaping doc** — ground truth for R's, shapes, parts, fit checks
3. **Slices doc** — ground truth for slice definitions, breadboards
4. **Individual slice plans** (V1-plan, etc.) — ground truth for implementation details

Each level summarizes levels below it. Changes ripple in both directions. Never let documents drift out of sync.

## Starting a Session

Offer both entry points:
- **Start from R** — Describe problem, pain points, constraints
- **Start from S** — Sketch a solution, extract requirements as you go

When shaping doc already has a selected shape: display fit check for selected shape only, summarize what is unsolved.

## Requirements (R)

Numbered set defining the problem space: R0, R1, R2...

- Negotiated collaboratively, not filled in automatically
- Track status: Core goal, Undecided, Leaning yes/no, Must-have, Nice-to-have, Out
- Requirements extracted from fit checks should be standalone (not shape-dependent)
- R states what's needed, not what's satisfied — satisfaction shown in fit check

## Shapes (S)

Letters represent mutually exclusive solution approaches.

- **A, B, C...** = top-level options (pick one)
- **C1, C2, C3...** = components/parts of Shape C (combine)
- **C3-A, C3-B...** = alternatives for component C3 (pick one)

### Shape Titles

Give shapes short descriptive titles:
- ✅ "E: Modify CUR in place to follow S-CUR"
- ❌ "E: The solution" (too vague)

### Notation Persistence

Keep notation as audit trail. Compose new options by referencing prior components (e.g., "Shape E = C1 + C2 + C3-A").

## Fit Check (Decision Matrix)

THE single table comparing all shapes against all requirements.

### Format

```markdown
| Req | Requirement | Status | A | B | C |
|-----|-------------|--------|---|---|---|
| R0 | Make items searchable | Core goal | ✅ | ✅ | ✅ |
| R1 | State survives refresh | Must-have | ✅ | ❌ | ✅ |

**Notes:**
- B fails R1: [brief explanation]
```

### Rules

- **Always show full requirement text** — never abbreviate
- **Binary only**: ✅ or ❌. No ⚠️, no other symbols
- **Shape columns contain only ✅ or ❌** — explanations in Notes
- If a shape passes all checks but feels wrong → missing requirement. Add new R.

## Shape Parts

Parts describe what we BUILD or CHANGE — mechanisms, not intentions.

### Parts Table

```markdown
| Part | Mechanism | Flag |
|------|-----------|:----:|
| F1 | Create widget (component, def, register) | |
| F2 | Magic authentication handler | ⚠️ |
```

- Empty flag = mechanism understood
- ⚠️ = flagged unknown — WHAT described but HOW unknown
- Flagged unknowns FAIL fit checks (⚠️ → ❌)

### Rules

- Parts must be mechanisms, not intentions or constraints
- Avoid tautologies between R and S — shape should add specificity about *how*
- Parts should be vertical slices, not horizontal layers
- Extract shared logic as standalone parts others reference
- Use hierarchical notation (E1.1, E1.2) only when needed for clarity

## Spikes

Investigation tasks to learn how existing system works and what steps are needed.

### Structure

```markdown
## [Component] Spike: [Title]

### Context
Why we need this investigation.

### Goal
What we're trying to learn.

### Questions
| # | Question |
|---|----------|
| X1-Q1 | Specific question about mechanics |

### Acceptance
Spike complete when all questions answered and we can describe [understanding].
```

- Always create in own file (e.g., `spike-[topic].md`)
- Acceptance = information/understanding, not conclusions
- Questions ask about mechanics, not effort

## Documents

| Document | Contains | Purpose |
|----------|----------|---------|
| Big Picture | Frame + Shape + Slices summary | Quick context |
| Frame | Source, Problem, Outcome | The "why" |
| Shaping doc | R, Shapes, Affordances, Breadboard, Fit Check | Working document |
| Slices doc | Slice details, per-slice affordances, wiring | Implementation plan |

### Frame

Contains:
- **Source** — Original requests, quotes (verbatim)
- **Problem** — What's broken, what pain exists
- **Outcome** — What success looks like

Always capture source material verbatim.

### Lifecycle

```
Frame → Shaping → Slices → Big Picture (summarizes all)
```

## Big Picture

One-page summary: Frame + Shape (fit check, parts, breadboard) + Slices (sliced breadboard + grid).

### Structure

```markdown
# [Feature] — Big Picture

**Selected shape:** [Letter] ([Description])

## Frame
### Problem
- [bullet list]
### Outcome  
- [bullet list]

## Shape
### Fit Check (R × [Selected Shape])
### Parts
### Breadboard

## Slices
[Sliced breadboard + Grid]
```

### Slices Grid Format

```markdown
|  |  |  |
|:--|:--|:--|
| **[V1: NAME](./v1-plan.md)**<br>⏳ PENDING<br><br>• Item 1<br>• Item 2<br><br>*Demo: description* | ... | ... |
```

Slice colors: V1 green, V2 blue, V3 orange, V4 purple, V5 yellow, V6 pink.

## Possible Actions (Any Order)

- Populate R, Sketch shape, Detail (components), Detail (affordances)
- Explore alternatives, Check fit, Extract Rs
- Breadboard, Spike, Decide, Create Big Picture, Slice

## Communication

Always show full tables — every row, every requirement, every part. Never summarize or abbreviate. The full table is the artifact.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)