wize-dev-kit 0.1.5 → 0.2.5

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.

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

@@ -0,0 +1,127 @@
+---
+code: wize-refresh-knowledge
+name: Refresh Project Knowledge
+phase: 1-analysis
+owner: wize-agent-analyst    # Pepper (drives), with Peggy on prose
+status: ready
+---
+
+# Refresh Project Knowledge
+
+**Goal.** Consolidate the dated bullets added to `document-project/*.md` over the sprint (via `wize-dev-story` step 8 and `wize-quick-dev` step 5) into a coherent, narrated, current-state baseline. Keep what's still true; demote what's outdated; archive what's no longer relevant.
+
+This is the workflow that **keeps `document-project` honest over months**, instead of letting it stale within a sprint.
+
+Pepper drives the consolidation. Peggy edits prose. Tony reviews architecture-snapshot changes. Hawkeye reviews risk-spots changes.
+
+## When to run
+
+- **End of sprint** (default cadence). `wize-help next` suggests it when it detects the sprint ended.
+- **After a major epic ships.** Architecture often shifts visibly; this is the moment to consolidate.
+- **Before onboarding a new engineer.** The baseline is the first thing they read; keep it fresh.
+- **Before an audit / external review.** Same.
+
+Don't run after every story — that's why each story already does its own inline update. This is the *periodic narration pass*.
+
+## Inputs
+
+- `.wize/knowledge/document-project/{overview,architecture-snapshot,conventions,dependencies,risk-spots,open-questions}.md`
+- `.wize/implementation/tea/**/gate.md` from this sprint (look for `KN-NN` findings — they flag where the baseline got out of sync).
+- Git log of the sprint window (`git log --since="<sprint-start>" --until="<sprint-end>"`).
+- `.wize/implementation/sprint-status.md` (latest sprint block).
+
+## Outputs
+
+- Updated `.wize/knowledge/document-project/*.md` (in place).
+- `.wize/knowledge/document-project/_history/{YYYY-Qn}/{sprint-N}.md` — sprint-scoped snapshot (frozen).
+- Optional new entries appended to `open-questions.md`.
+
+## Steps
+
+### 1. Collect the inline notes
+
+For each of the 5 axes, list every dated bullet added since the previous refresh (or since the baseline was created). They look like:
+
+```
+## 2026-06-12 — E01-S03
+- Conventions: `data-testid="invite-*"` published as public contract.
+- Risk: R-1 (mailer) mitigation confirmed.
+```
+
+Pepper extracts them by axis.
+
+### 2. Narrate, don't list
+
+For each axis, write a short paragraph that **integrates** the new bullets into the surrounding context. The bullets disappear; the prose grows. Each axis remains a single coherent file — not a chronological log.
+
+Example for `conventions.md` before refresh:
+
+```markdown
+## Tests
+Co-located with the file under test. `.spec.ts` for unit; `.e2e.ts` for end-to-end.
+```
+
+After refresh integrating an inline note "data-testid='invite-*' is a public contract":
+
+```markdown
+## Tests
+Co-located with the file under test. `.spec.ts` for unit; `.e2e.ts` for end-to-end. Test IDs follow the `data-testid="{feature}-{element}"` convention and are treated as a **public contract** — renaming one is a breaking change for end-to-end tests; ping Hawkeye before changing.
+```
+
+### 3. Demote what's outdated
+
+If a previous claim no longer holds (a service was retired, a convention was replaced), don't delete silently. Move it to a "Deprecated" section at the bottom of the file with the date it was replaced and the new pattern. Future readers need the breadcrumb.
+
+### 4. Archive a sprint snapshot
+
+Freeze the *current* state into `_history/{YYYY-Qn}/sprint-{N}.md`. This file is read-only after creation. Six months from now, when someone asks "when did we change the test-id convention?", the answer is in `_history/`.
+
+### 5. Open questions sweep
+
+Pull any `KN-NN` findings that weren't resolved (the gap was acknowledged but the doc still wasn't updated) and copy them as `open-questions.md` entries with owners.
+
+### 6. Diff narrative
+
+Append a one-paragraph summary to the bottom of each updated file:
+
+```markdown
+## Last refresh: 2026-06-25 (Sprint 7)
+- Architecture: 2 new components documented (`<InviteForm>`, `<TeamList>`); ADR-008 anchored in the auth section.
+- Conventions: test-id public contract documented; eslint plugin added (commit 7a3d2f).
+- Risk-spots: R-1 (mailer) closed; R-7 (rate limiter) added.
+- Dependencies: bumped zod, drizzle, expo (notes in dependencies.md).
+- Overview: unchanged; no new top-level feature in this sprint.
+```
+
+### 7. Hand off
+
+- All updated docs flip frontmatter `last_refreshed: YYYY-MM-DD`.
+- Wizer announces in `sprint-status.md`: *"Knowledge refresh done; baseline current."*
+- Maria Hill carries this into the retrospective: was the refresh smooth, or did the team accumulate too many KN findings?
+
+## Frontmatter convention for `document-project/*.md`
+
+Each baseline file ships with:
+
+```yaml
+---
+status: baseline
+owner: Pepper + Peggy
+created: 2026-04-02
+last_refreshed: 2026-06-25
+sampled: "wkly + sprint refresh"
+---
+```
+
+`last_refreshed` tells the next reader how much to trust the file vs read the more recent inline notes from `_history/`.
+
+## Anti-patterns Pepper rejects
+
+- **Refreshing into a chronological log.** That defeats narration; if a new dev opens `conventions.md` and sees 47 dated bullets, they can't form a mental model. Narrate.
+- **Refresh without reading the gate findings.** `KN-NN` findings are exactly the gaps you should be patching here; ignoring them recreates the original problem.
+- **Refresh every sprint regardless of activity.** If the sprint touched zero axes (rare but possible — a sprint of pure UI polish), say so in the diff narrative and skip the bulk of the work.
+- **Demotion without breadcrumb.** Future readers need the trail.
+
+## Hand-off
+
+> Knowledge refresh for Sprint 7 done. Baseline current; 1 historical snapshot frozen at `_history/2026-Q2/sprint-7.md`. KN-01 closed, KN-03 still open (deferred to S8 — assigned to Aaliyah).

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

@@ -3,22 +3,114 @@ code: wize-research
 name: Research
 phase: 1-analysis
 owner: wize-agent-analyst   # Pepper Potts
-status: stub
+status: ready
 ---
 
 # Research
 
-**Goal.** Synthesize external evidence (market, competitors, analytics, interviews) that informs the brief.
+**Goal.** Surface evidence that hardens the brief and trigger map. Frame the questions Pepper actually needs answered, do focused passes (market / competitors / analytics / interviews), and write the synthesis in a way Maria Hill can quote in the PRD.
+
+Pepper drives. Peggy edits prose. Output lands in `.wize/planning/research.md` with raw materials in `.wize/knowledge/research/`.
 
 ## Inputs
-- Research questions from the brief
-- External access (browser, MCPs) and/or attached docs
+
+- Open questions in `.wize/planning/brief.md`.
+- Hypotheses in `.wize/planning/ux/trigger-map.md`.
+- External access (browser, MCPs) and/or attached materials (decks, transcripts).
 
 ## Outputs
-- `.wize/planning/research.md`
+
+- `.wize/planning/research.md` — short synthesis (≤ 2 pages) referencing sources.
+- `.wize/knowledge/research/{slug}.md` — one file per major source (raw notes, links, attached PDFs).
 
 ## Steps
-1. List the questions to answer.
-2. For each question: gather sources, summarize, cite.
-3. Mark gaps explicitly as `open` so Wizer can re-route.
-4. Hand off back to brief workflow.
+
+### 1. Frame the questions
+
+Convert open questions + hypotheses into a numbered list. Each question is:
+- **Specific** — "What's the median onboarding time for the top 5 competitors?" not "How is onboarding usually done?".
+- **Answerable in a finite pass** — if it takes weeks, decompose.
+- **Tagged with category** — `market / competitive / analytics / interview / desk-research / regulatory`.
+
+### 2. Choose the framework that fits each question
+
+| Category | Recommended frame | Tools |
+|---|---|---|
+| Market sizing | TAM/SAM/SOM, top-down + bottom-up reconciled | Statista, public filings, gov registries |
+| Competitive | Porter's 5 + feature matrix + pricing scan | competitor sites, G2/Capterra, Pricing/Plans pages |
+| User research | Jobs-to-be-Done (Christensen / Klement) | 5–8 interviews (semi-structured, 30min) |
+| Behavioral | 5W2H + analytics funnel | product analytics (Amplitude/PostHog), session replays |
+| Compliance/legal | Reg list + clause map | gov sites, legal counsel review |
+| Macro context | PESTLE (political/economic/social/technological/legal/environmental) | desk research |
+
+### 3. Run focused passes
+
+One question, one pass. Don't bundle. For each:
+
+- Define what "enough evidence" looks like before starting.
+- Cite or it didn't happen. Links + access date.
+- When numbers conflict across sources, write down both and flag.
+
+### 4. Synthesize
+
+In `research.md`, for each original question, write:
+
+```markdown
+### Q1. {{the question}}
+**Finding:** one sentence answer.
+**Confidence:** high | medium | low
+**Why we believe it:** 2–3 lines + citations [1][2][3].
+**Implication for the brief/PRD:** what changes (or doesn't) because of this.
+```
+
+Don't include raw quotes here — link to `.wize/knowledge/research/{slug}.md`.
+
+### 5. Flag the gaps
+
+End the synthesis with a "Still open" section. List questions we couldn't answer + the cheapest next step (one interview / one analytics query / one expert call). Route back to Wizer with the gap.
+
+## Output template (synthesis)
+
+```markdown
+---
+status: ready-for-prd
+owner: Pepper Potts
+created: YYYY-MM-DD
+---
+
+# Research — {{project_name}}
+
+## Q1. {{question}}
+**Finding:** …
+**Confidence:** medium
+**Why:** … [1]
+**Implication:** Brief constraint #3 holds; PRD scope can drop feature X.
+
+## Q2. …
+
+## Still open
+- Q5: pricing elasticity in segment S — needs 1 hour with sales lead.
+
+## Sources
+[1] {{title}} — {{url}} (accessed YYYY-MM-DD)
+[2] interview-acme-cto-2026-05-30 — see knowledge/research/acme-cto.md
+```
+
+## When to use which framework (heuristic)
+
+- **JTBD** when you're about to write personas; JTBD is sharper than archetypes.
+- **Porter** when picking a market to enter or a defensible moat.
+- **PESTLE** for projects with regulatory or geopolitical exposure.
+- **5 Whys + analytics funnel** when a metric is bad and the cause isn't obvious.
+
+## Anti-patterns Pepper rejects
+
+- Synthesis without citations.
+- "We surveyed users" with no n, no method, no script.
+- Single-source claims with high confidence ("everyone is using X" because of one blog post).
+- Using brand-name competitor research as user research — they're different.
+- Continuing to research when the decision is already made. Stop and ship.
+
+## Hand-off
+
+> Research is in `.wize/planning/research.md`. Q3 still open — sales lead has a slot tomorrow. Hill can start the PRD on what's confirmed.

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

@@ -4,17 +4,21 @@ name: Trigger Map
 phase: 1-analysis
 owner: wize-agent-analyst   # Pepper Potts
 absorbs: "WDS Saga — Phase 2 (Trigger Mapping)"
-status: stub
+status: ready
 ---
 
 # Trigger Map
 
-**Goal.** Map user psychology to business goals. For each user action we want to drive, identify the **trigger** (need/anxiety/desire) and the **business outcome** it unlocks.
+**Goal.** Map user psychology to business goals. For each user action the product wants to drive, name the **trigger** (the need/anxiety/desire that precedes it), the **friction** that blocks it today, the **business outcome** unlocked, and the **signal** that confirms it happened.
+
+This is the bridge between Pepper's brief and Maria Hill's PRD: it forces the team to argue *why* users would do the thing before *what* the team will build.
+
+Pepper drives. Output lands in `.wize/planning/ux/trigger-map.md`.
 
 ## Inputs
 
-- `.wize/planning/brief.md`
-- `.wize/planning/research.md` (if exists)
+- `.wize/planning/brief.md` (vision + audience + success criteria).
+- `.wize/planning/research.md` (when present — strengthens triggers with evidence).
 
 ## Outputs
 
@@ -22,19 +26,79 @@ status: stub
 
 ## Steps
 
-1. **List target user actions.** From the brief, list the 3–8 actions we want users to take.
-2. **For each action**, fill the row:
-   - **Trigger** — what state of mind/need precedes this action?
-   - **Friction** — what stops users from doing it today?
-   - **Business outcome** — what changes for the business when this action happens?
-   - **Signal** — what telemetry/event proves it happened?
-3. **Validate.** Cite research or mark `hypothesis`.
-4. **Hand off to Mantis** for UX Scenarios.
+### 1. List target user actions
+
+From the brief, list **3–8 actions** users must take for the product to succeed. Verb-led. Concrete.
+
+- ✓ "Sign up using a work email."
+- ✓ "Add a teammate."
+- ✓ "Confirm the first invoice."
+- ✗ "Get value." (too abstract)
+
+If you have more than 8, you're conflating products. Trim.
+
+### 2. Per row: trigger / friction / business outcome / signal
+
+For each action, fill four cells. Each cell ≤ 1 sentence.
+
+| Field | What goes here |
+|---|---|
+| **Trigger** | The mental state preceding the action. *Need / anxiety / desire.* What makes the user think "I need to do this now"? |
+| **Friction** | The cost of doing it today (in the current workaround or competitor). What stops them? |
+| **Business outcome** | What changes for the business when this action happens. Revenue, retention, cost, NPS, risk reduction. |
+| **Signal** | The telemetry event/state-change proving it happened. Name it like an event (`signup_succeeded`), not a phrase ("user signs up"). |
+
+### 3. Mark each row evidence-backed or hypothesis
+
+Every cell must be tagged:
+
+- `evidence:<source>` — when based on an interview, survey, analytics or a citable doc.
+- `hypothesis` — when we believe it but haven't proven it.
+
+Hypotheses are fine. Hidden hypotheses are not. Force the label.
+
+### 4. Wire to success criteria
+
+For each of Pepper's success criteria in the brief, identify **which row of the map is the load-bearing one**. If a criterion has no row mapped to it, either it's not a real success criterion or the map is missing an action.
 
-## Trigger Map template
+### 5. Hand off
+
+Mark `status: ready-for-prd`. Tell Wizer the next step is Maria Hill.
+
+## Output template
 
 ```markdown
-| Action | Trigger | Friction | Business outcome | Signal | Evidence |
-|---|---|---|---|---|---|
-| … | … | … | … | … | research:/hypothesis |
+---
+status: ready-for-prd | draft
+owner: Pepper Potts
+created: YYYY-MM-DD
+---
+
+# Trigger Map — {{project_name}}
+
+## Actions
+
+| # | Action | Trigger | Friction | Business outcome | Signal | Evidence |
+|---|---|---|---|---|---|---|
+| 1 | Sign up with work email | "We need a tool we can hand to the team next week." | Existing tool requires manual SSO; we want self-serve. | New paid-team conversion. | `signup_completed` | research:user-interview-2026-04 |
+| 2 | Invite first teammate | Won't move forward solo. | Email + reminder loops cost manager 10min. | Activation. | `teammate_invited` | hypothesis |
+| … | … | … | … | … | … | … |
+
+## Coverage of brief success criteria
+
+- **Criterion 1** ("TTI ≤ 1.5s on Android by Q3") → covered by row 4 (`page_loaded`).
+- **Criterion 2** ("…") → covered by row 1.
+- …
 ```
+
+## Anti-patterns Pepper rejects
+
+- **Triggers written as features.** "Wants the dashboard." Wrong layer. Reword to the emotion/need: "Wants to know if the team is okay."
+- **Friction in vague language.** "It's confusing." Wrong. Name the step that breaks: "After invite, no email arrives for 4 hours."
+- **Business outcomes with no metric.** "Drives engagement." Wrong. "Reduces churn by ≥ 1pp in cohort C." If you can't measure it, it's not an outcome — it's a hope.
+- **Signals that fire on intent, not completion.** `signup_button_clicked` is intent. `signup_completed` is the signal.
+- **Same row repeated for two actions.** Each row must justify a distinct action. If you can collapse them, do it.
+
+## Hand-off
+
+> Trigger map is in `.wize/planning/ux/trigger-map.md`. Hill, the PRD goals should anchor on rows 1, 3, and 5 — they map to the success criteria in the brief.