Use this methodology when collaboratively shaping a solution with the user - iterating on problem definition (requirements) and solution options (shapes).

Shaping Methodology A structured approach for collaboratively defining problems and exploring solution options. Multi Level Consistency (Critical) Shaping produces documents at different levels of abstraction. Truth must stay consistent across all levels. The Document Hierarchy (high to low) 1. Shaping doc — ground truth for R's, shapes, parts, fit checks 2. Slices doc — ground truth for slice definitions, breadboards 3. Individual slice plans (V1 plan, etc.) — ground truth for implementation details The Principle Each level summarizes or provides a view into the level(s) below it. Lower levels contain more detail; higher levels are designed views that help acquire context quickly. Changes ripple in both directions: Change at high level → trickles down: If you change the shaping doc's parts table, update the slices doc too. Change at low level → trickles up: If a slice plan reveals a new mechanism or changes the scope of a slice, the Slices doc and shaping doc must reflect that. The Practice Whenever making a change: 1. Identify which level you're touching 2. Ask: "Does this affect documents above or below?" 3. Update all affected levels in the same operation 4. Never let documents drift out of sync The system only works if the levels are consistent with each other. Starting a Session When kicking off a new shaping session, offer the user both entry points: Start from R (Requirements) — Describe the problem, pain points, or 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. There is no required order. Shaping is iterative — R and S inform each other throughout. Working with an Existing Shaping Doc When the shaping doc already has a selected shape: 1. Display the fit check for the selected shape only — Show R × [selected shape] (e.g., R × F), not all shapes 2. Summarize what is unsolved — Call out any requirements that are Undecided, or where the selected shape has ❌ This gives the user immediate context on where the shaping stands and what needs attention. Core Concepts R: Requirements A numbered set defining the problem space. R0, R1, R2... are members of the requirements set Requirements are 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 made standalone (not dependent on any specific shape) R states what's needed, not what's satisfied — satisfaction is always shown in a fit check (R × S) Chunking policy: Never have more than 9 top level requirements. When R exceeds 9, group related requirements into chunks with sub requirements (R3.1, R3.2, etc.) so the top level stays at 9 or fewer. This keeps the requirements scannable and forces meaningful grouping. S: Shapes (Solution Options) Letters represent mutually exclusive solution approaches. A, B, C... are top level shape options (you pick one) C1, C2, C3... are components/parts of Shape C (they combine) C3 A, C3 B, C3 C... are alternative approaches to component C3 (you pick one) Shape Titles Give shapes a short descriptive title that characterizes the approach. Display the title when showing the shape: Good titles capture the essence of the approach in a few words: ✅ "E: Modify CUR in place to follow S CUR" ✅ "C: Two data sources with hybrid pagination" ❌ "E: The solution" (too vague) ❌ "E: Add search to widget grid by swapping..." (too long) Notation Hierarchy 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 Notation Persistence Keep notation throughout as an audit trail. When finalizing, compose new options by referencing prior components (e.g., "Shape E = C1 + C2 + C3 A"). Phases Shaping moves through two phases: Phase Purpose Output Shaping Explore the problem and solution space, select and detail a shape Shaping doc with R, shapes, fit checks, breadboard Slicing Break down for implementation Vertical slices with demo able UI Phase Transition Shaping → Slicing happens when: A shape is selected (passes fit check, feels right) The shape has been breadboarded into concrete affordances We need to plan implementation order You can't slice without a breadboarded shape. Fit Check (Decision Matrix) THE fit check is the single table comparing all shapes against all requirements. Requirements are rows, shapes are columns. This is how we decide which shape to pursue. Format Conventions Always show full requirement text — never abbreviate or summarize requirements in fit checks Fit check is BINARY — Use ✅ for pass, ❌ for fail. No other values. Shape columns contain only ✅ or ❌ — no inline commentary; explanations go in Notes section Never use ⚠️ or other symbols in fit check — ⚠️ belongs only in the Parts table's flagged column Keep notes minimal — just explain failures Comparing Alternatives Within a Component When comparing alternatives for a specific component (e.g., C3 A vs C3 B), use the same format but scoped to that component: Missing Requirements If a shape passes all checks but still feels wrong, there's a missing requirement. Articulate the implicit constraint as a new R, then re run the fit check. Macro Fit Check A separate tool from the standard fit check, used when working at a high level with chunked requirements and early stage shapes where most mechanisms are still ⚠️. Use when explicitly requested. The macro fit check has two columns per shape instead of one: Addressed? — Does some part of the shape seem to speak to this requirement at a high level? Answered? — Can you trace the concrete how? Is the mechanism actually spelled out? Format: Conventions: Only show top level requirements (R0, R1, R2...), not sub requirements No notes column — keep the table narrow and scannable Use ✅ (yes), ⚠️ (partially), ❌ (no) for Addressed Use ✅ (yes) or ❌ (no) for Answered Follow the macro fit check with a separate Gaps table listing specific missing parts and their related sub requirements Possible Actions These can happen in any order: Populate R Gather requirements as they emerge Sketch a shape Propose a high level approach (A, B, C...) Detail (components) Break a shape into components (B1, B2...) Detail (affordances) Expand a selected shape into concrete UI/Non UI affordances and wiring Explore alternatives For a component, identify options (C3 A, C3 B...) Check fit Build a fit check (decision matrix) playing options against R Extract Rs When fit checks reveal implicit requirements, add them to R as standalone items Breadboard Map the system to understand where changes happen and make the shape more concrete Spike Investigate unknowns to identify concrete steps needed Decide Pick alternatives, compose final solution Slice Break a breadboarded shape into vertical slices for implementation Communication Show Full Tables When displaying R (requirements) or any S (shapes), always show every row — never summarize or abbreviate. The full table is the artifact; partial views lose information and break the collaborative process. Show all requirements, even if many Show all shape parts, including sub parts (E1.1, E1.2...) Show all alternatives in fit checks Why This Matters Shaping is collaborative negotiation. The user needs to see the complete picture to: Spot missing requirements Notice inconsistencies Make informed decisions Track what's been decided Summaries hide detail and shift control away from the user. Mark Changes with 🟡 When re rendering a requirements table or shape table after making changes, mark every changed or added line with a 🟡 so the user can instantly spot what's different. Place the 🟡 at the start of the changed cell content. This makes iterative refinement easy to follow — the user should never have to diff the table mentally. Spikes A spike is an investigation task to learn how the existing system works and what concrete steps are needed to implement a component. Use spikes when there's uncertainty about mechanics or feasibility. File Management Always create spikes in their own file (e.g., spike.md or spike [topic].md ). Spikes are standalone investigation documents that may be shared or worked on independently from the shaping doc. Purpose Learn how the existing system works in the relevant area Identify what we would need to do to achieve a result Enable informed decisions about whether to proceed Not about effort — effort is implicit in the steps themselves Investigate before proposing — discover what already exists; you may find the system already satisfies requirements Structure Acceptance Guidelines Acceptance describes the information/understanding we'll have, not a conclusion or decision: ✅ "...we can describe how users set their language and where non English titles appear" ✅ "...we can describe the steps to implement [component]" ❌ "...we can answer whether this is a blocker" (that's a decision, not information) ❌ "...we can decide if we should proceed" (decision comes after the spike) The spike gathers information; decisions are made afterward based on that information. Question Guidelines Good spike questions ask about mechanics: "Where is the [X] logic?" "What changes are needed to [achieve Y]?" "How do we [perform Z]?" "Are there constraints that affect [approach]?" Avoid: Effort estimates ("How long will this take?") Vague questions ("Is this hard?") Yes/no questions that don't reveal mechanics Breadboards Use the /breadboarding skill to map existing systems or detail a shape into concrete affordances. Breadboarding produces: UI Affordances table Non UI Affordances table Wiring diagram grouped by Place Invoke breadboarding when you need to: Map existing code to understand where changes land Translate a high level shape into concrete affordances Reveal orthogonal concerns (parts that are independent of each other) Tables Are the Source of Truth The affordance tables (UI and Non UI) define the breadboard. The Mermaid diagram renders them. When receiving feedback on a breadboard: 1. First — update the affordance tables (add/remove/modify affordances, update Wires Out) 2. Then — update the Mermaid diagram to reflect those changes Never treat the diagram as the primary artifact. Changes flow from tables → diagram, not the reverse. CURRENT as Reserved Shape Name Use CURRENT to describe the existing system. This provides a baseline for understanding where proposed changes fit. Shape Parts Flagged Unknown (⚠️) A mechanism can be described at a high level without being concretely understood. The Flag column tracks this: Part Mechanism Flag : : F1 Create widget (component, def, register) F2 Magic authentication handler ⚠️ Empty = mechanism is understood — we know concretely how to build it ⚠️ = flagged unknown — we've described WHAT but don't yet know HOW Why flagged unknowns fail the fit check: 1. ✅ is a claim of knowledge — it means "we know how this shape satisfies this requirement" 2. Satisfaction requires a mechanism — some part that concretely delivers the requirement 3. A flag means we don't know how — we've described what we want, not how to build it 4. You can't claim what you don't know — therefore it mu