wize-dev-kit 0.1.4 → 0.2.0

package/src/app-overlay/stack-catalog.md

@@ -0,0 +1,178 @@
+---
+catalog: app-stack
+owner: wize-agent-architect   # Tony (with Fury on strategy)
+applies_when: app-overlay active
+status: ready
+---
+
+# App Stack Catalog — Tony's Reference
+
+The mobile stack decision is harder to reverse than the web one. Pick deliberately. This catalog lists each option with the **trade-off honest enough that you don't relitigate it in six months**.
+
+## 1. Decision dimensions
+
+Order them: **distribution → team → performance → reuse**.
+
+1. **Distribution** — App Store + Play Store only? B2B enterprise (TestFlight/internal)? Sideload?
+2. **Team** — primary skill set: web, native (Swift/Kotlin), Flutter (Dart)?
+3. **Performance** — animation-heavy / camera / AR / ML on-device? Or list + form?
+4. **Code reuse** — does a web app share business logic? How much?
+5. **Hiring tail** — what skill set will be easy to hire from in 2 years?
+
+## 2. Frameworks
+
+### React Native + Expo (managed workflow)
+
+| | |
+|---|---|
+| **Pick when** | Team is JS/TS-strong; cross-platform with one codebase + fast iteration. |
+| **Strengths** | EAS Build/Update/Submit; OTA updates; same team can ship the web product. |
+| **Costs** | Native modules sometimes need ejecting; SDK lag for very-new OS features. |
+| **Perf ceiling** | 60 fps for typical UIs; deep native work requires bridging or custom modules. |
+| **Best for** | Most cross-platform B2C apps with shared web team. |
+
+### React Native (bare / community CLI)
+
+| | |
+|---|---|
+| **Pick when** | Need native modules Expo doesn't ship + full control over Xcode/Gradle. |
+| **Strengths** | Maximum flexibility, integrate any SDK. |
+| **Costs** | Maintain native build configs; lose EAS conveniences (unless self-hosted). |
+| **Best for** | Apps with heavy custom native (BLE, advanced camera, ML, payments SDKs). |
+
+### Flutter
+
+| | |
+|---|---|
+| **Pick when** | Pixel-perfect cross-platform UI with custom motion; team is Dart-OK. |
+| **Strengths** | Skia rendering = identical UI across platforms; great motion; mature widgets. |
+| **Costs** | Dart hiring pool smaller; web/desktop story uneven; non-trivial native interop. |
+| **Perf ceiling** | High — Skia bypasses platform UI thread for many cases. |
+| **Best for** | Animation-heavy or brand-precise apps; shop already on Flutter. |
+
+### SwiftUI (native iOS)
+
+| | |
+|---|---|
+| **Pick when** | iOS-only or iOS-primary; want platform-best UX and access to newest APIs day-one. |
+| **Strengths** | Best feel, best APIs (Live Activities, WidgetKit, Vision, etc.). |
+| **Costs** | Min iOS support shifts upward; doesn't help Android at all. |
+| **Best for** | Premium iOS-led products; products with deep Apple-ecosystem integrations. |
+
+### Jetpack Compose (native Android)
+
+| | |
+|---|---|
+| **Pick when** | Android-only or Android-primary; want first-party Material 3 + platform integrations. |
+| **Strengths** | Declarative + modern; Compose Multiplatform offers iOS path now. |
+| **Costs** | Doesn't help iOS unless you commit to CMP. |
+| **Best for** | Android-led products. |
+
+### Compose Multiplatform (KMP + Compose)
+
+| | |
+|---|---|
+| **Pick when** | Kotlin team, want shared business logic + shared UI. |
+| **Strengths** | Code reuse high; same Kotlin stack on backend possible. |
+| **Costs** | Newer; iOS UI parity caveats; ecosystem younger than RN/Flutter. |
+| **Best for** | Kotlin-fluent teams comfortable with bleeding edge. |
+
+### Capacitor / Ionic (hybrid)
+
+| | |
+|---|---|
+| **Pick when** | Mostly-web app needs a thin native wrapper for store distribution. |
+| **Strengths** | Reuse the existing web codebase 1:1; fastest path to store. |
+| **Costs** | Performance ceiling lower than RN/Flutter; UI feel rarely passes "native". |
+| **Best for** | Internal tools, content apps, MVPs where store presence > performance. |
+
+### Native + KMP shared logic
+
+| | |
+|---|---|
+| **Pick when** | Want native UIs (SwiftUI + Compose) + shared business logic in Kotlin. |
+| **Strengths** | Best-of-both: native UX + shared domain. |
+| **Costs** | Two UIs to maintain; KMP infra to manage. |
+| **Best for** | Mature teams with enough size to maintain both fronts. |
+
+## 3. Build & release
+
+| Choice | Pick when |
+|---|---|
+| **Expo EAS** (Build, Submit, Update) | RN+Expo project, want a turn-key pipeline. |
+| **Fastlane** | Native or RN bare, want scriptable lanes; established tool. |
+| **Bitrise** | Cloud CI specialized for mobile, integrates with EAS/Fastlane. |
+| **GitHub Actions + matrices** | Already on GitHub, custom needs, fewer mobile-specific shortcuts. |
+| **App Center (sunset path)** | Legacy; migrate off. |
+
+## 4. Auth
+
+| Choice | Pick when |
+|---|---|
+| **Firebase Auth** | RN/Flutter; want SDK on every platform, simple onboarding. |
+| **Auth0 / Clerk / WorkOS** | Enterprise SSO needs. |
+| **Sign in with Apple / Google / Microsoft** | Required (Apple) when other social auth is offered; minimal friction. |
+| **Custom OAuth via Supabase / your backend** | Want full control; team has experience. |
+
+## 5. Data / sync
+
+| Choice | Pick when |
+|---|---|
+| **WatermelonDB** (RN) | Offline-first apps with large local datasets. |
+| **Realm / Atlas Sync** | Need bi-di sync to MongoDB. |
+| **PowerSync / Replicache / Triplit** | Modern offline + sync over Postgres / custom. |
+| **TanStack Query + AsyncStorage / EncryptedStorage** | Most apps — fetch + cache. |
+| **GraphQL + Apollo** | Single API for many clients (web + mobile share schema). |
+
+## 6. State management
+
+| Choice | Pick when |
+|---|---|
+| **Zustand / Jotai** | Small global state; RN |
+| **TanStack Query** | Server-derived data dominates. |
+| **MobX-State-Tree** | Bigger app, opinionated structure. |
+| **Recoil** | (Niche; less active recently — verify.) |
+| **Provider / Riverpod** | Flutter. |
+
+## 7. Storage
+
+- **AsyncStorage** (RN) — small KV only; not for sensitive data.
+- **EncryptedStorage** / **react-native-keychain** — tokens, secrets.
+- **MMKV** — fast KV; sub-ms reads; replaces AsyncStorage for perf-critical paths.
+- **SQLite (Op-SQLite / better-sqlite)** — relational on device.
+- **Realm** — object DB with sync.
+
+## 8. Push notifications
+
+| Choice | Pick when |
+|---|---|
+| **Expo Push** | RN/Expo; simplest path. |
+| **OneSignal** | Cross-platform, segmentation features. |
+| **Firebase Cloud Messaging (FCM) + APNs** | Custom backend; full control. |
+| **Customer.io / Iterable** | Marketing-driven (campaigns, journeys). |
+
+## 9. Analytics + observability
+
+| Choice | Pick when |
+|---|---|
+| **Amplitude / Mixpanel / PostHog** | Product analytics. |
+| **Sentry / Bugsnag** | Crash + performance. |
+| **Firebase Performance / Crashlytics** | Free, broad coverage. |
+| **DataDog Mobile RUM** | Already on DataDog. |
+
+## 10. Anti-patterns Tony flags fast
+
+- **React Native for an animation-heavy / camera-heavy app** without scoping native modules upfront.
+- **Flutter for an iOS-primary product** when the team has no Dart history.
+- **Capacitor for a product needing 60 fps gestures** — pick RN/native.
+- **One framework for two products** that don't share the audience or team.
+- **Side-loading internal apps with no signing strategy.**
+
+## 11. Recording the choice
+
+Tony documents the chosen stack into:
+
+- `.wize/planning/tech-vision.md` (Fury): platforms covered, non-negotiables.
+- `.wize/solutioning/architecture.md` (Tony): runtime, build, release pipeline, native modules required.
+- `.wize/solutioning/adrs/ADR-002-mobile-stack.md`: trade-off log.
+- `.wize/planning/app/device-matrix.md`: targets that justified the perf choice.

package/src/method-skills/1-analysis/wize-document-project/workflow.md

@@ -2,35 +2,162 @@
 code: wize-document-project
 name: Document Project (brownfield baseline)
 phase: 1-analysis
-owner: wize-agent-analyst   # Pepper Potts (paired with Peggy Carter)
-status: stub
+owner: wize-agent-analyst   # Pepper Potts (paired with Peggy Carter and Tony Stark)
+status: ready
 ---
 
 # Document Project — Brownfield Baseline
 
-**Goal.** When the kit is installed in an existing codebase, baseline the current state so subsequent planning isn't blind. Produces an "as-is" snapshot that Tony reads before drawing the "to-be."
+**Goal.** When the kit is installed in an existing repo, baseline the **as-is** state so the rest of the lifecycle isn't blind. Produces a structured snapshot Tony can read before designing the *to-be*, and a knowledge base Wizer can answer questions from.
+
+Pepper drives discovery. Peggy edits prose. Tony validates architecture interpretation. Output lands in `.wize/knowledge/document-project/`.
 
 ## When to run
-- Installer detected `package.json` / `pubspec.yaml` / `Cargo.toml` / `go.mod` + non-trivial `src/` history.
-- User explicitly requests `/wize-document-project`.
+
+- The installer detected brownfield signals (`package.json`, `src/`, history) and offered to run this. ✓
+- The team is onboarding to a codebase nobody fully owns. ✓
+- A previous re-platforming decision left the docs stale. ✓
+
+Skip:
+- Greenfield (nothing to document yet).
+- Repos < 200 LOC.
 
 ## Inputs
-- The target repo (root)
-- `git log --oneline -50`
-- Existing READMEs / ARCHITECTURE / docs
+
+- The target repo (root).
+- `git log --since="1 year ago" --oneline | wc -l` to scope.
+- Any prior README / ARCHITECTURE / docs that exist.
 
 ## Outputs
-- `.wize/knowledge/document-project/overview.md`
-- `.wize/knowledge/document-project/architecture-snapshot.md`
-- `.wize/knowledge/document-project/conventions.md`
-- `.wize/knowledge/document-project/open-questions.md`
+
+- `.wize/knowledge/document-project/overview.md` — what the project is, who uses it, how big it is.
+- `.wize/knowledge/document-project/architecture-snapshot.md` — current components, integrations, data flow.
+- `.wize/knowledge/document-project/conventions.md` — coding/test/folder conventions actually used.
+- `.wize/knowledge/document-project/dependencies.md` — runtime deps + dev deps + their roles.
+- `.wize/knowledge/document-project/risk-spots.md` — areas of concentrated complexity, undocumented behavior, or known fragility.
+- `.wize/knowledge/document-project/open-questions.md` — things the code doesn't answer; route to humans.
 
 ## Steps
-1. **Inventory.** List packages, top-level modules, infra files, entry points.
-2. **Architecture snapshot.** Components and integrations as currently exist. Diagrams welcome.
-3. **Conventions.** Coding/test/folder conventions surfaced from a sample of files.
-4. **Open questions.** Things the code doesn't answer; route to humans.
-5. **Hand off.** Pepper to Wizer: "baseline ready." Then Wizer decides next agent.
-
-## Pairing
-Peggy Carter edits prose for clarity and structure. Tony Stark may be looped in to confirm architecture interpretation.
+
+### 1. Inventory (Pepper, mechanical)
+
+A first pass that requires no judgment, just listing.
+
+```
+ls -la                                  # top-level layout
+cat package.json | jq '.dependencies, .devDependencies, .scripts'
+git log --since="3 months ago" --oneline | wc -l
+git log --pretty=format:"%an" | sort | uniq -c | sort -rn | head
+find . -name "*.test.*" -o -name "*.spec.*" | wc -l
+find . -type f -name "*.md" | head
+```
+
+Write what you found in `overview.md` (no opinions yet).
+
+### 2. Architecture snapshot (Pepper + Tony)
+
+Walk the repo top-down. Identify:
+- **Entry points** (CLI, server, worker, build).
+- **Components** (where the boundaries are — by folder, by package, by feature).
+- **Integrations** (databases, queues, external APIs, third-party SDKs).
+- **Data flow** for at least one end-to-end critical path (e.g., a typical user request).
+
+Draw or describe. Diagrams in ASCII or Mermaid are fine — the point is shared mental model.
+
+Tony validates. If the snapshot misnames a pattern, fix it.
+
+### 3. Conventions (Peggy)
+
+Sample 5–10 files across the repo. Note:
+- Naming (camelCase / snake_case / kebab-case).
+- Folder structure (feature-first / layer-first).
+- Test placement (co-located / `__tests__` / `test/`).
+- Comment style (JSDoc / TSDoc / inline).
+- Import ordering (alphabetical / by source).
+- Logging / error handling patterns.
+- Linter / formatter config (eslint, prettier, etc.).
+
+Write the convention found, not the convention you'd prefer.
+
+### 4. Dependencies (Pepper)
+
+For each runtime dep, write one line:
+- Name, version, what it does in this repo, whether it's load-bearing.
+
+Flag:
+- Deps without a clear role.
+- Deps with known CVEs (run `npm audit --omit=dev` and capture).
+- Multiple deps doing the same job (`lodash` + `ramda`, both date libs, etc.).
+- Deps not maintained in > 2 years (link to last release).
+
+### 5. Risk spots (Pepper + Tony)
+
+For each, name the area + the symptom + the likely cause + how confident you are:
+
+| Area | Symptom | Likely cause | Confidence |
+|---|---|---|---|
+| `src/legacy/billing/` | 2k-line file with no tests | rushed migration in 2024 | high |
+| Webhooks handler | Silent retries | no idempotency layer | medium |
+| Auth middleware | Custom JWT parsing | predates the library that handles it | high |
+
+This is *not* a refactor backlog. It's a map. Tony decides what to fix; this just makes the choices visible.
+
+### 6. Open questions (everyone)
+
+Things the code does NOT answer:
+- Why was this choice made?
+- What's the SLA?
+- Who's the owner of feature X?
+- Are there secret configs we're missing?
+
+Each question gets an owner (a human Pepper will ask). Route back via Wizer.
+
+### 7. Hand-off
+
+- Mark all docs `status: baseline`.
+- Tell Wizer: *"Baseline complete. Tony can read it before architecture work; Hill can read it before scoping."*
+
+## Conventions doc — template
+
+```markdown
+---
+status: baseline
+owner: Pepper Potts + Peggy Carter
+created: YYYY-MM-DD
+sampled: 8 files across src/, tests/, scripts/
+---
+
+# Conventions (observed, not prescribed)
+
+## Naming
+- Files: kebab-case (e.g., `user-profile.ts`).
+- Classes: PascalCase.
+- Functions: camelCase, verb-led.
+- Constants: UPPER_SNAKE_CASE.
+
+## Folder structure
+Feature-first: `src/features/<feature>/{index.ts, api.ts, ui.tsx, *.spec.ts}`.
+Shared utilities in `src/shared/`.
+
+## Tests
+Co-located with the file under test. `.spec.ts` for unit; `.e2e.ts` for end-to-end (separate runner).
+
+## Lint/format
+`eslint.config.mjs` with `airbnb-base` + custom rules in `eslint.local.cjs`. Prettier with 2-space indent.
+
+## Observed deviations
+- `src/legacy/billing/` doesn't follow feature-first; it predates the convention.
+- Some files use `_test.ts` suffix instead of `.spec.ts` — older code.
+```
+
+## Anti-patterns Pepper rejects
+
+- "TODO: document later." The baseline IS the documentation pass; later doesn't come.
+- Romanticizing the code ("clean, modular"). Describe what you see; let Tony judge.
+- Architecture diagrams that show what the team *wishes* exists. Diagram the real state.
+- Risk-spot table with no confidence label. Without confidence, readers can't act.
+- Open questions with no owner. They never get answered.
+
+## Hand-off
+
+> Baseline is in `.wize/knowledge/document-project/`. Three risk spots flagged. Five open questions routed to the humans named per question. Tony can read this before drawing `architecture.md`; Hill can scope the PRD knowing what's already there.

package/src/method-skills/1-analysis/wize-prfaq/workflow.md

@@ -3,25 +3,164 @@ code: wize-prfaq
 name: PR/FAQ
 phase: 1-analysis
 owner: wize-agent-analyst   # Pepper Potts
-status: stub
+status: ready
 ---
 
-# PR/FAQ
+# PR/FAQ — Working Backwards
 
-**Goal.** Force alignment by drafting the "future press release + FAQ" before building. Amazon-style.
+**Goal.** Force alignment by writing the *future* press release and a tight FAQ **before** anyone builds anything. Amazon-style. If you can't write a compelling PR, you don't have a product yet.
+
+Pepper drives. Peggy polishes prose. Output lands in `.wize/planning/prfaq.md`.
+
+## When to run
+
+Run this:
+- New product or new strategic feature.
+- The team disagrees on the user-visible value.
+- You're about to commit > 1 month of engineering.
+
+Skip this:
+- Bug fix, copy edit, dependency bump → use `wize-quick-dev`.
+- The brief already crisply names the user-visible value and the team is aligned → write the PRD directly.
 
 ## Inputs
+
 - `.wize/planning/brief.md`
+- `.wize/planning/research.md` (optional)
 
 ## Outputs
+
 - `.wize/planning/prfaq.md`
 
+## Structure (the Amazon shape)
+
+A PR/FAQ has two parts: the **PR** (≤ 1 page) and the **FAQ** (≤ 2 pages).
+
+### The PR (write this first)
+
+| Section | Length | What goes in it |
+|---|---|---|
+| **Headline** | 1 line | Audience + benefit + product name. Reader-understandable. |
+| **Sub-headline** | 1 line | The non-obvious part of the benefit. |
+| **Summary paragraph** | 3–5 sentences | What it is, who it's for, what changes, where to get it. |
+| **Problem paragraph** | 3–5 sentences | Why this matters *now*, evidence the pain is real. |
+| **Solution paragraph** | 3–5 sentences | How the product solves the problem. Concrete, not abstract. |
+| **Internal quote** | 1 quote | A leader (founder/CEO) saying why this matters strategically. |
+| **How it works** | 3 sentences | Three lines max. Not implementation — the *user* mental model. |
+| **Customer quote** | 1 quote | An imagined real user saying the thing they'd say. Specific. |
+| **How to get started** | 2 lines | One sentence: where + how. One sentence: what's first. |
+
+If you find yourself writing more, cut. The discipline is the point.
+
+### The FAQ
+
+5–10 questions a sharp reader would actually ask. Crisp answers.
+
+**Mandatory questions** (always include):
+
+1. Who exactly is this for?
+2. What does this replace today?
+3. Why now? (Why not last year, why not next year?)
+4. How is this different from {{nearest competitor}}?
+5. What's *out* of scope at launch?
+6. What does success look like in 6 months? In 18 months?
+7. What are the top three risks?
+
+**Optional questions** (include when relevant):
+
+8. What's the pricing model?
+9. How does this work for non-English locales / accessibility / offline?
+10. What does the regulatory story look like?
+11. What's the launch sequence (geos / segments / preview)?
+
 ## Steps
-1. **Headline + subhead.** One sentence each. Reader must understand.
-2. **Quote (customer).** Why does this matter to a real user?
-3. **Quote (internal leader).** Why does this matter to the business?
-4. **How it works.** Three paragraphs max.
-5. **FAQ.** 5–10 most likely sharp questions, with crisp answers.
-
-## When to skip
-Skip this workflow for small fixes or features whose audience is obvious. Use for net-new products or strategic bets.
+
+### 1. Frame and freeze the audience
+
+Write the audience line at the top of your draft and don't move it. Every sentence is judged against "does this matter to the audience?"
+
+### 2. PR before FAQ
+
+Always. The discipline of writing the PR exposes vague thinking. The FAQ comes after, when you're forced to defend it.
+
+### 3. Show, don't market
+
+No "world-class," "revolutionary," "AI-powered" without a noun next to it. If you can replace the adjective with another and lose nothing, delete it.
+
+### 4. Numbers, not adjectives
+
+Every claim has a unit. "Reduces onboarding from 35 minutes to 7" beats "reduces onboarding significantly."
+
+### 5. Pre-mortem question
+
+Before sending, write the answer to: *"It's six months after launch and it failed. Why?"*. If the FAQ doesn't already cover the failure mode, add the question.
+
+### 6. Adversarial review
+
+Run `wize-review-adversarial` on the draft. Cut what survives only "trust me."
+
+### 7. Hand off
+
+The PR/FAQ is **not** the PRD. It's a strategic alignment doc. Marker `status: aligned`. Hill writes the PRD from this + the brief.
+
+## Output template
+
+```markdown
+---
+status: draft | aligned
+owner: Pepper Potts
+created: YYYY-MM-DD
+---
+
+# PR/FAQ — {{project_name}}
+
+## Press Release
+
+**Headline:** {{audience}} can now {{benefit}} with {{product_name}}.
+**Sub-headline:** {{the non-obvious twist}}.
+
+{{summary paragraph}}
+
+{{problem paragraph}}
+
+{{solution paragraph}}
+
+> "{{quote}}" — {{internal leader title}}
+
+How it works: {{three sentences}}
+
+> "{{customer quote}}" — {{persona}}
+
+Get started: {{where + first step}}
+
+## FAQ
+
+**Q1. Who exactly is this for?**
+…
+
+**Q2. What does this replace today?**
+…
+
+**Q3. Why now?**
+…
+
+(…through Q10 as needed)
+
+## Pre-mortem
+It's six months after launch and it failed. Why?
+1. …
+2. …
+3. …
+```
+
+## Anti-patterns Pepper rejects
+
+- PR longer than one page. Cut.
+- A press release with no user. ("Wize Foo unlocks synergies.") — say *who*.
+- A FAQ that dodges the hard question. The reader will ask it; better in your draft than in a launch review.
+- Pricing left vague when it's the load-bearing question.
+- Customer quote that sounds like marketing copy. Rewrite as a person speaking.
+
+## Hand-off
+
+> PR/FAQ is in `.wize/planning/prfaq.md`. Aligned with leadership. Hill, the PRD scope should anchor on FAQ Q5 (in/out). Mantis, the customer quote is your North Star for UX.

package/src/method-skills/1-analysis/wize-product-brief/workflow.md

@@ -4,57 +4,128 @@ name: Product Brief
 phase: 1-analysis
 owner: wize-agent-analyst   # Pepper Potts
 absorbs: "WDS Saga — Phase 1"
-status: stub
+status: ready
 ---
 
 # Product Brief
 
-**Goal.** Turn raw demand into a concise, decision-ready brief that the rest of the team can ship from.
+**Goal.** Convert raw demand into a one-page brief the team can ship from. The brief is the single source of truth at this point — every other artifact (PRD, UX, architecture) references back to it.
+
+Pepper drives. Peggy edits prose. Output lands in `.wize/planning/brief.md`.
 
 ## Inputs
 
-- Raw demand (chat or file)
-- Optional existing materials (deck, doc, ticket, recording)
-- `.wize/config/project.toml`
+- Raw demand (chat message, doc, ticket, screenshot, recording).
+- Optional existing materials (deck, doc, prior brief).
+- `.wize/config/project.toml`.
 
 ## Outputs
 
 - `.wize/planning/brief.md`
+- Optionally `.wize/knowledge/research/` if Pepper pulled external sources.
 
 ## Steps
 
-1. **Frame.** One paragraph: what is being asked, by whom, by when.
-2. **Audience.** Primary user (1), secondary users (≤2), stakeholders (≤3).
-3. **Vision.** One sentence describing the desired future state.
-4. **Success criteria.** 3–5 measurable outcomes (numbers, not adjectives).
-5. **Non-goals.** What this is *not*. Cut ambiguity early.
-6. **Constraints.** Deadlines, budgets, compliance, integrations.
-7. **Open questions.** Ranked, each with the person who can answer.
-8. **Hand off.** Mark `status: ready-for-prd`; ping Wizer to call Maria Hill.
+### 1. Frame in one paragraph
+
+What is being asked, by whom, and by when. If you can't write it in three sentences, you don't understand it yet. Ask one clarifying question, then write.
+
+### 2. Audience
+
+- **Primary user** (one, name them by role + JTBD).
+- **Secondary users** (≤ 2).
+- **Stakeholders** (≤ 3 — the people whose lives change if this ships).
+
+If the user list overflows, the brief is too broad. Force the cut.
+
+### 3. Vision
+
+One sentence describing the desired future state. Future tense. Concrete. No buzzwords. Test: can a new dev one month from now repeat it after a 30-second read?
+
+### 4. Success criteria
+
+3–5 measurable outcomes. Numbers, not adjectives.
+
+Examples:
+- ✓ "Median TTI on the checkout page ≤ 1.5s on a mid-range Android by Q3."
+- ✗ "Faster checkout."
+
+### 5. Non-goals
+
+What this is *not*. Cut ambiguity early. If a feature isn't ruled in or out here, it will be in the PRD review.
+
+### 6. Constraints
+
+Hard limits. Pick from:
+- Deadline (and what slipping it means).
+- Budget envelope (one-time and run-rate).
+- Compliance (GDPR, LGPD, SOC2, PCI, HIPAA, etc.).
+- Integrations the product must speak to.
+- Team / hiring envelope.
+
+### 7. Open questions
 
-## Brief template (target file)
+Each with the human who can answer it. Each marked priority `blocker` / `important` / `nice-to-know`. Blockers must be resolved before the PRD starts.
+
+### 8. Hand-off
+
+- Mark `status: ready-for-prd` in the brief.
+- Notify Wizer: "Brief ready, hand to Hill."
+- Move to `wize-trigger-map` next (Pepper continues).
+
+## Brief template
 
 ```markdown
+---
+status: ready-for-prd | draft
+owner: Pepper Potts
+created: YYYY-MM-DD
+---
+
 # Brief — {{project_name}}
 
 ## Vision
 …
 
 ## Audience
-- Primary: …
-- Secondary: …
-- Stakeholders: …
+- **Primary:** … (one role + their JTBD)
+- **Secondary:** …
+- **Stakeholders:** …
 
 ## Success criteria
 1. …
 2. …
+3. …
 
 ## Non-goals
 - …
 
 ## Constraints
-- …
+- **Deadline:** …
+- **Budget:** …
+- **Compliance:** …
+- **Integrations:** …
 
 ## Open questions
-- [ ] … (owner: …)
+- [ ] **(blocker)** … — *owner: NAME*
+- [ ] **(important)** … — *owner: NAME*
+- [ ] **(nice-to-know)** … — *owner: NAME*
 ```
+
+## Anti-patterns Pepper rejects
+
+- "Make the product better." → no audience, no outcome, not a brief.
+- Pasting a stakeholder's slack message verbatim. Rewrite in the brief voice.
+- Success criteria like "increase engagement". Reword: which event, how much, by when.
+- Hidden assumptions ("everyone has fast internet"). Surface them in *Constraints* or *Open questions*.
+- Open questions with no owner. If nobody owns it, the answer never comes.
+
+## When to skip
+
+This workflow is **not optional** for new products / new features. For tiny fixes (typo, copy, dependency bump), use `wize-quick-dev` instead — Pepper isn't called.
+
+## Hand-off
+
+When the brief is approved, Pepper notifies Wizer:
+
+> Brief is ready in `.wize/planning/brief.md`. No blockers open. Hill, your call on PRD.