shapeup-sdlc 1.6.2

package/skills/shapeup/resources/breadboarding.md

@@ -0,0 +1,334 @@
+# Breadboarding — Reference
+
+> Source: rjs/shaping-skills (upstream). Loaded on demand by the shapeup skill.
+
+---
+
+## What Breadboarding Does
+
+Breadboarding transforms a workflow description (existing system or shaped parts) into a complete map of **affordances** and their **relationships**. The output is always a set of tables showing numbered UI and Code affordances with their Wires Out and Returns To relationships.
+
+**The tables are the truth. Mermaid diagrams are optional visualizations.**
+
+---
+
+## Use Cases
+
+### 1. Mapping an Existing System
+
+Input:
+- Code repo(s) to analyze
+- Workflow description (always from the perspective of an operator trying to make an effect happen — through UI or as a caller)
+
+Output:
+- UI Affordances table
+- Code Affordances table
+- (Optional) Mermaid visualization
+
+Note: If the workflow spans multiple applications (frontend + backend), create ONE breadboard. Label places to show which system they belong to.
+
+### 2. Designing from Shaped Parts
+
+Input:
+- Parts list (mechanisms from shaping)
+- The R (requirement/outcome) the parts are meant to achieve
+- Existing system (optional) — if the new parts must interoperate with existing code
+
+### 3. Mixtures
+
+Often you have both: an existing system that must remain as-is, plus new pieces or changes defined in a shape. Breadboard both together — existing affordances and new ones — showing how they connect.
+
+---
+
+## Core Concepts
+
+### Places
+
+A Place is a **bounded context of interaction**. While you're in a Place:
+- You have a specific set of affordances available to you
+- You **cannot** interact with affordances outside that boundary
+- You must take an action to leave
+
+**Place is perceptual, not technical.** It's not about URLs or components — it's about what the user experiences as their current context.
+
+#### The Blocking Test
+
+The simplest test for whether something is a different Place: **Can you interact with what's behind?**
+
+| Answer | Meaning |
+|--------|---------|
+| **No** | You're in a different Place |
+| **Yes** | Same Place, with local state changes |
+
+#### Examples
+
+| UI Element | Blocking? | Place? | Why |
+|---|---|---|---|
+| Modal | Yes | Yes | Can't interact with page behind |
+| Confirmation popover | Yes | Yes | Must respond before returning |
+| Edit mode (whole screen transforms) | Yes | Yes | All affordances changed |
+| Checkbox reveals extra fields | No | No | Surroundings unchanged |
+| Dropdown menu | No | No | Can click away, non-blocking |
+| Tooltip | No | No | Informational, non-blocking |
+
+#### Mode-Based Places
+
+When a mode transforms the entire screen — different buttons, different affordances everywhere — model as separate Places:
+
+```
+PLACE: CMS Page (Read Mode)
+PLACE: CMS Page (Edit Mode)
+```
+
+#### Labeling Conventions
+
+| Pattern | Use |
+|---|---|
+| `PLACE: Page Name` | Standard page/route |
+| `PLACE: Page Name (Mode)` | Mode-based variant |
+| `PLACE: Modal Name` | Modal dialog |
+| `PLACE: Backend` | API/database boundary |
+
+### Place IDs
+
+Each Place gets an ID. IDs enable explicit navigation wiring and Mermaid subgraph matching.
+
+| # | Place | Description |
+|---|---|---|
+| P1 | CMS Page (Read Mode) | View-only state |
+| P2 | CMS Page (Edit Mode) | Editing state |
+| P2.1 | widget-grid (subplace) | Letter editing widget within P2 |
+| P3 | Letter Form Modal | Form for adding/editing |
+| P4 | Backend | API resolvers and database |
+
+### Navigation Wiring
+
+Wire to the **Place itself**, not to an affordance inside:
+
+```
+✅ N1 Wires Out: → P2          (navigate to Edit Mode)
+❌ N1 Wires Out: → U3          (affordance inside P2)
+```
+
+### Affordances
+
+- **UI affordances (U)**: inputs, buttons, displayed elements, scroll regions
+- **Code affordances (N)**: methods, subscriptions, data stores, framework mechanisms
+
+### Wiring
+
+**Wires Out** — control flow (what an affordance triggers or calls):
+- Call wires, write wires, navigation wires
+
+**Returns To** — data flow (where an affordance's output flows):
+- Return wires, read wires
+
+---
+
+## Output Tables
+
+### Places Table
+
+| # | Place | Description |
+|---|---|---|
+| P1 | Search Page | Main search interface |
+| P2 | Detail Page | Individual result view |
+
+### UI Affordances Table
+
+| # | Place | Component | Affordance | Control | Wires Out | Returns To |
+|---|---|---|---|---|---|---|
+| U1 | P1 | search-detail | search input | type | → N1 | — |
+| U2 | P1 | search-detail | loading spinner | render | — | — |
+| U3 | P1 | search-detail | results list | render | — | — |
+| U4 | P1 | search-detail | result row | click | → P2 | — |
+
+### Code Affordances Table
+
+| # | Place | Component | Affordance | Control | Wires Out | Returns To |
+|---|---|---|---|---|---|---|
+| N1 | P1 | search-detail | `activeQuery.next()` | call | → N2 | — |
+| N2 | P1 | search-detail | `activeQuery` subscription | observe | → N3 | — |
+| N3 | P1 | search-detail | `performSearch()` | call | → N4, → N5, → N6 | — |
+| N5 | P1 | search-detail | `loading` | write | store | → U2 |
+| N6 | P1 | search-detail | `results` | write | store | → U3 |
+
+### Data Stores Table
+
+| # | Place | Store | Description |
+|---|---|---|---|
+| S1 | P1 | `results` | Array of search results |
+| S2 | P1 | `loading` | Boolean loading state |
+
+---
+
+## Procedures
+
+### Mapping an Existing System
+
+1. Pick a specific user journey — frame as "operator trying to do something"
+2. Walk through the journey, identify each distinct place
+3. Trace through the code from entry point; find every component touched
+4. For each component, list UI and Code affordances
+5. **Name the actual thing, not an abstraction** — if you write "DATABASE", stop. What's the actual method?
+6. Fill in Control column (what triggers each affordance)
+7. Fill in Wires Out (what does it trigger)
+8. Fill in Returns To (where does its output flow)
+9. Add data stores as affordances (write + read)
+10. Add framework mechanisms (e.g., `cdr.detectChanges()`)
+11. Verify against the code
+
+### Designing from Shaped Parts
+
+1. List each part from the shape
+2. Translate parts into affordances (UI + Code per part)
+3. Verify every U has a supporting N
+4. Classify places as existing or new
+5. Wire the affordances (Wires Out + Returns To)
+6. Connect to existing system if applicable
+7. Check completeness: handlers → Wires Out; queries → Returns To; stores → Returns To
+8. Treat user-visible outputs as Us (emails, notifications)
+
+---
+
+## Key Principles
+
+### Never use memory — always check the data
+When tracing a flow backwards, scan the Wires Out column for ALL affordances that wire to your target. The tables are the source of truth.
+
+### Every affordance name must exist (when mapping)
+Never invent abstractions. Every name must point to something real.
+
+### Mechanisms aren't affordances
+Things that look like affordances but are just implementation details:
+- Visual containers (`modal-frame wrapper`) — just a Place boundary
+- Internal transforms (`letterDataTransform()`) — internal to caller
+- Navigation mechanisms (`modalService.open()`) — wire to destination directly
+
+```
+❌ N8 --> N22 --> P3     (N22 is modalService.open — just mechanism)
+✅ N8 --> P3             (handler navigates to modal)
+```
+
+### Two flows: Navigation and Data
+- **Navigation flow**: Movement from Place to Place (Wires Out → Places)
+- **Data flow**: How state populates displays (Returns To → Us)
+
+Trace both flows when reviewing a breadboard.
+
+### Every U that displays data needs a source
+```
+❌ U6: letter list (no incoming wire)
+✅ S1 -.-> U6 (store feeds the display)
+```
+
+### Every N must connect
+- Handlers → should have Wires Out
+- Queries → should have Returns To
+- Data stores → should have Returns To
+
+### Backend is a Place
+The database and resolvers aren't floating infrastructure — they're a Place with their own affordances.
+
+---
+
+## Subplaces
+
+A **subplace** is a defined subset of a Place. Use when a Place contains multiple distinct widgets. Notation: `P2.1`, `P2.2`, etc.
+
+---
+
+## Chunking
+
+Collapse a subsystem with one wire in + one wire out into a single chunk node. Show internals separately in a chunk diagram. Use stadium shape in Mermaid: `dynamicForm[["CHUNK: dynamic-form"]]`
+
+**Color**: `#b3e5fc` (light blue)
+
+---
+
+## Mermaid Visualization
+
+### Line Conventions
+
+| Line Style | Mermaid Syntax | Use |
+|---|---|---|
+| Solid (`-->`) | `A --> B` | Wires Out: calls, triggers, writes |
+| Dashed (`-.->`) | `A -.-> B` | Returns To: return values, data store reads |
+| Labeled | `A -.->|label| B` | Abbreviated flow |
+
+### Color Conventions
+
+```
+classDef ui fill:#ffb6c1,stroke:#d87093,color:#000
+classDef nonui fill:#d3d3d3,stroke:#808080,color:#000
+classDef store fill:#e6e6fa,stroke:#9370db,color:#000
+classDef chunk fill:#b3e5fc,stroke:#0288d1,color:#000,stroke-width:2px
+classDef placeRef fill:#ffb6c1,stroke:#d87093,stroke-width:2px,stroke-dasharray:5 5
+```
+
+### Subgraph IDs = Place IDs
+Use Place IDs as subgraph IDs so navigation wiring connects properly:
+```
+subgraph P1["P1: CMS Page (Read Mode)"]
+    U1["U1: Edit button"]
+end
+N1 --> P2   ← wire connects to Place boundary
+```
+
+---
+
+## Slicing a Breadboard
+
+Slicing groups affordances into **vertical implementation slices** — each demonstrating a mechanism working.
+
+### Rules
+- **Every slice must have visible UI that can be demoed**
+- Demo means: entry point (UI interaction) + observable output (UI renders, effect occurs)
+- Aim for ≤ 9 slices
+- Right size: coherent journey with clear "watch me do this" demo
+
+### Procedure
+
+1. **Identify minimal demo-able increment** — core data fetch + basic rendering (V1)
+2. **Layer mechanisms as slices** — each slice = one mechanism from the shape
+3. **Assign affordances** — each affordance in the slice where it's first needed
+4. **Create per-slice affordance tables**
+5. **Write a demo statement** for each slice: "Type 'dharma', results filter live"
+
+### Slice Summary Format
+
+| # | Slice | Mechanism | Demo |
+|---|---|---|---|
+| V1 | Widget with real data | F1, F4, F6 | "Widget shows letters from API" |
+| V2 | Search works | F3 | "Type to filter results" |
+| V3 | Infinite scroll | F5 | "Scroll down, more load" |
+
+### Visualizing Slices
+
+| Category | Style | Description |
+|---|---|---|
+| **This slice** | Bright color | Affordances being added |
+| **Already built** | Solid grey | Previous slices |
+| **Future** | Transparent, dashed border | Not yet built |
+
+---
+
+## Verification Checks
+
+| Check | Question | If No... |
+|---|---|---|
+| Every U that displays data | Incoming wire present? | Add the data source |
+| Every N | Has Wires Out or Returns To? | Investigate — may be dead code |
+| Every S | Something reads from it? | Investigate — may be unused |
+| Navigation mechanisms | Is N just "how" of getting somewhere? | Wire directly to Place |
+| N with side effects | Affects external state? | Add a store for external state |
+
+---
+
+## Handoff to High-Fidelity Design
+
+Once the breadboard is completed, verified, and sliced, it serves as the wireframe blueprint for the **Product Designer**:
+1. **Place to Figma Frame**: Each Place (e.g. `P1`, `P2`) maps to a distinct Figma frame/view.
+2. **Affordance to Element**: Every UI Affordance (e.g. `U1`, `U2`) must be represented as a visual component in the design.
+3. **Transition to Navigation**: The wires between Places define the interactive flows and navigation transitions in the Figma prototype.
+

package/skills/shapeup/resources/context-compaction.md

@@ -0,0 +1,240 @@
+# Context Compaction — Reference
+
+> Loaded on demand by the shapeup skill for `/shapeup full` (and any multi-gate
+> run). Operationalizes the v2.1 context-compaction design: digest format,
+> two-zone rules, writer ops, and the per-gate consumer view.
+
+---
+
+## Why this exists
+
+Over a long shaping run the artifacts (`shaping.md`, `spike-*.md`,
+`breadboard.md`, `pitch.md`) accumulate. Re-feeding raw prose into the LLM at
+every gate is token-expensive, signal-diluting, and eventually
+context-overflowing. The fix is **not** to stop accumulating — it is to stop
+using the **source of truth** as the **decision context**.
+
+Two layers, never collapsed into one:
+
+- **Source** = the full artifacts on disk (`shapeup/[slug]/shaping/...`). Immutable
+  once confirmed. The traceability + RULE 3 non-regression record.
+- **Decision context (the digest)** = a cheap, regenerable **derived read
+  model**. Never a write surface. The moment a gate's decision mutates the
+  digest as if it were state, the confirmed source is lost.
+
+> Compaction is lossy; RULE 3 (non-regression) is lossless.
+> Therefore compaction lives **only** in the derived layer.
+
+This is not a new philosophy — Shape Up already compacts (breadboard compacts the
+idea, the pitch compacts shaping into 5 ingredients, affordance IDs `U[N]`/`N[N]`
+are a compact symbol table). The digest is the missing read model for **in-run
+state**.
+
+---
+
+## The digest — `digest.md`
+
+One digest per shaping run. It lives in the **ephemeral, gitignored** run
+workspace, not next to the source artifacts:
+
+```
+.shapeup/[feature-slug]/digest.md
+```
+
+The LLM reads the digest at each gate; it follows a wikilink down to a full
+source artifact **only** when it must drill into one decision. No vector DB at
+the gate — a gate decision needs *every* constraint still in force (a missed
+No-Go or out-of-bounds = a silent wrong decision), which is a deterministic need.
+
+### Schema — 4 fields
+
+| Field | Meaning |
+|---|---|
+| `appetite` | central Shape Up constraint — never drops out of context |
+| `confirmed` | signed-off decisions, one line each + wikilink (frozen record) |
+| `open` | open questions / unresolved spikes — the thing that blocks the next gate |
+| `links` | wikilinks down to source artifacts |
+
+Affordance tables are **NOT** inlined — they are their own symbol table in
+`breadboard.md`; the digest links to them.
+
+`schema_version: 1` is carried in the frontmatter — v2.1 output must be readable
+by v2.2 (8-skill versioning is tightly coupled; forward-compat for one field is
+cheap).
+
+### Two-zone structure
+
+Shaping is **not** monotonic: GATE 1 can loop back and revise the R-list; an
+UNRESOLVED spike can force the shape to change at GATE 2/3. "Append-only" and
+"revision-before-confirm" cannot both be literally true. The resolution reuses
+the existing *frozen zone untouched, append-only* pattern:
+
+- **Frozen zone** — decisions that have *passed* a gate. Append-only,
+  **absolutely immutable**. This *is* RULE 3 embodied. One line + wikilink each.
+- **Working head** — exactly one block: the current pre-confirm phase. Freely
+  **overwritten / regenerated** until its gate confirms. On confirm → **promote**
+  the block into the frozen zone; open a fresh working head for the next phase.
+
+> Corrected definition: not "append-only digest" but
+> **"append-only frozen zone + mutable working head."**
+
+Staleness is **designed out**, not patched:
+- the frozen zone never stales (both source and digest are frozen — drift
+  impossible);
+- the working head never stales (rebuilt from the live artifact before its gate
+  fires).
+
+### Digest template
+
+```markdown
+---
+schema_version: 1
+type: shaping-digest
+feature: [feature-slug]
+appetite: [~1 week | ~2 weeks | ~6 weeks | TBD (uncapped)]
+---
+
+# [Feature] — Shaping Digest (derived read model — DO NOT hand-edit)
+
+> Regenerated from source on each phase. Source of truth is the artifacts under
+> `shapeup/[feature-slug]/shaping/`. This file is ephemeral + gitignored.
+
+## Appetite
+[~N weeks — anchors scope for every gate below]
+
+## Confirmed (frozen — append-only, immutable)
+- [S1] Problem frame: [one line] → [[shaping#problem-frame]]
+- [S2] R-list: R0..RN [one-line gist] → [[shaping#requirements]]
+- [S2.5] Rabbit holes / no-goes: [one line] → [[shaping#rabbit-holes]]
+- [S3] Shape: [name] — [one line rationale] → [[shaping#selected-shape]]
+- [S4] Fit check: clean (or: R3 ⚠️ → [[spike-pagination]]) → [[shaping#fit-check]]
+- [B1] Places: [list] → [[breadboard#places]]
+- [B3] Affordances: U0..UN / N0..NN → [[breadboard#affordances]]
+- [B5] Slices: [count] (≤9) → [[breadboard#slicing]]
+
+## Working head — [current phase, e.g. "S3 — Solution Shape"]
+[the full pre-confirm content of the current phase; freely overwritten until its
+ gate confirms, then promoted to a one-liner above and replaced by the next phase]
+
+## Open (blocks the next gate)
+- [ ] [unresolved spike / open question] → [[spike-xxx]]
+
+## Links
+- shaping → [[../../shapeup/[feature-slug]/shaping/shaping.md]]
+- breadboard → [[../../shapeup/[feature-slug]/shaping/breadboard.md]]
+- spikes → [[../../shapeup/[feature-slug]/shaping/spike-*.md]]
+```
+
+---
+
+## Writer ops — exactly two
+
+The digest stays **single-writer** (the running phase). The writer does exactly
+one of two operations — never an arbitrary edit:
+
+| Op | When | Effect |
+|---|---|---|
+| **overwrite-head** | On entry to a phase, and on any pre-confirm revision | Rebuild the *Working head* block from the live source artifact. The frozen zone is never touched. |
+| **promote-head** | On the phase's gate confirm | Collapse the working head into a one-line + wikilink entry appended to the *Confirmed* (frozen) zone; open a fresh working head for the next phase. |
+
+The frozen zone is **append-only and never rewritten**. A revision loop (GATE 1
+loops back, a spike forces a shape change) is just repeated `overwrite-head` on
+the *current* head — it can never mutate an already-frozen line, because the
+phase that wrote it has already passed its gate.
+
+---
+
+## Gate → minimal slice (the consumer view)
+
+At each gate, read the **filtered view** below from `digest.md` — not the full
+artifact prose. Confirmed state does not grow; it **shrinks in relevance** (GATE
+3 needs zero S1 prose — it needs the R-list as a frozen checklist). Compaction is
+mostly: *on confirm, demote the block from prose to a frozen one-liner + wikilink.*
+
+| Gate | Decision | Minimal slice to read | Accumulated state |
+|---|---|---|---|
+| **0** | Idea has clear user + problem? | raw input only | ~0 — nothing to compact |
+| **1** | R-list right? | problem frame + R-list + **appetite** | small |
+| **2** | Shape ok? | R-list (**frozen**) + shape + rationale + constraints | R demoted to checklist |
+| **3** | Fit check → breadboard? | R-list (frozen) + shape + **fit map** + spike results | S1 prose now useless |
+| **4** | Affordances/wiring right? | R-list (frozen) + places + **affordance table** (`U/N`) | symbol table, no prose |
+| *Pitch* | betting handoff | everything → 5 ingredients | compaction already exists |
+
+**Benefit is back-loaded.** GATE 0–1 have almost nothing to compact; the wins are
+at GATE 3–4 and especially the **handoff to ba-pitch-analyzer**. If staging the
+work, build the digest for the B-phases + pitch first.
+
+---
+
+## The two roots (by artifact *nature*, not by producer)
+
+Everything keys off the feature `<slug>`. Two roots, split by **who needs it**:
+
+| Root | Contents | Nature | Git |
+|---|---|---|---|
+| `shapeup/[slug]/shaping/` | shaping · breadboard · spike · pitch · kickoff | **durable source** | commit, shared |
+| `shapeup/[slug]/spec/` | domain model · UC · contracts · tasks | **durable deliverable** | commit, shared |
+| `.shapeup/[slug]/` | run-state · round ledger · gate log · **digest.md** · orient/ · evaluation/ · qa/ · discovery/ledger.md · harness-run.md | **ephemeral / derived** | **gitignore (hidden)** |
+
+- The **shared** root `shapeup/[slug]/` holds what the team contributes
+  to and reviews — source (shaping) + deliverable (spec). One feature folder, two
+  subfolders.
+- The **local** root `.shapeup/[slug]/` is per-run scratch + reports — hidden,
+  fully gitignorable, dies with the run. It is derived from the same `<slug>`.
+- `.gitignore`: one line — `.shapeup/`. The whole local root is ignored; no
+  carve-out is needed because the one committed report surface, the harvested
+  signal feed `shapeup/metrics.jsonl` (written by the tech-lead at SHIP,
+  fact-only; see the tech-lead skill's SHIP step), lives in the **shared** root.
+- All paths are **project-relative, resolved from the project root / cwd.** Never
+  `/mnt/...` — that is the claude.ai authoring sandbox and dies in a user repo.
+
+### Private ≠ hidden report
+
+Gitignoring the run workspace must NOT swallow the **report surface**. Shape Up
+mandates *status without asking* — hill position, verdict, ship sign-off, and
+surprise count are signals, not noise. Split inside the workspace:
+- **live scratch** (raw ledger, gate transition log, digest) → ephemeral, hidden;
+- **report surface** (hill / surprise / verdict / sign-off) → harvested at ship
+  (the tech-lead's metrics row), surfaced or archived to a `run-summary.md`.
+
+---
+
+## Handoff boundary — the digest never crosses a skill
+
+**`ba-pitch-analyzer` does NOT read the digest. It reads `pitch.md` / `shaping.md`.**
+
+The digest lives in `.shapeup/` — ephemeral, gitignored, run-scoped;
+it dies when the shaping run ends. `pitch.md`/`shaping.md` are durable source,
+committed. Each skill is a stateless reducer reading durable files — no reducer
+may depend on another reducer's ephemeral scratch.
+
+> Digest = internal context of **one** shaping run.
+> Pitch = the cross-skill compaction.
+> The digest never crosses a skill boundary.
+
+---
+
+## The digest is a sink, not a node — the ripple-check rule
+
+The digest carries **NO `shaping: true`** in its frontmatter. It is *outside* the
+ripple graph: working-head regeneration absorbs any upstream change on the next
+phase, so the digest never needs to be rippled into.
+
+**Mandatory config:** the ripple-check must **glob-exclude
+`.shapeup/`**. Without the exclude, the check scans the digest as a
+source artifact and ripples incorrectly (the digest links *down* to sources; a
+naive scanner reads those wikilinks as upstream edges and inverts the graph).
+
+---
+
+## Deferred (`~`)
+
+- **Cross-run pitch RAG / vector archive** — semantic search over a *pitch
+  archive* across cycles ("have we shaped this before?", reviving passed pitches)
+  serves a **human at the betting table**, not an automated gate, so probabilistic
+  recall is harmless there. It is a separate infrastructure bet (embedding model,
+  store, re-index trigger). Revive as its own bet at a future betting table; its
+  home would be `.shapeup/pitch-archive/` + index — a level-up, never a
+  gate dependency.
+- **Cross-run pitch archive** under `.shapeup/pitch-archive/` — only if/when
+  cross-run discovery lands. (The two-root workspace itself shipped in v2.2.)

package/skills/shapeup/resources/framing-doc.md

@@ -0,0 +1,92 @@
+# Framing Doc — Reference
+
+> Source: rjs/shaping-skills (upstream). Loaded on demand by the shapeup skill.
+
+---
+
+## What This Does
+
+Turns a raw conversation transcript into a structured framing document. Captures **the problem worth solving** and **why it was chosen** over alternatives.
+
+**⚠️ GIGO Warning:** Formats and distills only. Does not evaluate whether the thinking is sound. Good conversation in → good document out. Bad in → bad out.
+
+---
+
+## When to Use
+
+- You have a transcript of a real conversation about a problem or opportunity
+- You need a shareable document to align the team on what you're solving
+- Before starting shaping — to record the "why this, why now"
+
+**This is a document skill for team contexts.** Not part of the solo shaping workflow.
+
+---
+
+## Phase F1 — Parse Transcript
+
+```
+Read the entire transcript before writing anything. Extract:
+- Core problem or observation being discussed
+- Any "why this, not that" reasoning stated
+- Appetite or time constraint if mentioned
+- Explicit no-gos or out-of-scope statements
+- Unresolved questions or open threads
+
+DO NOT invent reasoning not present in the transcript.
+If something is unclear: write "[unclear from transcript]" — never guess.
+```
+
+---
+
+## Phase F2 — Write Framing Document
+
+Write `shapeup/[feature-slug]/shaping/frame.md`
+
+```markdown
+---
+shaping: true
+feature: [feature-slug]
+doc_type: frame
+status: draft
+---
+
+# [Feature Name] — Framing
+
+## The Problem
+[2–4 sentences: situation + complication + why it matters now]
+
+## Why Now
+[What changed that makes this worth doing now vs later]
+[Omit if not discussed in transcript]
+
+## Desired Outcome
+[Success from the user's perspective — observable and specific]
+
+## Why This Direction
+[Alternatives considered + rationale for this choice]
+[Omit if alternatives not discussed]
+
+## Appetite
+[Time budget if mentioned. Omit if not mentioned.]
+
+## Non-Goals
+[Things explicitly decided NOT to solve. Omit if not discussed.]
+
+## Open Questions
+[Unresolved threads from the conversation. Omit if none.]
+
+---
+*Generated from transcript. Review before distributing.*
+```
+
+---
+
+## Phase F3 — Quality Check
+
+```
+- [ ] Every claim traces to something said in transcript (not inferred)
+- [ ] No solution details in the Problem section
+- [ ] Non-Goals present only if explicitly discussed
+- [ ] Open Questions lists things unresolved, not new questions invented
+- [ ] "[unclear from transcript]" used for ambiguous parts, not guesses
+```