rsc-universal 0.1.1

package/skills/pitch-deck/references/numbers-that-matter.md

@@ -0,0 +1,78 @@
+# The numbers that matter on the deck
+
+This file is about **which numbers belong ON the deck and what "good" looks like** — not how to compute them
+at scale. Build the projection/cohort/burn model in `financial-model`; run the standalone CAC/LTV/payback
+health check in `unit-economics`. Here you pick the decision-grade few and put them where they persuade.
+
+At seed, the decision rides on a small set. Do **not** dump the P&L on a slide — choose the metrics that tell
+*your* story (traction, business model, the ask) and show each with a unit and a trend.
+
+## The metric glossary (formula + current band)
+
+| Metric | Formula | Healthy band (2025/26) | Where on the deck |
+| --- | --- | --- | --- |
+| MRR | sum of monthly recurring revenue | — | Traction |
+| ARR | MRR × 12 | — | Traction |
+| MoM growth | (this month − last month) / last month | ~15–20% (<$1M ARR); ~8–15% ($1M–$10M ARR) | Traction (the curve) |
+| CAC | sales+marketing spend / new customers acquired | varies; judged via LTV:CAC + payback | Business model |
+| LTV | (ARPA × gross margin) / churn rate | — | Business model |
+| LTV : CAC | LTV / CAC | **≥ 3:1** | Business model / Traction |
+| CAC payback | CAC / (ARPA × gross margin), in months | **< ~18 months** (2024 median; lower = above avg) | Business model |
+| Gross margin | (revenue − COGS) / revenue | software typically **70%+** | Business model |
+| Net revenue retention | (start + expansion − churn − contraction) / start | **> 110%** | Traction |
+| Burn rate | net cash out per month | context for runway | Ask (use-of-funds) |
+| Runway | cash on hand / monthly burn | names the ask milestone | Ask |
+
+A quick read of the bands: **LTV:CAC ≥ 3:1, NRR > 110%, CAC payback under ~18 months** is the "above-average
+efficiency" signal. You do not need all of them — pick the ones that are strong and honest for your stage.
+
+## Growth shape beats absolute size
+
+This is the load-bearing idea of the traction slide. **A consistent curve outperforms a bigger flat number.**
+
+```text
+Company A:  $50K MRR, +25% MoM, 6 months straight   ->  reads STRONGER
+Company B:  $200K MRR, flat or erratic              ->  reads weaker
+```
+
+Why: investors back the *derivative*, not the level. $50K growing 25% MoM compounds past $200K fast and proves
+the acquisition engine works; $200K flat proves it stalled. Show the curve, label the trend, and let the slope
+do the persuading. Early-stage targets: ~15–20% MoM under $1M ARR, ~8–15% MoM from $1M–$10M ARR.
+
+## Bad → Good traction slides
+
+```text
+Bad   "10,000 users. Huge interest. Going viral."
+       (no unit, no trend, no money — a vanity wall)
+
+Good   "$50K MRR, +22% MoM for 5 straight months (curve shown).
+        NRR 118%. 40 paying logos incl. [Customer A, Customer B].
+        LTV:CAC 4:1, CAC payback 11 months."
+       (each number has a UNIT and a TREND; the SHAPE is visible; money is real)
+```
+
+```text
+Bad   "We grew 300% last year!"
+       (300% from what to what? one big % hides a tiny base or a one-off spike)
+
+Good   "$8K -> $50K MRR over 6 months, +22% MoM average (no single month below +15%)."
+       (the base, the path, the consistency — the claim is falsifiable and the trend is the point)
+```
+
+The vanity tell: **a count with no rate behind it.** Registered users without an activation or paying rate, app
+installs without retention, "interest" without revenue. A sharp investor reads the missing rate as the number
+you are hiding — so show it, even when it is small but honest.
+
+## What NOT to put on the deck
+
+- The full P&L or a 5-year monthly model — that is a data-room artifact; the deck shows the shape, the room
+  holds the detail. Build it in `financial-model`.
+- A CAC/LTV teardown by channel and cohort — that is the `unit-economics` health check; the deck shows the
+  headline band (LTV:CAC 4:1), the analysis lives elsewhere.
+- Every metric you track. Three strong, honest numbers beat twelve mediocre ones. Curate.
+
+## Sourcing rule
+
+Every number on a slide traces to a source: the model, your analytics, or a citation. Mark any gap
+`[[NEEDS PROOF]]` rather than inventing a figure to fill a chart — a single fabricated number, once caught,
+poisons the whole deck. A hockey-stick projection must name its driver; a curve with no mechanism is fiction.

package/skills/pitch-deck/references/slide-spine.md

@@ -0,0 +1,149 @@
+# The slide spine — full template
+
+The canonical investor-deck spine is **10 core slides + the ask**, read in risk-evaluation order. Keep the
+whole deck under ~15 (DocSend: 11–20 raises better; past that it hurts). For each slide below: its one job, the
+investor question it answers, what content goes on it, an example line, and the trap.
+
+Read this top-to-bottom: the deck is built in this order because that is the order an investor evaluates risk.
+
+---
+
+## 1 — Title / purpose
+
+- **Job:** say what you do in one declarative line.
+- **Investor question:** "What is this, in a sentence?"
+- **On it:** company name, a one-line "we do X for Y" positioning, stage/round (optional), one clean visual.
+- **Example:** *"Acme — the books-close autopilot for Series-A finance teams."*
+- **Trap:** a vague tagline ("reimagining work") that could describe a hundred companies. Be concrete.
+
+## 2 — Problem
+
+- **Job:** make a real pain ache, for a specific who.
+- **Investor question:** "Is this a real, urgent problem — and for whom?"
+- **On it:** who has the pain, what it costs them today, why current workarounds fail. One number that sizes
+  the pain.
+- **Example:** *"A 200-person SaaS company spends ~12 finance-days a month closing the books in spreadsheets."*
+- **Trap:** a problem no one pays to solve, or a problem stated so broadly it has no owner.
+
+## 3 — Solution
+
+- **Job:** show the insight that solves the problem.
+- **Investor question:** "Does their thing actually solve it — and why is it the right shape?"
+- **On it:** your approach in one sentence, the non-obvious insight behind it, the before→after for the user.
+- **Example:** *"We ingest the ledger and auto-reconcile — close drops from 12 days to 2."*
+- **Trap:** a feature list. Lead with the insight; features are slide 6.
+
+## 4 — Why now
+
+- **Job:** name the shift that makes this the moment.
+- **Investor question:** "Why hasn't this been done — and why is now the time?"
+- **On it:** the recent change (tech, regulation, behavior, cost curve) that just made this viable or urgent.
+- **Example:** *"Ledger APIs went universal in 2024; what needed a 6-month integration is now a 1-day connect."*
+- **Trap:** no answer, or a hand-wave ("AI is hot"). If there is no real shift, the timing thesis is weak.
+
+## 5 — Market
+
+- **Job:** show the prize is big and reachable.
+- **Investor question:** "Is the outcome big enough to return the fund?"
+- **On it:** TAM / SAM / SOM, **bottom-up first**, every number sourced. (Full method below.)
+- **Example:** *"120K target SMBs × $4.8K ACV = $576M SAM (source: [registry]); 3-yr SOM 3,000 = $14.4M ARR."*
+- **Trap:** "$X trillion, we just need 1%." Top-down hand-wave; a credibility tell.
+
+## 6 — Product
+
+- **Job:** one concrete proof the thing is real.
+- **Investor question:** "Is this a working product or a slide?"
+- **On it:** one screenshot / flow / demo frame that shows the core loop. Not 17 features — the one that matters.
+- **Example:** *"[screenshot of the auto-reconcile run completing in 90 seconds]."*
+- **Trap:** a feature carousel. One visual that proves the core insight from slide 3 actually ships.
+
+## 7 — Business model
+
+- **Job:** show how a dollar in becomes more dollars out.
+- **Investor question:** "How does this make money, and is the unit profitable?"
+- **On it:** pricing, who pays, ACV, and the unit economics signal (gross margin, LTV:CAC if you have it).
+- **Example:** *"$400/mo per finance seat; ACV $4.8K; 82% gross margin; LTV:CAC 4:1."*
+- **Trap:** "we'll figure out monetization later" at seed, or a model with no margin logic.
+
+## 8 — Traction (the center of gravity)
+
+- **Job:** show it is working AND accelerating — the SHAPE, not just a point.
+- **Investor question:** "Is it working, and is it speeding up?"
+- **On it:** MRR/ARR + MoM trend (the curve), retention/NRR, key logos, the LTV:CAC band. Few numbers, each
+  with a unit and a trend.
+- **Example:** *"$50K MRR, +22% MoM for 5 months (curve); NRR 118%; 40 paying logos; LTV:CAC 4:1."*
+- **Trap:** vanity metrics (registered users with no activation), a single flat number, or no unit/trend.
+- **Why it's the highest-stakes slide:** investors spend ~3× longer here, and 76% of "no" decisions cite weak
+  traction. This is where the deck is won or lost.
+
+## 9 — Competition
+
+- **Job:** an honest landscape + your specific wedge.
+- **Investor question:** "Why won't incumbents just crush them?"
+- **On it:** the real alternatives (incl. "status quo / spreadsheets"), and the one axis where you win.
+- **Example:** *"Incumbents bolt reconciliation onto an ERP; we are the close-native layer — 10× faster setup."*
+- **Trap:** "we have no competition." Reads as naive or as "no market." Status quo is always a competitor.
+
+## 10 — Team
+
+- **Job:** why *this* team wins *this*.
+- **Investor question:** "Can these specific people pull it off?"
+- **On it:** founders, the earned insight / unfair advantage, relevant prior wins. Key hires/advisors if they
+  de-risk.
+- **Example:** *"Ex-Stripe finance-infra lead + ex-Big4 controller — we lived this close for 6 years."*
+- **Trap:** a logo wall of past employers with no link to *why it makes you win this problem*.
+
+## 11 — The ask
+
+- **Job:** amount → use-of-funds → the milestone it buys.
+- **Investor question:** "What do you need, and what does my money de-risk?"
+- **On it:** raise amount + instrument, the use-of-funds split, and the specific milestone the runway reaches.
+- **Example:**
+
+  ```text
+  Raising $1.5M (SAFE).
+  Use of funds:  60% engineering · 25% go-to-market · 15% ops
+  Buys:          18 months runway to $100K MRR — Series-A ready.
+  ```
+
+- **Trap:** an ask with no number, or a burn statement with no milestone ("$1.5M for 18 months"). The
+  milestone turns a burn rate into an investment thesis.
+
+---
+
+## The market-sizing method (bottom-up, sourced)
+
+Investors scrutinize the market slide and the ask hardest for realism. Build the number, do not assert it.
+
+1. **SOM (bottom-up, the honest one):** reachable accounts in 3 years × your price. Start here.
+2. **SAM:** total accounts you could serve × price — the segment you actually address.
+3. **TAM:** the whole category, top-down — used only as a sanity ceiling.
+4. **Source every figure** (registry, analyst report, census). The big number should be the *result* of the
+   unit math, never the premise.
+
+```text
+SOM (3-yr reachable):  3,000 accounts  × $4.8K ACV = $14.4M ARR
+SAM (addressable):     120,000 accounts × $4.8K   = $576M
+TAM (category ceiling): $X.XB  (top-down sanity check, sourced)
+```
+
+## Stage deltas — what each slide may claim
+
+| Slide | Pre-seed (sells team + insight) | Seed (sells early traction shape) | Series A (sells repeatable engine) |
+| --- | --- | --- | --- |
+| Problem | Sharp, lived, specific | Same, now validated by users | Same, with paying-customer proof |
+| Solution | The insight + a prototype | A shipped product | A product with depth/moat |
+| Why now | The timing thesis | Same, with early signal | Same, proven by adoption |
+| Market | Bottom-up estimate | Bottom-up, refined by real ACV | Real ACV + expansion math |
+| Traction | Waitlist / LOIs / design partners | MRR + MoM trend + early retention | Predictable growth + NRR + payback |
+| Business model | Hypothesis, with margin logic | Early pricing validated | Proven unit economics (LTV:CAC, payback) |
+| Team | The whole bet | Team + early execution proof | Team scaled, key hires in place |
+| Ask | Small (to reach traction) | Medium (to reach the engine) | Larger (to pour fuel on a proven engine) |
+
+Claiming above your stage (Series-A "engine" language on a pre-seed deck with no data) reads as naive.
+Claiming below it (a seed deck hiding real traction behind a vision) wastes your strongest card.
+
+---
+
+Hand off: once this spine is locked, `presentations` renders + themes + exports it; `financial-model` produces
+the numbers behind slides 5/7/8/11; `investor-materials` builds the one-pager, memo, and data room around it.

package/skills/pitch-deck/scripts/verify.sh

@@ -0,0 +1,186 @@
+#!/usr/bin/env bash
+#
+# verify.sh — structural/numeric lint for an investor pitch-deck OUTLINE.
+#
+# WHAT IT DOES (read-only; no edits, no network)
+#   Parses a deck outline (markdown — one slide per heading line, e.g. `## Problem`
+#   or `## Slide 8: Traction`) and checks the CONTENT CONTRACT, not prose taste:
+#     1. Required core slides present: problem, solution, why-now, market, product,
+#        business-model, traction, team, ask (case-insensitive heading match).
+#     2. Slide count: warn if > 15 (the deck-discipline limit).
+#     3. Ask block: must name a currency amount (or "raising ...") AND a
+#        use-of-funds / runway / milestone token. A numberless ask FAILS.
+#     4. Traction block: must carry >=1 metric with a unit (%, MRR, ARR, x, $).
+#        Numberless traction WARNS.
+#     5. Buzzword banlist WARNING (revolutionary, disruptive, world-class,
+#        no competition, best-in-class, hockey stick, conservative estimate).
+#
+#   Narrative quality is NOT judged here — that is the capability eval's job.
+#   This is grep-level structure only.
+#
+# HOW TO RUN (against your own deck outline, not the skills repo)
+#   ./verify.sh path/to/deck.md
+#   ./verify.sh --strict path/to/deck.md      # warnings become failures (CI gate)
+#   ./verify.sh                               # no path -> nothing to lint, exits 0
+#
+# EXIT CODES
+#   0  clean, or warn-only (and not --strict), or no target given / empty target
+#   1  a real failure: a missing CORE slide, or an ask with no number
+#      (also: any warning when --strict)
+#   2  bad usage (path given but not a readable file)
+
+set -euo pipefail
+
+if [ -z "${BASH_VERSION:-}" ]; then
+  printf 'This script requires bash (>= 3.2). Run: bash %s\n' "$0" >&2
+  exit 2
+fi
+
+# --- color (suppressed when not a TTY) -------------------------------------
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; NC=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; NC=''
+fi
+
+ok_count=0; warn_count=0; fail_count=0
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN"  "$NC" "$*"; ok_count=$((ok_count + 1)); }
+warn() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; warn_count=$((warn_count + 1)); }
+fail() { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; fail_count=$((fail_count + 1)); }
+
+usage() { sed -n '3,35p' "$0" | sed 's/^# \{0,1\}//'; }
+
+# --- arg parse -------------------------------------------------------------
+STRICT=0
+DECK=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --strict)  STRICT=1; shift ;;
+    -h|--help) usage; exit 0 ;;
+    -*)        printf '%sUnknown flag: %s%s\n\n' "$RED" "$1" "$NC"; usage; exit 2 ;;
+    *)         DECK="$1"; shift ;;
+  esac
+done
+
+# No target -> nothing to check. Clean exit (no false failure on empty input).
+if [ -z "$DECK" ]; then
+  printf 'No deck outline given. Pass a markdown path, e.g.: %s deck.md\n' "$0"
+  printf '(nothing to lint — exiting clean)\n'
+  exit 0
+fi
+
+if [ ! -f "$DECK" ]; then
+  printf '%sNot a readable file: %s%s\n' "$RED" "$DECK" "$NC"
+  exit 2
+fi
+
+# Empty file -> clean exit, no false failure.
+if [ ! -s "$DECK" ]; then
+  warn "deck outline is empty: $DECK (nothing to lint)"
+  printf '\nok=%d warn=%d fail=%d\n' "$ok_count" "$warn_count" "$fail_count"
+  exit 0
+fi
+
+printf 'Linting deck outline: %s\n\n' "$DECK"
+
+# Headings only (lines starting with one or more '#').
+HEADINGS="$(grep -E '^#{1,6}[[:space:]]' "$DECK" 2>/dev/null || true)"
+
+# --- 1. required core slides ----------------------------------------------
+# Each entry: "Label|regex matched against heading text (case-insensitive)".
+check_slide() {
+  label="$1"; pat="$2"
+  if printf '%s\n' "$HEADINGS" | grep -iqE "$pat"; then
+    ok "core slide present: $label"
+  else
+    fail "missing core slide: $label (heading matching /$pat/)"
+  fi
+}
+
+check_slide "Problem"        'problem|pain'
+check_slide "Solution"       'solution|how it works|approach'
+check_slide "Why now"        'why[ -]?now|timing'
+check_slide "Market"         'market|tam|sam|som|market size'
+check_slide "Product"        'product|demo|how it works'
+check_slide "Business model" 'business model|model|pricing|revenue model|how we (make|earn)'
+check_slide "Traction"       'traction|growth|metrics|momentum'
+check_slide "Team"           'team|founders|who we are'
+check_slide "Ask"            'ask|raise|raising|fundrais|the ask|use of funds'
+
+# --- 2. slide count --------------------------------------------------------
+SLIDE_COUNT="$(printf '%s\n' "$HEADINGS" | grep -cE '^#{1,6}[[:space:]]' || true)"
+SLIDE_COUNT="${SLIDE_COUNT:-0}"
+if [ "$SLIDE_COUNT" -gt 15 ]; then
+  warn "deck has $SLIDE_COUNT headings — over the ~15-slide discipline; move detail to the conversation/data room"
+elif [ "$SLIDE_COUNT" -eq 0 ]; then
+  warn "no '#' headings found — is this a slide-per-heading outline?"
+else
+  ok "slide count $SLIDE_COUNT (<= 15 discipline limit)"
+fi
+
+# --- block extraction ------------------------------------------------------
+# Print the lines from the heading matching $1 up to (not incl.) the next heading.
+block_for() {
+  # Lowercase the heading for matching so it works on BSD awk (no IGNORECASE).
+  awk -v pat="$1" '
+    BEGIN { inblk = 0 }
+    /^#{1,6}[[:space:]]/ {
+      if (inblk) { exit }
+      if (tolower($0) ~ pat) { inblk = 1; print; next }
+    }
+    { if (inblk) print }
+  ' "$DECK"
+}
+
+# --- 3. ask block: amount AND a use-of-funds/runway/milestone token --------
+ASK_BLOCK="$(block_for 'ask|raise|raising|fundrais|use of funds')"
+if [ -z "$ASK_BLOCK" ]; then
+  warn "could not isolate an ask block to inspect (heading not found earlier?)"
+else
+  has_amount=0; has_use=0
+  # currency amount: $/€/£ + number, or a number + k/m/mm, or the word raising/raise
+  # An actual figure: currency+digit, a number with a k/m unit, or "raising <number>".
+  # Bare "raise/raising" with no number does NOT count as an amount.
+  if printf '%s\n' "$ASK_BLOCK" | grep -iqE '[$€£][0-9]|[0-9]+(\.[0-9]+)?[[:space:]]*(k|m|mm|million|thousand)|rais(e|ing)[[:space:]]+[$€£]?[0-9]'; then
+    has_amount=1
+  fi
+  if printf '%s\n' "$ASK_BLOCK" | grep -iqE 'use of funds|runway|milestone|months?|to[[:space:]]+[$€£]?[0-9]|series[ -]?[ab]|allocat|breakdown'; then
+    has_use=1
+  fi
+  if [ "$has_amount" -eq 1 ] && [ "$has_use" -eq 1 ]; then
+    ok "ask names an amount AND a use-of-funds/runway/milestone"
+  elif [ "$has_amount" -eq 0 ]; then
+    fail "ask slide names no raise amount (need e.g. '\$1.5M' or 'raising ...')"
+  else
+    warn "ask names an amount but no use-of-funds/runway/milestone — add 'what it buys'"
+  fi
+fi
+
+# --- 4. traction block: at least one metric with a unit --------------------
+TRACTION_BLOCK="$(block_for 'traction|growth|metrics|momentum')"
+if [ -z "$TRACTION_BLOCK" ]; then
+  warn "could not isolate a traction block to inspect"
+else
+  if printf '%s\n' "$TRACTION_BLOCK" | grep -iqE '[0-9]+([.,][0-9]+)?[[:space:]]*(%|x|mrr|arr|nrr)|[$€£][0-9]|[0-9]+[[:space:]]*(mom|mo|month)'; then
+    ok "traction carries >=1 metric with a unit (%, x, MRR/ARR, \$, MoM)"
+  else
+    warn "traction slide has no number+unit — show the growth SHAPE (e.g. '\$50K MRR, +22% MoM')"
+  fi
+fi
+
+# --- 5. buzzword banlist (warn-only) ---------------------------------------
+BUZZ='revolutionary|disruptive|world-?class|no competition|best-?in-?class|hockey ?stick|conservative estimate|game-?changer'
+hits="$(grep -inE "$BUZZ" "$DECK" 2>/dev/null || true)"
+if [ -n "$hits" ]; then
+  warn "buzzwords found (replace with a number / mechanism / receipt):"
+  printf '%s\n' "$hits" | head -n 6
+else
+  ok "no banlist buzzwords"
+fi
+
+# --- summary ---------------------------------------------------------------
+printf '\nok=%d warn=%d fail=%d\n' "$ok_count" "$warn_count" "$fail_count"
+
+if [ "$fail_count" -gt 0 ]; then exit 1; fi
+if [ "$STRICT" -eq 1 ] && [ "$warn_count" -gt 0 ]; then exit 1; fi
+exit 0

package/skills/plan/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: plan
+description: "Use when turning an approved, clarified spec into a technical implementation plan — the SDD phase between clarify and tasks. Covers architecture and component boundaries, the public interfaces/contracts, data model and data flow, the testing strategy, sequencing, and the risk register. Triggers: 'plan this feature', 'how should we build this', 'design the architecture', 'write the implementation plan', 'plan.md', 'what's the data flow', 'how do we test this', 'what are the risks', 'we have the spec, now what'. Reads the spec under 02-DOCS/wiki/sdd/specs/ and the constitution; writes 02-DOCS/wiki/sdd/plans/<slug>.md; defers concrete stack mechanics (framework APIs, ORM, test tooling) to the relevant stack skill. NOT requirements capture (that's specify), NOT ambiguity removal (that's clarify), NOT the task breakdown (that's tasks). Honors the harness accompaniment dial."
+tags: [sdd, plan, design]
+recommends: [tasks]
+profiles: [core, full]
+origin: risco
+---
+
+# Plan — the technical blueprint between spec and tasks
+
+You have a spec that says **what** and **why**. `plan` decides **how** — the architecture, the
+interfaces, the data flow, the way you'll prove it works, and the things most likely to bite you.
+It is the engineering counterpart of the spec: a spec a human signed off on becomes a plan an
+engineer (or an agent) can execute without re-deciding the shape of the system halfway through.
+
+`plan` sits fourth in the SDD chain:
+
+```text
+constitution → specify → clarify → [ plan ] → tasks → analyze → implement → verify → review → ship
+```
+
+It reads the clarified spec and the constitution, produces ONE artifact —
+`02-DOCS/wiki/sdd/plans/<slug>.md` — and hands off to `tasks`, which slices that plan into an
+ordered, independently-verifiable checklist.
+
+## The one rule that defines this phase
+
+**Decide structure, not syntax.** A plan names the components, their contracts, the data that
+flows between them, and how each piece is proven. It does **not** write the framework's route
+decorators, the ORM's session boilerplate, or the test runner's flags. Those are stack mechanics,
+and they belong to the stack skill (`../fastapi/SKILL.md`, `../nextjs/SKILL.md`, `../go/SKILL.md`,
+`../flutter/SKILL.md`, `../postgresdb/SKILL.md`). The plan says *"the orders service exposes a
+`reserve(cartId) → Reservation` operation, transactional, idempotent on cartId"*; the stack skill
+later decides whether that's a POST handler with a Pydantic model or a Go method on a struct.
+
+If you find yourself writing real code in the plan, you have dropped an altitude. Pull back up.
+
+## Before you write a line
+
+Run this gate. Skipping it produces a plan that drifts from intent on contact.
+
+1. **Read the accompaniment dial.** Open `02-DOCS/wiki/harness/user-profile.md`. The technical +
+   accompaniment level (L0..L3) sets how much you explain and how many questions you ask — see
+   "Adapting to the dial" below. No profile yet → assume non-technical, ask the two gauging
+   questions first (the harness owns that flow).
+2. **Read the spec.** `02-DOCS/wiki/sdd/specs/<slug>.md`. If it is missing, STOP — there is nothing
+   to plan from; route to `../specify/SKILL.md`. If it still carries `[NEEDS CLARIFICATION]` markers
+   or open questions, STOP — route to `../clarify/SKILL.md`. **A plan built on an unclarified spec
+   is a guess wearing a diagram.**
+3. **Read the constitution.** `02-DOCS/wiki/sdd/constitution.md` holds the project's non-negotiables
+   (stack canon, quality bars, conventions). Every architectural choice must be consistent with it;
+   when the plan needs to bend a principle, say so explicitly with a reason — don't bend it silently.
+4. **Read the Knowledge map.** The root `CLAUDE.md` `## Knowledge map` points at existing
+   `02-DOCS/wiki/stack/*` and prior plans/decisions. Reuse what's already established. A plan that
+   reinvents a pattern the project already settled is scope drift.
+
+Only when the spec is present and clarified do you plan.
+
+## What a plan contains
+
+A plan is the answer to seven questions, in this order. Each is a section of the artifact
+(template in `references/plan-template.md`). Fill them top-down; later sections lean on earlier ones.
+
+| # | Section | The question it answers |
+| --- | --- | --- |
+| 1 | Context & constraints | What spec/constitution facts pin this design down? |
+| 2 | Architecture | What are the components and how do they fit together? |
+| 3 | Interfaces & contracts | What does each component promise to the others? |
+| 4 | Data model & flow | What data exists, where it lives, how it moves and changes? |
+| 5 | Testing strategy | How will we *prove* each part does what it claims? |
+| 6 | Sequencing & dependencies | In what order can this be built and verified? |
+| 7 | Risks & open decisions | What is most likely to be wrong, and what's still undecided? |
+
+Detailed guidance and the fill-in template live in `references/plan-template.md`. The essentials of
+each section:
+
+### 1. Context & constraints
+
+Restate, in one or two lines each, the spec facts and constitution rules that actually constrain
+the design — the acceptance criteria, the non-functional bars (latency, scale, data residency),
+the stack canon. Don't re-paste the spec; cite it (`spec §Acceptance #3`). This section is the
+plan's contract with intent: if a reviewer disagrees with the design, this is where they check
+whether you misread the constraints.
+
+### 2. Architecture
+
+Name the components and draw the relationship — a small box-and-arrow diagram in a fenced block,
+plus a sentence per component stating its single responsibility. Mark each component's boundary:
+what's inside the system you're building vs. an external dependency. Show where the seams are,
+because the seams are where you'll test, mock, and parallelize later.
+
+```text
+[ client ] --HTTP--> [ api: orders ] --calls--> [ svc: reservation ]
+                            |                            |
+                            v                            v
+                     [ db: orders ]              [ external: payments ]
+```
+
+State the **one** architectural decision that matters most and why you made it (sync vs. async,
+monolith vs. split service, read model vs. single table). One real decision, defended, beats five
+hedged ones. If two designs are genuinely viable, present both with the trade-off and a
+recommendation matched to the constitution — don't leave the reader to guess which you'd ship.
+
+### 3. Interfaces & contracts
+
+For each seam in the architecture, define the contract at the **shape** level, not the
+implementation: the operation name, its inputs and outputs, its error modes, and its invariants
+(idempotent? transactional? ordered?). This is where most integration bugs are prevented or born.
+
+```text
+reservation.reserve(cartId: CartId) -> Reservation | OutOfStock | CartNotFound
+  - idempotent on cartId (calling twice returns the same Reservation)
+  - holds stock for 15 min, then auto-releases
+  - never partially reserves: all lines or none
+```
+
+Keep it language-neutral. The stack skill turns this into a typed signature, a route, or an
+interface later — and it will, because you gave it an unambiguous contract.
+
+### 4. Data model & flow
+
+Name the entities, their key fields, and their relationships — again at the model level, not DDL.
+Then trace the **flow**: for the primary scenario in the spec, follow one request from entry to
+persistence and back, naming what reads and writes each store. Call out the consistency boundaries
+(what's transactional together, what's eventually consistent) and the migration impact (new table?
+new column? backfill?). Concrete schema, indexes, and migration mechanics → `../postgresdb/SKILL.md`.
+
+### 5. Testing strategy
+
+Decide *how each claim in the spec gets proven* before any code exists — this is what makes
+`implement`'s TDD discipline possible. For each acceptance criterion, name the level that proves it
+(unit / contract / integration / e2e), what the test asserts, and what it has to fake to stay fast.
+You are choosing the *strategy* (which seams to test, what to mock, where the e2e line is); the
+stack skill owns the *tooling* (the runner, the fixtures, the assertion library). A plan whose
+testing section is "we'll add tests" has no testing strategy — name the levels and the seams.
+
+### 6. Sequencing & dependencies
+
+Order the work so each step is independently verifiable and the dependency graph is explicit. Mark
+which steps are independent (candidates for fan-out via the `parallel` phase when it's available)
+and which must be serial. This section is the bridge to `tasks`: a clean sequence here becomes a
+clean task list there.
+
+### 7. Risks & open decisions
+
+List what is most likely to be wrong, ranked. For each risk: the trigger, the impact, and the
+mitigation or the spike that would retire it. Separately, log any decision still genuinely open
+(and what input would close it). Honesty here is the whole point — a plan that claims zero risk is
+the riskiest plan. Significant design decisions taken during planning also get appended to
+`02-DOCS/wiki/sdd/decisions.md` (the SDD decisions log), so later phases can trace the *why*.
+
+## Adapting to the dial
+
+Read `02-DOCS/wiki/harness/user-profile.md` and match the artifact and your narration to it:
+
+| Level | How `plan` behaves |
+| --- | --- |
+| **L0** | Terse plan: the seven sections, minimal prose, diagram + contracts + risks. No narration in chat — write the file, point to it. |
+| **L1** | Same artifact, one line of *why* on the top architectural decision. |
+| **L2** | Justify each significant design choice in the artifact; surface trade-offs you weighed. |
+| **L3** | Explain-everything: walk the non-technical user through the architecture in plain language, ask about constraints you can't infer (one focused question at a time), define terms inline. |
+
+The dial changes how much you *say*, never whether the seven sections exist. Even at L0 the plan is
+complete; it's just quiet.
+
+## The artifact
+
+Write to `02-DOCS/wiki/sdd/plans/<slug>.md`, where `<slug>` matches the spec's slug exactly (one
+plan per spec, same name — that's how `tasks`, `analyze`, and `implement` find it). Use
+`references/plan-template.md` verbatim as the skeleton. Then index it: add a row under the
+`## Knowledge map` section of the root `CLAUDE.md` pointing at the new plan, so the harness wiki and
+every later phase can find it. If a plan for this slug already exists, update it in place and note
+what changed — don't fork a `-v2`.
+
+## Anti-patterns → STOP
+
+| Rationalization | Reality / Fix |
+| --- | --- |
+| "I'll just write the actual code in the plan, it's faster" | You dropped an altitude. The plan owns structure; syntax is the stack skill's job at `implement`. Pull back to contracts. |
+| "The spec's a bit fuzzy but I get the gist, I'll plan around it" | A plan on an unclarified spec is a guess. STOP, route to `clarify`, then plan. |
+| "Testing strategy = 'we'll write tests'" | That's not a strategy. Name the level per acceptance criterion and what each test fakes. |
+| "Risks section feels negative, I'll keep it short" | The plan that claims no risk is the riskiest. Rank the real risks and give each a mitigation. |
+| "I'll pick the framework and ORM and config here" | Stack canon lives in the constitution; mechanics live in the stack skill. The plan stays stack-neutral above the seam. |
+| "Two designs are fine, I'll list both and let them choose" | Decide. Present alternatives only with a trade-off and a recommendation matched to the constitution. |
+| "I'll plan the whole sequence as one big step" | Then `tasks` can't slice it and nothing's independently verifiable. Break it into ordered, checkable steps. |
+| "There's already a plan for this slug, I'll start a fresh one" | Update in place and note the change. Forked plans rot; later phases read the wrong one. |
+
+## When NOT to use
+
+- Capturing what to build and why, from a fuzzy idea → `../specify/SKILL.md`.
+- Removing ambiguity / edge cases from an existing spec → `../clarify/SKILL.md`.
+- Slicing an approved plan into an ordered task checklist → `../tasks/SKILL.md`.
+- Concrete framework/ORM/test-runner mechanics → the relevant stack skill
+  (`../fastapi/SKILL.md`, `../nextjs/SKILL.md`, `../go/SKILL.md`, `../flutter/SKILL.md`,
+  `../postgresdb/SKILL.md`).
+- Project-wide non-negotiables (stack canon, quality bars) → `../constitution/SKILL.md`.
+
+## Next in the chain
+
+Plan written, indexed, decisions logged → hand off to **`../tasks/SKILL.md`**, which turns the
+sequencing section into an ordered, independently-verifiable task list with a done-check per task.
+If planning surfaced an ambiguity the spec never resolved, loop back to **`../clarify/SKILL.md`**
+before tasking.