rsc-universal 0.1.1

package/skills/php/references/type-system.md

@@ -0,0 +1,220 @@
+# PHP type system — depth
+
+Offloaded from SKILL.md. Patterns and edge cases for enums, docblock generics,
+`readonly`/`clone with`, property hooks, and asymmetric visibility. PHP 8.3 floor,
+8.4 default, 8.5 features flagged.
+
+## Enums: backed + interface + methods
+
+Enums are first-class types, not class constants. A backed enum maps each case to a scalar;
+a pure enum has no backing. Both can implement interfaces and carry methods and constants.
+
+```php
+<?php
+
+declare(strict_types=1);
+
+interface HasLabel {
+    public function label(): string;
+}
+
+enum Priority: int implements HasLabel {
+    case Low    = 10;
+    case Normal = 20;
+    case High   = 30;
+
+    // Methods: behavior travels with the closed set.
+    public function label(): string {
+        return match ($this) {
+            self::Low    => 'Low priority',
+            self::Normal => 'Normal',
+            self::High   => 'High priority',
+        };
+    }
+
+    // A static "named constructor" over the raw value.
+    public static function fromScore(int $score): self {
+        return match (true) {
+            $score >= 30 => self::High,
+            $score >= 20 => self::Normal,
+            default      => self::Low,
+        };
+    }
+
+    // Enum constants are allowed.
+    const Default = self::Normal;
+}
+```
+
+Parsing rules:
+
+- `Priority::from(20)` returns the case or **throws** `\ValueError` on a bad value.
+- `Priority::tryFrom(99)` returns `null` on a bad value — use it for untrusted input.
+- `Priority::cases()` returns every case in declaration order — iterate for menus/seeders.
+- `$case->value` is the backing scalar; `$case->name` is the case name string.
+
+Comparison is by identity: `$a === Priority::High` (cases are singletons). Never compare
+`->value` when you mean the case.
+
+## Docblock generics for PHPStan
+
+The engine has no runtime generics; PHPStan and Psalm read `@template` annotations and
+enforce them at analysis time. The runtime type stays `array`/`mixed`.
+
+```php
+<?php
+
+declare(strict_types=1);
+
+/**
+ * @template TKey of array-key
+ * @template TValue
+ */
+final class TypedMap {
+    /** @var array<TKey, TValue> */
+    private array $items = [];
+
+    /**
+     * @param TKey   $key
+     * @param TValue $value
+     */
+    public function set(int|string $key, mixed $value): void {
+        $this->items[$key] = $value;
+    }
+
+    /**
+     * @param TKey $key
+     * @return TValue|null
+     */
+    public function get(int|string $key): mixed {
+        return $this->items[$key] ?? null;
+    }
+
+    /** @return list<TValue> */
+    public function values(): array {
+        return array_values($this->items);
+    }
+}
+```
+
+Useful pseudo-types PHPStan understands: `list<T>` (a 0-indexed sequential array),
+`array<K, V>`, `non-empty-array<...>`, `non-empty-string`, `int<0, max>`, `class-string<T>`,
+`callable(int): string`. Prefer `list<T>` over `array<int, T>` when the array is a sequence
+— it documents and enforces the no-gaps invariant.
+
+`@template T of SomeInterface` bounds the parameter; `@template-covariant` allows variance on
+read-only containers. Annotate `@implements`/`@extends` when a class implements a generic
+interface so the type flows through.
+
+## readonly rules and the with-er pattern
+
+`readonly` properties are write-once: assignable only from inside the declaring class scope,
+and only before they hold a value. A `readonly class` makes every property readonly implicitly.
+
+Constraints to know:
+
+- A readonly property has no default value and must be typed.
+- You cannot `unset()` or re-assign it, even inside the class.
+- Cloning copies the value, but a plain `clone` then re-assigning a readonly prop in
+  `__clone` is **not** allowed before 8.3; from 8.3 you may reinitialize a readonly property
+  inside `__clone`. From **8.5**, prefer `clone with`.
+
+```php
+<?php
+
+declare(strict_types=1);
+
+final readonly class Point {
+    public function __construct(
+        public int $x,
+        public int $y,
+    ) {}
+
+    // Pre-8.5 with-er: build a new instance explicitly.
+    public function withX(int $x): self {
+        return new self($x, $this->y);
+    }
+}
+
+// 8.5+: clone with overrides named properties in one expression.
+$p2 = clone $p1 with ['x' => 10];   // y is copied, x is replaced
+```
+
+## Property hooks — edge cases (8.4+)
+
+A property may declare a `get` hook, a `set` hook, or both. A property with only a `get` hook
+and no backing assignment is **virtual** (computed, stores nothing).
+
+```php
+<?php
+
+declare(strict_types=1);
+
+final class User {
+    // Backed property with a guarded set and a normalizing get.
+    public string $email {
+        get => strtolower($this->email);
+        set (string $value) {
+            if (!filter_var($value, FILTER_VALIDATE_EMAIL)) {
+                throw new \InvalidArgumentException("invalid email: {$value}");
+            }
+            $this->email = $value;
+        }
+    }
+
+    // Virtual: no backing store, recomputed each read.
+    public string $domain {
+        get => substr($this->email, (int) strpos($this->email, '@') + 1);
+    }
+
+    public function __construct(string $email) {
+        $this->email = $email; // runs the set hook -> validation
+    }
+}
+```
+
+Gotchas:
+
+- Inside a hook, `$this->email` refers to the backing store, not the hook — no infinite loop
+  for a backed property. A **virtual** property (get-only, never assigned) must not reference
+  itself.
+- Hooks run on **every** access. Do not do I/O, queries, or state mutation in a `get` hook —
+  a field read becoming a side effect is a debugging trap. Use a named method instead.
+- Hooks are inheritable and can be declared in interfaces (an interface can require a property
+  with hooks).
+- PHPStan 2.1+ analyzes hooks; older analyzers will misreport them.
+
+## Asymmetric visibility matrix (8.4+)
+
+Read visibility and write (set) visibility are declared independently. Write visibility must
+be **equal to or narrower** than read visibility.
+
+| Declaration | Readable from | Writable from |
+|---|---|---|
+| `public int $n` | anywhere | anywhere |
+| `public protected(set) int $n` | anywhere | class + subclasses |
+| `public private(set) int $n` | anywhere | declaring class only |
+| `protected private(set) int $n` | class + subclasses | declaring class only |
+| `private int $n` | declaring class | declaring class |
+
+Use `public private(set)` for the common case: a value object whose fields are read freely
+but mutated only through intent-revealing methods (`deposit()`, `rename()`), without writing a
+getter for every field.
+
+```php
+<?php
+
+declare(strict_types=1);
+
+final class Counter {
+    public function __construct(public private(set) int $count = 0) {}
+    public function increment(): void { $this->count++; } // only path that writes
+}
+
+$c = new Counter();
+echo $c->count;   // ok: public read
+// $c->count = 5; // Error: write is private(set)
+```
+
+`readonly` plus `private(set)` is redundant — `readonly` already forbids writes after init.
+Choose `private(set)` when you need controlled mutation, `readonly` when you need none.

package/skills/php/scripts/verify.sh

@@ -0,0 +1,155 @@
+#!/usr/bin/env bash
+#
+# verify.sh - local quality gate for a PHP project (superset of CI).
+#
+# Usage:
+#   cd <your-php-project-root>   # the directory containing composer.json
+#   ./verify.sh
+#
+# Runs: composer validate, php -l syntax lint, Pint/PHP-CS-Fixer (style, dry-run),
+# PHPStan analyse, and PHPUnit/Pest - each only if the tool/config is present.
+# Missing tools are skipped with a yellow warning (not a failure).
+# Real problems (invalid composer.json, syntax errors, style/analysis/test failures)
+# exit non-zero. Read-only: never mutates your source or runs a formatter in fix mode.
+#
+# Portability: stock macOS bash 3.2 (no mapfile, no associative arrays, no unguarded
+# array expansion under `set -u`). Exits 0 on a clean project and on an empty src tree.
+
+set -euo pipefail
+
+# Colors only when stdout is a TTY (keeps logs/CI output clean).
+if [ -t 1 ]; then
+  YELLOW=$'\033[33m'; RED=$'\033[31m'; GREEN=$'\033[32m'; RESET=$'\033[0m'
+else
+  YELLOW=''; RED=''; GREEN=''; RESET=''
+fi
+
+failed=0
+
+have()  { command -v "$1" >/dev/null 2>&1; }
+warn()  { printf '%s[skip]%s %s\n' "$YELLOW" "$RESET" "$*"; }
+fail()  { printf '%s[fail]%s %s\n' "$RED" "$RESET" "$*"; failed=1; }
+ok()    { printf '%s[ ok ]%s %s\n' "$GREEN" "$RESET" "$*"; }
+info()  { printf -- '----- %s\n' "$*"; }
+
+# A binary may be a global on PATH or a project-local vendor/bin script. Resolve either.
+binof() {
+  if [ -x "vendor/bin/$1" ]; then printf 'vendor/bin/%s' "$1"; return 0; fi
+  if have "$1"; then printf '%s' "$1"; return 0; fi
+  return 1
+}
+
+# Must run from a project root.
+if [ ! -f composer.json ]; then
+  printf '%serror:%s no composer.json in %s - cd into your project root first.\n' \
+    "$RED" "$RESET" "$(pwd)" >&2
+  exit 2
+fi
+
+# Directories we lint/analyse, only those that exist.
+SRC_DIRS=""
+for d in src app lib tests; do
+  [ -d "$d" ] && SRC_DIRS="$SRC_DIRS $d"
+done
+
+# 1. composer validate - the manifest must be well-formed.
+info "composer validate"
+if have composer; then
+  if composer validate --strict --no-check-publish >/dev/null 2>&1; then
+    ok "composer.json valid"
+  else
+    # Re-run to surface the message, but a lockfile drift is a warning, not a hard fail.
+    if composer validate --no-check-publish >/dev/null 2>&1; then
+      warn "composer.json valid but not strict-clean (lock drift / metadata) - run: composer validate --strict"
+    else
+      fail "composer validate reported errors (run: composer validate)"
+    fi
+  fi
+else
+  warn "composer not found (https://getcomposer.org)"
+fi
+
+# 2. php -l syntax lint across the source tree. No files = nothing to do (clean exit).
+info "php -l (syntax lint)"
+if have php; then
+  if [ -z "$SRC_DIRS" ]; then
+    warn "no src/app/lib/tests directory to lint"
+  else
+    lint_failed=0
+    file_count=0
+    # find with -print0 + a while/read loop is bash-3.2 safe and space-safe.
+    while IFS= read -r -d '' f; do
+      file_count=$((file_count + 1))
+      if ! php -l "$f" >/dev/null 2>&1; then
+        php -l "$f" || true
+        lint_failed=1
+      fi
+    done < <(find $SRC_DIRS -name '*.php' -type f -print0 2>/dev/null)
+
+    if [ "$file_count" -eq 0 ]; then
+      warn "no .php files found under:$SRC_DIRS"
+    elif [ "$lint_failed" -ne 0 ]; then
+      fail "PHP syntax errors found"
+    else
+      ok "syntax clean ($file_count files)"
+    fi
+  fi
+else
+  warn "php not found - cannot lint/analyse/test"
+fi
+
+# 3. Style: Pint preferred, else PHP-CS-Fixer. Always dry-run / test mode (read-only).
+info "style (Pint / PHP-CS-Fixer)"
+if pint_bin="$(binof pint)"; then
+  if $pint_bin --test >/dev/null 2>&1; then
+    ok "pint clean"
+  else
+    fail "pint reports style issues (run: $pint_bin)"
+  fi
+elif fixer_bin="$(binof php-cs-fixer)"; then
+  if $fixer_bin fix --dry-run >/dev/null 2>&1; then
+    ok "php-cs-fixer clean"
+  else
+    fail "php-cs-fixer reports style issues (run: $fixer_bin fix)"
+  fi
+else
+  warn "no formatter found (composer require --dev laravel/pint)"
+fi
+
+# 4. PHPStan - only if a config exists (else we cannot know the intended level).
+info "phpstan"
+if [ -f phpstan.neon ] || [ -f phpstan.neon.dist ] || [ -f phpstan.dist.neon ]; then
+  if stan_bin="$(binof phpstan)"; then
+    if $stan_bin analyse --no-progress >/dev/null 2>&1; then
+      ok "phpstan clean"
+    else
+      $stan_bin analyse --no-progress || true
+      fail "phpstan reported issues"
+    fi
+  else
+    warn "phpstan config present but binary not found (composer require --dev phpstan/phpstan)"
+  fi
+else
+  warn "no phpstan.neon - skipping static analysis"
+fi
+
+# 5. Tests: Pest preferred, else PHPUnit - only if a test config/dir exists.
+info "tests (Pest / PHPUnit)"
+if [ -f phpunit.xml ] || [ -f phpunit.xml.dist ] || [ -f Pest.php ] || [ -d tests ]; then
+  if pest_bin="$(binof pest)"; then
+    if $pest_bin >/dev/null 2>&1; then ok "pest green"; else fail "pest failed (run: $pest_bin)"; fi
+  elif phpunit_bin="$(binof phpunit)"; then
+    if $phpunit_bin >/dev/null 2>&1; then ok "phpunit green"; else fail "phpunit failed (run: $phpunit_bin)"; fi
+  else
+    warn "tests present but no runner found (composer require --dev pestphp/pest)"
+  fi
+else
+  warn "no phpunit.xml / tests dir - skipping tests"
+fi
+
+echo
+if [ "$failed" -ne 0 ]; then
+  printf '%sFAIL:%s one or more checks failed.\n' "$RED" "$RESET"
+  exit 1
+fi
+printf '%sPASS:%s all checks passed.\n' "$GREEN" "$RESET"

package/skills/pitch-deck/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: pitch-deck
+description: "Use when building or fixing an investor fundraising deck — the narrative arc, the slide-by-slide story, and the small set of numbers that actually move an investment decision, for a pre-seed, seed, or Series A raise (and the close cousin, a YC/accelerator application deck). Decides WHAT goes on each slide, in what order, and with which metric; sequences the story the way a VC evaluates risk (problem → solution → why-now → market → traction → team → ask). Triggers: 'build our seed pitch deck', 'what slides do I need to raise pre-seed', 'write the traction slide and the ask slide', 'investors lose interest after slide 3', 'tighten the fundraising story before demo day', 'monta el pitch deck para inversores', 'prepara la ronda seed', 'el deck per a la presentació a inversors'. NOT rendering/exporting/theming the slides into a designed PDF or PPTX (that is presentations), NOT the projection spreadsheet behind the numbers (that is financial-model)."
+tags: [pitch-deck, fundraising, investor-deck, startup]
+recommends: [presentations, financial-model, investor-materials, unit-economics, fundraising, marketing]
+origin: risco
+---
+
+# Pitch deck — the fundraising story, slide by slide
+
+> You are a fundraising story editor that thinks in slides and in evidence. Your output is the founder's
+> argument for *why invest, why this team, why now* — the narrative arc, the slide-by-slide content, and the
+> few numbers that decide the meeting. You decide WHAT goes on each slide, in what ORDER, and with which
+> METRIC. You do **not** draw the slides, build the spreadsheet, or write the SAFE terms. You write the pitch,
+> then hand the rest off.
+
+Scope: pre-seed → Series A investor decks, plus the accelerator/YC application deck. This is *not* a sales or
+demo deck (selling product to customers → `presentations`) and *not* a customer proof story (→ `case-studies`).
+
+## What you produce — and what you hand off
+
+You own the story and the numbers ON the deck. The moment the job becomes design, math, or paperwork, route it
+out. Naming the boundary keeps this skill from bloating into a slide renderer or a spreadsheet.
+
+| The job | Owner | Why it is not yours |
+| --- | --- | --- |
+| Story order, slide content, which metric goes where | **pitch-deck** (you) | This is the pitch — the persuasion lives in sequence + evidence. |
+| Render/theme/export slides to PDF or PPTX (Marp/Slidev/python-pptx) | `../presentations/SKILL.md` | Design + export is a different craft; you hand it a locked outline. |
+| The revenue projection, cohort model, burn/runway, valuation math | `financial-model` | The spreadsheet *produces* the numbers; you only put the decision-grade few on a slide. |
+| One-pager, exec memo, data room, investor-update FAQ, SAFE prep | `investor-materials` | The non-deck raise collateral around the deck. |
+| The standalone CAC/LTV/payback health check itself | `unit-economics` | You cite the verdict; you do not run the analysis. |
+| Round strategy, target-investor list, outreach sequencing | `fundraising` | The raise *process*, not the deck content. |
+| Polishing the deck's WORDS (headline craft, voice, ban-list) | `../marketing/SKILL.md` | Copy craft; you set the deck-shaped structure those words fill. |
+
+Rule: **lock the outline here, then hand off.** Do not start theming colors or building a model inside this
+skill — that is scope creep, and it buries the narrative work that only you do.
+
+## First principle: front-load belief
+
+A VC reads a deck the way you skim a cold email. DocSend's data puts the average first read at roughly
+**2m24s–3m44s total — under ~20 seconds a slide.** That is the whole budget. It forces three rules:
+
+- **Win belief in the first ~5 slides.** Problem → solution → why-now → market have to land before attention
+  decays — because nobody reaches slide 12 if slide 3 lost them.
+- **Depth goes to the follow-up, not the page.** Extra detail (the full model, the cohort tables, the
+  competitive teardown) lives in the *conversation* and the data room — because a slide read in 19 seconds
+  cannot hold it, and crowding it kills the slides that matter.
+- **Every slide earns its place or is cut.** If a slide does not move the investment decision, it is stealing
+  seconds from one that does — so it goes to the appendix or the bin.
+
+## The canonical spine (10 + the ask)
+
+The disciplined spine is **10 core slides plus an ask — keep it under ~15.** DocSend's survey found decks of
+11–20 slides raised more successfully (~43% higher); past that, more slides *hurt* (extra material belongs in
+the conversation). Each slide has exactly one job and answers one investor question.
+
+| # | Slide | Its one job | The investor question it answers |
+| --- | --- | --- | --- |
+| 1 | Title / purpose | State what you do in one line | "What is this, in a sentence?" |
+| 2 | Problem | Make the pain ache, for a real who | "Is this a real, urgent problem?" |
+| 3 | Solution | Show the insight that solves it | "Does their thing actually solve it?" |
+| 4 | Why now | Name the shift that makes this the moment | "Why hasn't this been done — why now?" |
+| 5 | Market | TAM/SAM/SOM, bottom-up and sourced | "Is the prize big enough to matter?" |
+| 6 | Product | One concrete proof it works (a visual, a flow) | "Is this real or a slide?" |
+| 7 | Business model | How a dollar in becomes more dollars out | "How does this make money?" |
+| 8 | Traction | The growth SHAPE + the few key metrics | "Is it working, and accelerating?" |
+| 9 | Competition | Honest landscape + your wedge | "Why don't incumbents just crush them?" |
+| 10 | Team | Why *this* team wins *this* | "Can these people actually pull it off?" |
+| 11 | The ask | Amount → use-of-funds → milestone it buys | "What do you need, and what does it buy?" |
+
+Full per-slide template (what content goes on each, an example line, the trap to avoid) and the stage deltas
+(pre-seed / seed / Series A: what each slide may claim) live in `references/slide-spine.md`. Read it before
+drafting; do not improvise the order.
+
+## Sequence is the persuasion
+
+Investors read in **risk-evaluation order**: believe the problem → understand the solution → trust the market
+→ see the proof → back the team → know the ask. Reordering breaks the logic and makes the business harder to
+grasp in the 19 seconds a slide gets. The order *is* the argument.
+
+```text
+Bad  (founder-centric)              Good  (investor-risk order)
+1 Look at our product!              1 Here is a painful, real problem
+2 17 features, a demo tour          2 Here is the insight that solves it
+3 Our amazing team                  3 Why this is solvable now and not before
+4 ... oh, the problem               4 The market is big and reachable
+5 The ask                           5 Proof: it works and it is growing
+                                    6 This team is why it wins → the ask
+```
+
+Open with the *problem*, never with a feature tour. A feature tour answers a question the investor has not
+asked yet ("does this solve a real problem?") and burns the front-loaded attention on the wrong thing.
+
+## The numbers that matter
+
+At seed, the decision rides on a **small set** of numbers — not the whole P&L. Pick the few that tell *your*
+story and put them where they belong (traction, business model, the ask). The set and healthy bands:
+
+| Metric | What it shows | Healthy band (2025/26) |
+| --- | --- | --- |
+| MRR/ARR + MoM growth | Are you growing, and how fast | ~15–20% MoM (<$1M ARR); ~8–15% MoM ($1M–$10M ARR) |
+| LTV : CAC | Is acquisition profitable | **≥ 3:1** |
+| CAC payback | Months to earn back acquisition cost | **< ~18 months** (the 2024 median; lower = above average) |
+| Gross margin | How much of revenue is yours to keep | software typically 70%+ |
+| Net revenue retention | Do existing customers expand | **> 110%** |
+| Burn / runway | Cash out per month / months left | runway names the ask (below) |
+
+Formulas and the full glossary → `references/numbers-that-matter.md`. The model that *computes* these is
+`financial-model`; the deep CAC/LTV health check is `unit-economics`. This skill only decides which numbers
+go ON the deck and what "good" looks like.
+
+**Growth shape beats absolute size.** Traction is the highest-stakes slide — investors spend ~3× longer on it,
+and **76% of "no" decisions cite weak traction.** A company at **$50K MRR growing 25% MoM consistently** reads
+stronger than one at **$200K MRR that is flat or erratic.** Show the curve, not just the point.
+
+```text
+Bad traction slide                 Good traction slide
+"We have 10,000 users."            "$50K MRR, +22% MoM for 5 straight months (curve shown);
+"Huge interest!"                    NRR 118%; 40 paying logos incl. [2 names]; LTV:CAC 4:1."
+ (a vanity number, no shape,        (a number + a unit + a trend + a band — the SHAPE is visible)
+  no unit, no trend)
+```
+
+Never show registered users without an activation/paying rate behind them — a count with no engagement is a
+vanity metric, and a sharp investor reads it as hiding the real number.
+
+## The ask slide
+
+The ask names three things, in this order: **the amount → the use-of-funds allocation → the milestone it
+buys.** An ask with no number, or no milestone, reads as "we have not done the math."
+
+```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.
+```
+
+The milestone is the point. "$1.5M for 18 months" is a burn statement; "$1.5M → 18 months → $100K MRR /
+Series-A-ready" is an *investment thesis* — it tells the VC what their money de-risks and what the next round
+will look like. Tie the allocation to the milestone; if a line item does not move you toward it, cut it.
+
+## Market sizing, honestly
+
+Size **bottom-up first**, then sanity-check top-down — and source every number. TAM/SAM/SOM and the ask are
+the two slides investors scrutinize hardest for realism.
+
+```text
+Bad   "The market is $1.2 trillion — we only need 1% of it."
+Good  "120,000 target SMBs in our segment × $4.8K ACV = $576M SAM (sourced: [registry/report]).
+       Bottom-up reachable in 3 yrs (SOM): 3,000 accounts = $14.4M ARR."
+```
+
+The "$X trillion, we just need 1%" move is a credibility tell — it shows you reasoned top-down from a number
+too big to mean anything. Build up from a unit (accounts × price), name the source, and let the big number be
+the *result*, not the premise.
+
+## Stage deltas (short)
+
+What each stage is allowed to claim — full table in `references/slide-spine.md`:
+
+- **Pre-seed** sells the **team + the insight**. Little traction yet; the bet is the founders and the wedge.
+- **Seed** sells the **early traction shape** — growth trend, early retention, the first signs of a model.
+- **Series A** sells a **repeatable growth engine** — efficient, predictable acquisition and expansion you can
+  pour fuel on.
+
+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 that hides real traction behind a vision) wastes your best card.
+
+## Anti-patterns
+
+| Anti-pattern | Why it's wrong | Do instead |
+| --- | --- | --- |
+| "No competition" / "we have no competitors" | Reads as naive or as "no market" | Map the honest landscape + your specific wedge |
+| Ask slide with no amount or no milestone | "They have not done the math" | Amount → use-of-funds → the milestone it buys |
+| Vanity metrics (registered users, no activation) | Hides the real number; investors notice | Show the metric WITH its rate/trend (paying, active, MoM) |
+| 25–30 slide deck | Past ~15 it hurts; attention is gone | 10 + ask; depth to the data room / conversation |
+| Designing/theming before the story is locked | Polishing the wrong outline | Lock the spine here, THEN hand to `presentations` |
+| Hockey-stick projection with no driver | A curve with no mechanism is fiction | Tie growth to a named driver; cite the model |
+| Opening with a feature tour | Answers a question not yet asked | Open with the problem (risk order) |
+| "$X trillion × 1%" market | Top-down hand-wave, credibility tell | Bottom-up: accounts × price, sourced |
+| Buzzwords ("revolutionary", "disruptive", "world-class") | Hollow; says nothing falsifiable | A number, a mechanism, a receipt |
+| Reading the deck aloud verbatim | Slide and voice become redundant | Slide = the claim + proof; you narrate the story |
+
+## Verify + references
+
+Run the structural linter against a deck outline (markdown, one slide per heading) before handing off:
+
+```bash
+./scripts/verify.sh path/to/deck.md          # required-slide presence, count, ask + traction numbers, buzzwords
+./scripts/verify.sh --strict path/to/deck.md # warnings become failures (CI gate)
+```
+
+It is a structural/numeric lint only — required core slides present, count ≤ 15, the ask names an amount + a
+use-of-funds/milestone token, traction carries a metric with a unit, and a buzzword warning. **Narrative
+quality is graded by the capability eval, not by grep.** Exits 0 on a clean/empty target; non-zero only on a
+missing core slide or a numberless ask.
+
+References:
+
+- `references/slide-spine.md` — full ordered slide-by-slide template (one job + investor question + what goes
+  on it + an example line + the trap), the ask/use-of-funds block, and the pre-seed/seed/Series A stage deltas.
+- `references/numbers-that-matter.md` — the seed/Series A metric glossary (formula + current benchmark band),
+  the "growth shape" framing, and Bad→Good traction examples; defers the model to `financial-model` and the
+  CAC/LTV health check to `unit-economics`.
+
+See also: `../presentations/SKILL.md` (renders + exports the locked outline), `../marketing/SKILL.md` (polishes
+the words), `../harness/SKILL.md` (the `02-DOCS` wiki where deck/raise conventions persist). The siblings
+`financial-model`, `investor-materials`, `unit-economics`, and `fundraising` are named in the route-out table
+above; link them once they exist in the catalog.

package/skills/pitch-deck/evals/README.md

@@ -0,0 +1,15 @@
+# Evals — pitch-deck
+
+These cases check two things: that the skill's description/triggers ROUTE correctly, and that the SKILL.md
+content contract actually holds. Run them with the repo's eval harness if one is wired up, or read-and-judge
+manually. `should_trigger` prompts must select `pitch-deck` (they include non-obvious cases — a narrative
+diagnosis, a story-tightening, a market-slide judgment call — plus a Spanish trigger). `should_not_trigger`
+prompts must route to the named real sibling instead (`presentations` for rendering/sales decks,
+`financial-model` for the projection spreadsheet, `investor-materials` for the one-pager/data room,
+`unit-economics` for the CAC/LTV health check, `fundraising` for the raise process). The `capability` cases are
+graded against their `must_include` rubric: a correct response produces a ~10-slide + ask outline in
+risk-evaluation order, shows the growth SHAPE on traction, names amount + use-of-funds + milestone on the ask,
+sizes the market bottom-up, respects the stage, defers rendering and modeling to the right siblings, and stays
+within the ~15-slide discipline. The mechanical slide-structure subset (required slides, count, ask + traction
+numbers, buzzwords) is enforced by `../scripts/verify.sh` against a deck outline; narrative quality is judged
+here, not by grep.

package/skills/pitch-deck/evals/cases.yaml

@@ -0,0 +1,55 @@
+skill: pitch-deck
+
+should_trigger:
+  - prompt: "Help me build our seed pitch deck for investors."
+    why: "Core use case: writing the fundraising-deck narrative and slide content for a seed raise. This skill owns the story order and the deck-level numbers."
+  - prompt: "What slides do I need to raise a pre-seed round?"
+    why: "A request for the slide spine / deck structure at a named stage — the canonical 10 + ask spine and stage deltas are exactly this skill."
+  - prompt: "Investors keep losing interest after slide 3 — can you fix our deck's narrative?"
+    why: "Non-obvious: a narrative DIAGNOSIS, not a build request. The front-load-belief principle and risk-order sequencing are the cure this skill owns; it is not asking to render slides."
+  - prompt: "Write the traction slide and the ask slide for our Series A deck."
+    why: "Slide-level content — the two highest-stakes slides (growth shape, amount/use-of-funds/milestone). Deciding what metric and what ask go on a slide is this skill's job."
+  - prompt: "Prepara el pitch deck para la ronda seed."
+    why: "Spanish trigger for building a seed fundraising deck — same core use case, named explicitly in the description triggers."
+  - prompt: "Tighten our fundraising story before demo day."
+    why: "Non-obvious: story-arc tightening for an accelerator/demo-day pitch, not a slide-design task. The narrative arc and slide ordering are this skill's center."
+  - prompt: "Our market slide says we just need 1% of a trillion-dollar market — does that hurt us?"
+    why: "Non-obvious: a content-judgment question about the market slide. Bottom-up TAM/SAM/SOM and the over-claim trap are this skill's market-sizing guidance."
+
+should_not_trigger:
+  - prompt: "Export our deck to PDF and PPTX with our brand colors and a clean theme."
+    route_to: presentations
+    why: "Rendering, theming, and exporting the slides is presentations' craft; pitch-deck hands it a locked outline and does not draw or export pixels."
+  - prompt: "Build the 3-year revenue projection and burn/runway model behind these numbers."
+    route_to: financial-model
+    why: "The spreadsheet that COMPUTES the projections is financial-model; pitch-deck only places the decision-grade few numbers on a slide."
+  - prompt: "Draft the investor one-pager and the data-room checklist for the raise."
+    route_to: investor-materials
+    why: "The non-deck raise collateral (one-pager, memo, data room, FAQ) is investor-materials; pitch-deck writes the deck itself, not the package around it."
+  - prompt: "Is our CAC/LTV actually healthy? Run the full unit-economics analysis by channel."
+    route_to: unit-economics
+    why: "The standalone CAC/LTV/payback health check is unit-economics; pitch-deck cites the headline band on a slide but does not run the analysis."
+  - prompt: "Make a sales deck to demo our product to enterprise customers."
+    route_to: presentations
+    why: "A sales/demo deck sells product to customers, not equity to investors — that is a presentations deck, not a fundraising pitch."
+  - prompt: "Plan our raise: build the target-investor list and the outreach sequence."
+    route_to: fundraising
+    why: "The raise PROCESS — investor targeting, outreach, round strategy — is fundraising; pitch-deck produces only the deck content."
+
+capability:
+  - scenario: "A pre-seed SaaS founder gives raw context: problem is finance teams closing books in spreadsheets; an early product ships; $40K MRR growing 22% MoM for 5 straight months; 2 technical/finance founders; wants to raise $1.2M. 'Turn this into a pitch deck.'"
+    must_include:
+      - "Produces a ~10-slide + ask outline (problem, solution, why-now, market, product, business model, traction, competition, team, ask) in risk-evaluation order, kept under ~15 slides."
+      - "Traction slide shows the growth SHAPE — $40K MRR with the +22% MoM, 5-month trend/curve — not just the single $40K figure; each number carries a unit."
+      - "Ask slide names all three: the amount ($1.2M), a use-of-funds allocation, and the milestone the runway buys (e.g. months of runway to a target MRR / Series-A readiness)."
+      - "Sizes the market bottom-up (accounts x price, sourced), explicitly avoiding the '$X trillion, we just need 1%' top-down hand-wave."
+      - "Frames pre-seed correctly: sells the team + insight, does not over-claim a Series-A 'repeatable engine'."
+      - "Defers rendering/theming/export to presentations and the projection/burn model to financial-model instead of building them here."
+      - "Flags any vanity or over-claim (e.g. registered users without an activation/paying rate, hollow superlatives) and keeps the deck within the ~15-slide discipline."
+  - scenario: "A founder says 'our deck has 28 slides and investors zone out after slide 3 — fix it.'"
+    must_include:
+      - "Diagnoses front-loading: belief must be won in the first ~5 slides because a first read is ~2.5-3.7 minutes (~19s/slide); depth moves to the conversation/data room."
+      - "Cuts the deck toward the 10 + ask spine, well under ~15 slides, moving appendix-grade detail off the deck."
+      - "Re-sequences into investor risk order (problem -> solution -> why-now -> market -> proof -> team -> ask) and calls out any feature-tour opening as the wrong front."
+      - "Identifies which slides do not move the investment decision and cuts or appendixes them."
+      - "Hands the re-themed/re-exported result to presentations once the outline is locked, rather than redesigning slides itself."