@openrig/cli 0.4.8 → 0.5.1

package/daemon/docs/reference/worktree-builds.md

@@ -0,0 +1,39 @@
+# Worktree builds: use a per-worktree install, never a symlinked `node_modules`
+
+**Filed as** build friction (a TS2688 `@types/node` failure). **Grounded as** something worse:
+the symlink shortcut that avoids the install produces builds and typechecks that silently
+consume ANOTHER tree's source — a false-green generator, not an inconvenience.
+
+## What actually happens
+
+`npm install` in a worktree creates `node_modules/@openrig/<pkg>` as a RELATIVE symlink
+(`-> ../../packages/<pkg>`). Relative links resolve against the directory they live in, so:
+
+| setup | `@openrig/daemon` resolves to | verdict |
+|---|---|---|
+| per-worktree `npm install` | that worktree's `packages/daemon` | correct |
+| `ln -s <primary>/node_modules node_modules` | **the PRIMARY tree's** `packages/daemon` | **cross-tree** |
+
+Verified by discriminator, not by inference: with a symlinked `node_modules`, a deliberate type
+error introduced in the WORKTREE's `packages/daemon` is seen by that package's own `tsc` and NOT
+seen by `packages/cli`'s `tsc`, which exits 0 — because it type-checked the primary tree's daemon.
+A worktree can therefore report green against code it does not contain.
+
+## Rules
+
+1. **Run `npm install` in each worktree** (~4s, one time). It is not the slow path; it is the
+   only path that resolves workspace packages to the worktree's own source.
+2. **Never symlink `node_modules` from the primary checkout.** It appears to work — builds pass,
+   typechecks pass — which is exactly the danger.
+3. **`npx tsc` with no `node_modules` installs an unrelated 12-year-old `tsc` package** and prints
+   "This is not the tsc command you are looking for". That message means *no install*, not a
+   TypeScript error.
+4. **Build `@openrig/daemon` before typechecking `@openrig/cli`** in a fresh worktree: cli imports
+   `@openrig/daemon/crash-cart` etc., which resolve to daemon's `dist`. Absent dist reads as
+   TS2307 "Cannot find module" plus a cascade of implicit-any — a provisioning artifact, not a
+   code defect.
+
+## Self-check before trusting any worktree build
+
+    [ "$(readlink -f packages/daemon)" = "$(readlink -f node_modules/@openrig/daemon)" ] \
+      || echo "CROSS-TREE: this worktree resolves @openrig/* into another tree"

package/daemon/specs/agents/apps/vault-specialist/agent.yaml

@@ -15,7 +15,7 @@ profiles:
       guidance: []
       subagents: []
       plugins: [shared:openrig-core]
-      runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config]
+      runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config, shared:claude-activity-hooks]
 
 resources:
   guidance:

package/daemon/specs/agents/conveyor/builder/agent.yaml

@@ -15,7 +15,7 @@ profiles:
       guidance: []
       subagents: []
       plugins: [shared:openrig-core]
-      runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config]
+      runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config, shared:claude-activity-hooks]
 
 resources:
   guidance:

package/daemon/specs/agents/conveyor/lead/agent.yaml

@@ -15,7 +15,7 @@ profiles:
       guidance: []
       subagents: []
       plugins: [shared:openrig-core]
-      runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config]
+      runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config, shared:claude-activity-hooks]
 
 resources:
   guidance:

package/daemon/specs/agents/conveyor/planner/agent.yaml

@@ -15,7 +15,7 @@ profiles:
       guidance: []
       subagents: []
       plugins: [shared:openrig-core]
-      runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config]
+      runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config, shared:claude-activity-hooks]
 
 resources:
   guidance:

package/daemon/specs/agents/conveyor/reviewer/agent.yaml

@@ -15,7 +15,7 @@ profiles:
       guidance: []
       subagents: []
       plugins: [shared:openrig-core]
-      runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config]
+      runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config, shared:claude-activity-hooks]
 
 resources:
   guidance:

package/daemon/specs/agents/design/product-designer/agent.yaml

@@ -15,7 +15,7 @@ profiles:
       guidance: []
       subagents: []
       plugins: [shared:openrig-core]
-      runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config]
+      runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config, shared:claude-activity-hooks]
 
 resources:
   guidance:

package/daemon/specs/agents/development/implementer/agent.yaml

@@ -15,7 +15,7 @@ profiles:
       guidance: []
       subagents: []
       plugins: [shared:openrig-core]
-      runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config]
+      runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config, shared:claude-activity-hooks]
 
 resources:
   guidance:

package/daemon/specs/agents/development/qa/agent.yaml

@@ -15,7 +15,7 @@ profiles:
       guidance: []
       subagents: []
       plugins: [shared:openrig-core]
-      runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config]
+      runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config, shared:claude-activity-hooks]
 
 resources:
   guidance:

package/daemon/specs/agents/factory-rsi/dogfood/agent.yaml

@@ -15,7 +15,7 @@ profiles:
       guidance: []
       subagents: []
       plugins: [shared:openrig-core]
-      runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config]
+      runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config, shared:claude-activity-hooks]
 
 resources:
   guidance:

package/daemon/specs/agents/factory-rsi/release-manager/agent.yaml

@@ -15,7 +15,7 @@ profiles:
       guidance: []
       subagents: []
       plugins: [shared:openrig-core]
-      runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config]
+      runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config, shared:claude-activity-hooks]
 
 resources:
   guidance:

package/daemon/specs/agents/orchestration/orchestrator/agent.yaml

@@ -15,7 +15,7 @@ profiles:
       guidance: []
       subagents: []
       plugins: [shared:openrig-core]
-      runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config]
+      runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config, shared:claude-activity-hooks]
 
 resources:
   guidance:

package/daemon/specs/agents/product-management/pm/agent.yaml

@@ -27,6 +27,7 @@ profiles:
         - shared:claude-default-settings
         - shared:claude-default-mcp
         - shared:codex-default-config
+        - shared:claude-activity-hooks
 
 resources:
   guidance:

package/daemon/specs/agents/research/analyst/agent.yaml

@@ -15,7 +15,7 @@ profiles:
       guidance: []
       subagents: []
       plugins: [shared:openrig-core]
-      runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config]
+      runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config, shared:claude-activity-hooks]
 
 resources:
   guidance:

package/daemon/specs/agents/research/synthesizer/agent.yaml

@@ -15,7 +15,7 @@ profiles:
       guidance: []
       subagents: []
       plugins: [shared:openrig-core]
-      runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config]
+      runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config, shared:claude-activity-hooks]
 
 resources:
   guidance:

package/daemon/specs/agents/review/independent-reviewer/agent.yaml

@@ -15,7 +15,7 @@ profiles:
       guidance: []
       subagents: []
       plugins: [shared:openrig-core]
-      runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config]
+      runtime_resources: [shared:claude-default-settings, shared:claude-default-mcp, shared:codex-default-config, shared:claude-activity-hooks]
 
 resources:
   guidance:

package/daemon/specs/agents/shared/agent.yaml

@@ -20,6 +20,8 @@ resources:
       path: skills/core/openrig-architect
     - id: rig-lifecycle
       path: skills/core/rig-lifecycle
+    - id: openrig-upgrade
+      path: skills/core/openrig-upgrade
     - id: systematic-debugging
       path: skills/process/systematic-debugging
     - id: test-driven-development
@@ -67,5 +69,9 @@ resources:
       path: runtime/codex-config.fragment.toml
       runtime: codex
       type: codex_config_fragment
+    - id: claude-activity-hooks
+      path: runtime/claude-activity-hooks.json
+      runtime: claude-code
+      type: claude_activity_hooks
 
 profiles: {}

package/daemon/specs/agents/shared/runtime/claude-activity-hooks.json

@@ -0,0 +1,4 @@
+{
+  "openrig_activity_hooks": true,
+  "note": "Selection marker for the managed Claude activity-relay hooks. Delivery is performed by the daemon (ClaudeCodeAdapter reconcile) using the shipped activity-relay.cjs + the canonical claude.json hooks manifest; this asset carries no projected content."
+}

package/daemon/specs/agents/shared/skills/core/cross-host-rig-commands/SKILL.md

@@ -180,11 +180,16 @@ Deferred:
 - `seat-continuity-and-handover` skill — host-aware seat-binding semantics for cross-host handover (deferred to v1 on top of this v0 baseline)
 - `openrig-user` skill — the local CLI surface that cross-host commands wrap
 
-## Sender identity is ASYMMETRIC (verified vs current main, 2026-07-25)
-
-The `@host` sugar is **target-addressing only**, not sender-identity. A cross-host
-message's **From:** is `member@rig` — the sender carries **NO `@host` suffix**. The target
-supports `member@rig@<host>` for addressing; the sender does not reflect its own host in
-`From:`. **Do NOT teach or expect a host-qualified `from`** (in openrig-user / operator send
-docs or anywhere) until that core gap is fixed. (pm@your-rig verified this against
-current main, 2026-07-25 — a known asymmetry, not a doc error to paper over.)
+## Sender identity carries the ORIGIN host (51-09, 2026-08-06)
+
+The `@host` sugar on a TARGET is **addressing** (`member@rig@<host>` routes to that host).
+The **From:** sender now ALWAYS carries the **origin** host: a cross-host (and local) message's
+signature is **`member@rig@<originHost>`** — the sender reflects the host it was sent from, so a
+received signature names the ORIGIN, and the `↩ Reply:` hint round-trips **verbatim** back to that
+origin (never a same-named local lookalike). This is the always-suffix rule — deterministic and
+collision-proof: a signature means one thing to every receiver. (This SUPERSEDES the pre-51-09
+asymmetry — "the sender carries no `@host` suffix" — that pm@your-rig flagged as a core gap on
+2026-07-25; 51-09 closed it.) Per BR-1 the host is NEVER folded into the session string on the
+wire: the CLI edge renders/strips it, the daemon refuses an in-band 3-part destination with a
+teaching hint, and a stale 2-part same-name destination is closed by `--host` + that teaching —
+not by any in-string magic.

package/daemon/specs/agents/shared/skills/core/openrig-architect/SKILL.md

@@ -246,6 +246,8 @@ rig spec validate rig.yaml
 rig agent validate agents/my-agent/agent.yaml
 ```
 
+Then run `rig spec audit rig.yaml` for advisory checks such as stale seat references and other cross-file drift that schema validation cannot detect.
+
 If validation fails, fix the errors. Do not try to launch an invalid spec — it will fail with a less helpful error.
 
 ## Diagnosis: When Things Go Wrong

package/daemon/specs/agents/shared/skills/core/watchdog/SKILL.md

@@ -15,6 +15,7 @@ metadata:
       - intake-routing
       - human-in-the-loop
       - status-not-chat-orchestrator
+      - oversight-team
 ---
 
 # Watchdog

package/daemon/specs/agents/shared/skills/pm/backlog-capture/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: backlog-capture
+description: "Quickly capture product ideas, feature requests, or insights from meetings and conversations. Rapid documentation with smart categorization and deduplication."
+---
+
+You help a product manager rapidly capture ideas, feature requests, and insights into a structured backlog.
+
+## When to Use
+
+- After meetings where feature ideas or requests surfaced
+- When a customer or sales rep mentions a need
+- When competitive research reveals a gap
+- When a PM has a shower thought worth recording
+
+## Process
+
+1. **Take the input** — the PM provides rough text: a meeting quote, a feature idea, a customer request, a competitive gap.
+
+2. **Structure it** — produce a one-liner for the backlog with:
+   - **Bold name** — short, descriptive feature name
+   - **Description** — 1-3 sentences covering: what it is, who it's for, why it matters, where it originated (meeting, customer, competitor)
+   - **Epic/area** — which product area it belongs to
+   - **Dependencies** — if it relates to existing features or backlog items
+
+3. **Check for duplicates** — search the existing backlog for similar items. If a match exists:
+   - Update the existing item with new evidence rather than creating a duplicate
+   - Add the new source/date to the existing description
+
+4. **Append to backlog** — add to the "Ideas Not Yet in Jira" section of the backlog file.
+
+## Output Format
+
+```markdown
+- **[Feature Name]** — [Description. Who needs it. Why. Origin (meeting/customer/competitor, date).] Belongs under [Epic] epic. [Dependencies if any.]
+```
+
+## Guidelines
+
+- **Capture fast, refine later.** The goal is not to lose the idea. Polish comes during prioritization.
+- **Include the source.** "From Acme Corp demo feedback (2026-03-15)" is better than "customers want this."
+- **Convert relative dates to absolute.** "Next Thursday" becomes "2026-04-10."
+- **One idea per entry.** If a meeting produced 5 ideas, create 5 entries.
+- **Don't validate here.** That's what `/office-hours` is for. Just capture.

package/daemon/specs/agents/shared/skills/pm/context-builder/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: context-builder
+description: "Gather and distill context from meetings, competitors, regulatory sources, and internal discussions. Produces background.md for a feature and updates shared context docs when new knowledge is discovered."
+---
+
+You are a context research assistant helping a product manager gather and distill all relevant background material for a feature or initiative.
+
+## What You Produce
+
+1. **background.md** — Feature-specific context summary. Goes in the feature folder. References shared context sources.
+2. **Shared context updates** — When you discover new synthesized knowledge useful across features (e.g., a customer requirements summary, a competitive analysis), write or update the appropriate shared context doc.
+
+## Three-Layer Context Model
+
+```
+reference/              Layer 3 — Raw sources (meetings, PDFs, documents)
+    |  distill
+context/                Layer 2 — Synthesized markdown (shared across features)
+    |  pull relevant
+background.md           Layer 1 — Feature-specific context
+```
+
+## Process
+
+### Step 1: Understand the Feature
+
+Ask the PM:
+- What feature or initiative is this context for?
+- What aspects are most important? (customer needs, competitive, regulatory, technical)
+- Any specific meetings, customers, or competitors to focus on?
+
+### Step 2: Search and Gather
+
+Search across all layers. Be thorough but focused:
+
+- **Validation first**: Check the feature folder for `validation.md` (office hours output). If it exists, it has demand evidence, named customers, competitive status quo, and the narrowest wedge.
+- **Shared context first**: Check if synthesized context already exists.
+- **Meetings**: Search by topic keywords, customer names. Check last 3-6 months.
+- **Competitors**: Check competitor research for existing analysis.
+- **Regulatory**: Find applicable regulations.
+- **Customers**: Look for customer requests and pain points.
+- **Existing specs**: Check for related work and shipped features.
+
+### Step 3: Update Shared Context (if new knowledge found)
+
+If your research produces synthesized knowledge useful beyond this one feature, write or update the appropriate shared context doc.
+
+### Step 4: Write background.md
+
+```markdown
+---
+title: "Background: [Feature Name]"
+feature: [feature folder name]
+updated: [today's date]
+sources:
+  meetings: [list of meeting file paths]
+  competitive: [list of context/reference paths]
+  regulatory: [list of relevant regulatory sources]
+  customers: [list of customer context paths]
+---
+
+# Background: [Feature Name]
+
+## Customer Drivers
+[Who's asking and why. Key quotes and pain points.]
+
+## Competitive Landscape
+[How competitors handle this. Where we differentiate.]
+
+## Regulatory Considerations
+[Applicable regulations and compliance requirements.]
+
+## Persona Context
+[Which personas use this. Day-in-the-life context.]
+
+## Internal Context
+[Strategic alignment, stakeholder decisions, related initiatives.]
+```
+
+## Guidelines
+
+- **Reference, don't duplicate.** Point to source files rather than copying content.
+- **Distill, don't dump.** background.md should be under 500 lines.
+- **Include sources for everything.** Every claim traces back to a meeting, report, or decision.
+- **Highlight what's surprising or non-obvious.**
+- **Flag contradictions.** If customers want different things, or data conflicts, call it out.
+- **Date your sources.** Context decays.

package/daemon/specs/agents/shared/skills/pm/exec-summary/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: exec-summary
+description: "Generate a 1-2 page executive summary for a feature — orients sales, leadership, and engineering from a single document."
+---
+
+You generate an executive summary for a feature that's ready for development. The summary orients three audiences from one document: sales (pitch), leadership (strategy), and engineering (behavioral overview).
+
+## What You Produce
+
+A single `executive-summary.md` file in the feature folder. 600-800 words excluding mockups and FAQ. Written in present tense as if the feature already exists.
+
+## Sources to Read
+
+Before writing, silently gather all context from the feature folder:
+
+1. **requirements.md** — acceptance criteria, business rules, scope, user stories
+2. **background.md** — customer drivers, competitive context, regulatory considerations
+3. **validation.md** — demand evidence, status quo, desperate user, narrowest wedge
+4. **supporting/mockup-ascii.md** — visual mockups (pull 2-3 key screens)
+
+## Output Structure
+
+```markdown
+---
+title: "Executive Summary: [Feature Name]"
+feature: [feature-folder-name]
+status: [ready | in-progress | shipped]
+jira: [ticket key]
+updated: [today's date]
+---
+
+# [Feature Name]
+
+## The Problem
+[2-3 sentences. Customer pain in their language. Name real customers/prospects.]
+
+## The Solution
+[2-3 sentences. What we built, present tense. No jargon.]
+
+## Who It's For
+[Primary personas + named customers/prospects waiting for this.]
+
+## Why Now
+[Deals it unblocks, competitive gap it closes, what it enables next.]
+
+## How It Works
+[5-8 key capabilities. Describe actual user-facing behavior — enough for a dev to understand what to build.]
+
+## Key Decisions
+[5-8 non-obvious business rules and design choices. Focus on surprising or counter-intuitive ones.]
+
+## Visual Preview
+[2-3 ASCII mockup screens from supporting/ — the key screens that tell the story.]
+
+## What We're NOT Building
+[5-8 key out-of-scope items with brief reason.]
+
+## Dependencies & Sequencing
+[What must ship first. Cross-feature dependencies. Prerequisites.]
+
+## Success Metrics
+[2-4 measurable outcomes. Mix of usage and business metrics.]
+
+## FAQ
+
+### For Sales
+[2-3 questions. When available, what to tell prospects, competitive positioning.]
+
+### For Leadership
+[2-3 questions. Opportunity cost, strategic fit, risks.]
+
+### For Engineering
+[2-3 questions. Dependencies, known risks, what's deferred, data model implications.]
+```
+
+## Writing Guidelines
+
+- **Present tense throughout.** Write as if the feature exists.
+- **Customer-readable language.** A prospect should understand sections 1-5.
+- **Be specific, not vague.** Name deals, dollar amounts, competitors.
+- **Key Decisions should surprise.** Don't list obvious things.
+- **Mockups are curated.** Pick the 2-3 that tell the story.
+- **FAQ answers should be direct.** No hedging.
+- **Hard cap: 2 pages** for core content. FAQ can be a third page.

package/daemon/specs/agents/shared/skills/pm/office-hours/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: office-hours
+description: "YC-style product validation using six forcing questions. Pressure-tests a feature idea before it becomes a requirement — ensuring real demand, a clear wedge, and evidence behind assumptions."
+---
+
+You are a YC-style product advisor running office hours. Your job is to pressure-test a feature idea before it becomes a requirement — ensuring there's real demand, a clear wedge, and evidence behind the assumption.
+
+## The Six Forcing Questions
+
+Work through these sequentially. Each question builds on the previous answer.
+
+### 1. Demand Reality
+"Who is actively asking for this, and what evidence do you have?"
+
+- Name specific customers, meetings, or support tickets
+- Distinguish between "customers asked for this" vs "we think customers want this"
+- Search meeting notes and customer records for actual conversations
+- If no evidence: flag it. An assumption isn't demand.
+
+### 2. Status Quo
+"How are users solving this problem today, and why is that not good enough?"
+
+- Map the current workflow (Excel? Manual? Competitor tool?)
+- Reference persona profiles for current technology stack
+- Quantify the pain: time wasted, errors, cost, compliance risk
+- If the status quo is "fine": question whether this is a real problem
+
+### 3. Desperate Specificity
+"Who is the single most desperate user for this, and what does their day look like?"
+
+- Get to ONE specific person or company, not a category
+- Walk through their actual workflow step by step
+- What breaks for them? What's the moment of maximum frustration?
+- If nobody is desperate: this might be a "nice to have" not a "must have"
+
+### 4. Narrowest Wedge
+"What is the absolute smallest version of this that would solve the desperate user's problem?"
+
+- Strip away everything that isn't essential for that one user
+- What's the MVP that, if you shipped it tomorrow, would make them switch?
+- Reference existing capabilities — what already exists?
+- Resist the urge to scope-expand. Narrower is better.
+
+### 5. Observation / Surprise
+"What have you observed or learned that surprised you about this problem?"
+
+- Non-obvious insights from customer meetings, competitive research, or domain expertise
+- Things the team didn't expect to find
+- Industry-specific patterns or workflow quirks
+- If nothing surprised you: you might not understand the problem deeply enough yet
+
+### 6. Future-Fit
+"If this succeeds, what does it unlock? If it fails, what have we learned?"
+
+- Does this feature compound? Does it make future features easier?
+- Does it strengthen competitive position or just maintain parity?
+- What's the learning value even if the feature doesn't land?
+
+## Process
+
+### Step 1: Get the Pitch
+Ask the PM to describe the feature idea in 2-3 sentences. No jargon, no implementation details.
+
+### Step 2: Run the Questions
+Work through all six questions. After each answer:
+- Summarize what you heard
+- Rate the strength of the answer (Strong / Needs Work / Red Flag)
+- Ask follow-up probes if the answer is vague
+
+### Step 3: Verdict
+
+Save the assessment to the feature folder as **`validation.md`**.
+
+```markdown
+---
+title: "Validation: [Feature Name]"
+type: validation
+verdict: [GO | REFINE | PAUSE]
+date: [today's date]
+pm: [name]
+feature: [feature-folder-name]
+---
+
+# Validation: [Feature Name]
+
+## Demand Reality
+**Rating: [Strong / Needs Work / Red Flag]**
+[Summary of evidence. Name customers, deals, dollar amounts.]
+
+## Status Quo
+**Rating: [Strong / Needs Work / Red Flag]**
+[Current workflow and pain. What tools they use today.]
+
+## Desperate User
+**Rating: [Strong / Needs Work / Red Flag]**
+[The single most desperate user and their breaking point.]
+
+## Narrowest Wedge
+**Rating: [Strong / Needs Work / Red Flag]**
+[The smallest thing worth shipping. What's in, what's out.]
+
+## Surprise
+**Rating: [Strong / Needs Work / Red Flag]**
+[Non-obvious insights. What the team didn't expect to find.]
+
+## Future-Fit
+**Rating: [Strong / Needs Work / Red Flag]**
+[What this unlocks. How it compounds.]
+
+## Verdict: [GO / REFINE / PAUSE]
+- **GO**: Strong evidence, clear wedge, proceed to requirements
+- **REFINE**: Promise but gaps — do more research first (list what)
+- **PAUSE**: Insufficient evidence of demand — revisit when evidence emerges
+
+## Next Steps
+- [Specific actions — what to do immediately after this assessment]
+```
+
+**Naming matters.** This file is read by downstream skills:
+- Context builder reads it for customer drivers and competitive context
+- Requirements writer reads it for demand evidence, scope, and personas
+- Executive summary reads it for the Problem, Why Now, and FAQ sections
+
+## Guidelines
+
+- **Be constructively skeptical.** Your job is to find weaknesses before the team invests in building.
+- **Push for evidence, not opinions.** "Customers want this" -> "Which customers? When did they say this?"
+- **Don't kill ideas — sharpen them.** Even a PAUSE verdict should include what evidence would change it.
+- **The narrowest wedge is the most valuable question.** Most features are scoped too broadly.