breadboarding

# Breadboarding

## Purpose

Produce a Shape Up style breadboard that is concrete enough to guide a build, without collapsing into pixel-perfect UI spec or a full-code hairball.

Based on Shape Up and Ryan Singer's work.

Treat **affordances** as the simplifying primitive.

- **UI affordances**: things a user can do (type, click, scroll) or see (states/messages) that matter to the flow.
- **Code affordances**: things the system can do (call a function, observe an observable, write/read state, navigate) that cause the UI affordances to change.

Use those to build a lightweight model of the current system and the proposed change.

## When to use

- Reach the “rough out the elements” stage and need to turn an idea into buildable parts.
- Shape a change to a **pre-existing system** and need to understand what the system actually does today.
- Compare a new concept against an existing feature and decide whether to **duplicate vs extract** shared logic.
- Pick up a shaping effort after a gap and need a fast re-orientation: current state, chosen approach, and what’s still unsolved.

## Inputs to request or infer

Prefer working with whatever exists. If inputs are missing, use `ask-questions-if-underspecified` skill

- Appetite / timebox and any hard boundaries.
- Problem statement and success definition.
- Brief (problem, goals, in/out scope). If missing, pause and draft a brief first.
- Requirements list (or a rough list of must-haves).
- Entry point(s): where the user starts, how they discover the feature.
- Existing system context: routes/screens, key components, services, data stores.
- Any comparable feature(s) to analyse for reuse.

## Workflow

### 1) Establish the “right level of abstraction”

- Avoid full wireframes and visual design.
- Prefer **words** and **connections** over pictures.
- Focus on “what’s connected to what” (topology) and “what changes state”.

Use the breadboard primitives:

- **Places**: screens/pages/modals/menus that can be navigated to.
- **Affordances**: actions and information at a place (buttons, fields, copy, empty/loading states).
- **Connection lines**: how an affordance moves between places or triggers work.

### 2) Breadboard the user flow

- Start at the entry place.
- List the minimum affordances needed to serve the use case.
- Draw (describe) connection lines for navigation and “cause/effect” transitions.

Stop when the flow answers these shaping questions:

- Where in the current system does the new thing fit?
- How does a user get to it?
- What are the key components/interactions?
- Where does it take the user next?

### 3) Inventory UI affordances

Create a numbered list (recommended prefix **U**):

For each UI affordance, record:

- **ID**: U1, U2…
- **Component / place**: where it lives
- **Affordance**: “search input”, “loading spinner”, “no results message”, etc
- **Control**: type/click/scroll/render/iterate
- **Wires out**: what it triggers (calls, navigation, messages)
- **Reads** (optional): what state/data it depends on

Keep UI affordances at the interaction level, not implementation detail.

### 4) Inventory code affordances

Create a numbered list (recommended prefix **N**):

For each code affordance, record:

- **ID**: N1, N2…
- **Component/service**: where it lives
- **Affordance**: function, observable subscription, store write/read
- **Control**: call/observe/write/read
- **Wires out**: what it calls, writes, triggers, or returns

Interpretation rule:

- If it’s something that can be “operated” from a whole-system POV to make something happen, it’s an affordance.

### 5) Build a wiring diagram from affordances

Convert the inventories into a simple directed graph using `beautiful-mermaid` skill.

- Nodes: places, UI affordances, code affordances, external services, browser events.
- Edges:
  - **Solid** for “wires out”: calls, triggers, writes
  - **Dashed** for “returns/reads”: return values, store reads

Keep it legible:

- Draw only the parts touched by the change.
- Collapse deep internals into a single node when they aren’t central to the shaped behaviour.
- If it becomes a hairball, split into sub-diagrams per place or per flow.

Required output format (both, not either/or):

1) **Source code**: include Mermaid source in a fenced ```mermaid block in the Markdown artefact.
2) **Static render**: generate and save a rendered diagram asset (SVG preferred) via `beautiful-mermaid`, and embed it in the Markdown artefact.
3) **Fallback**: also generate a terminal-safe ASCII/Unicode render (`.txt`) when practical.

Compatibility note:
- Some Markdown/SVG renderers (for example Zed) do not fully support CSS variables or `color-mix()` inside SVG.
- If the render appears as black blocks, post-process the SVG to use literal color values (hex) for fill/stroke/text.

Naming convention (recommended):

- `<doc-base>-wiring.svg`
- `<doc-base>-wiring.txt`

Place static assets adjacent to the breadboard Markdown file so links stay portable.
Use template `references/templates/wiring-diagram-mermaid-template.md`.

### 6) Produce a parts list (BOM)

Write a numbered parts list (recommended prefix **F** for “shape/feature parts”):

- Each part is a buildable chunk with a clear mechanism.
- Include deletes/migrations explicitly (e.g., “remove letters from widget-grid”).

For each part:

- Name the part
- Summarise the mechanism in 1–2 lines
- Call out notable trade-offs (scope cuts, simplifications)

Use `references/templates/parts-bom-template.md`.

### 7) Fit check: requirements × concept

Create a simple table:

- Rows: requirements (R0…)
- Columns:
  - requirement statement
  - status (core goal / must-have / nice-to-have / out / undecided)
  - fit with current concept (✅/❌/⚠️)

Then:

- Call out the **unsolved** requirement(s) as explicit shaping questions.
- Identify the decision needed (product/UX judgement vs technical unknown vs policy).

Use `references/templates/fit-check-template.md`.

### 8) Duplicate vs extract analysis (when overlap exists)

When a new change overlaps an existing feature, decide reuse via an **affordances overlap** rather than vibes.

Steps:

- Identify the comparable feature (existing) and the new concept.
- List shared affordances and divergent affordances.
- Compare requirements that drive divergence (URL shape, guards, state model, pagination mode, etc).
- Estimate the real code coupling cost vs the amount of duplication avoided.

Produce:

- A “Keep Shared vs Duplicate” table
- A recommendation (default bias: duplicate feature-level orchestration; extract infrastructure-level types/utilities)
- 3–5 concrete reasons, with emphasis on:
  - **divergent requirements**
  - **lines of code vs coupling cost**

Use `references/templates/extract-vs-duplicate-template.md`.

### 9) Package the breadboard as a single artefact

Output a “Breadboard Pack” as Markdown:

- Current State (what exists today)
- Proposed Breadboard (places, affordances, connections)
- UI Affordances table
- Code Affordances table
- Wiring diagram:
  - embedded static image link (`.svg`)
  - Mermaid code block (source of truth)
  - optional `.txt` fallback path
- Parts/BOM
- Fit check + unsolved questions
- Rabbit holes / out-of-bounds / cuts
- Optional: extract vs duplicate analysis

Use `references/templates/breadboard-pack-template.md`.

## Quality bar

- Stay rough, but solved: enough detail to unblock building, not enough to constrain visual design.
- Keep a consistent numbering scheme (U*, N*, R*, F*).
- Make every edge in the wiring diagram traceable back to an affordance row.
- Ensure diagram portability: a reader without Mermaid support must still see the static diagram.
- Prefer small, explicit trade-offs over implied complexity.

## Bundled resources

- `references/shapeup-breadboarding-notes.md` — summary of Shape Up breadboarding concepts.
- `references/templates/*` — reusable templates for breadboard pack, tables, diagrams, fit checks.
- `references/templates/brief-template.md` — brief template used by the brief skill.
- `references/examples/letter-search-example.md` — an end-to-end example using UI+code affordances.
- `scripts/render_mermaid_from_edges.py` — optional helper: JSON edge list -> Mermaid code (render via `beautiful-mermaid`)