wize-dev-kit 0.16.0 → 0.17.0

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

@@ -0,0 +1,66 @@
+---
+code: wize-market-research
+name: Market Research
+phase: 1-analysis
+owner: wize-agent-analyst   # Pepper Potts
+status: ready
+description: "Use quando precisar pesquisar mercado, concorrentes, tendências ou posicionamento."
+---
+
+> **Variante de pesquisa.** Para outros tipos de pesquisa, veja:
+> - Mercado/concorrência → `/wize-market-research`
+> - Domínio/indústria → `/wize-domain-research`
+> - Técnica/stack → `/wize-technical-research`
+> - Pesquisa geral (dispatcher) → `/wize-research`
+
+# Market Research
+
+**Goal.** Conduct market research on competition and customers to inform the product brief and PRD.
+
+Pepper Potts drives. Peggy Carter edits prose. Output lands in `.wize/planning/research/market-{slug}-research-{date}.md`.
+
+## When to use
+
+- "I need market research on..."
+- "Who are the competitors?"
+- "What do customers actually want?"
+
+## Inputs
+
+- Open questions from `.wize/planning/brief.md`
+- User-provided topic or problem area
+- Web search access
+
+## Outputs
+
+- `.wize/planning/research/market-{slug}-research-{date}.md`
+
+## Workflow architecture
+
+This skill uses **step-file architecture**:
+
+- Six steps, each self-contained.
+- Sequential progression with user control.
+- Document state tracked in frontmatter (`stepsCompleted`).
+
+## On activation
+
+1. Load `.wize/config/project.toml` and `.wize/config/user.toml`.
+2. Resolve language settings and output paths.
+3. Greet the user in `communication_language`.
+4. Ask for the market research topic if not provided.
+5. Derive `{research_topic_slug}` and create the output file from `research.template.md`.
+6. Read fully and follow `./steps/step-01-init.md`.
+
+## Steps
+
+1. `step-01-init.md` — confirm scope.
+2. `step-02-customer-behavior.md` — analyze customer behavior.
+3. `step-03-customer-pain-points.md` — identify pain points.
+4. `step-04-customer-decisions.md` — map purchase/journey decisions.
+5. `step-05-competitive-analysis.md` — analyze competitors.
+6. `step-06-research-completion.md` — synthesize and complete.
+
+## Hand-off
+
+> Market research document is in `.wize/planning/research/`. Hill can quote the findings in the PRD; open questions route back to Wizer.

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

@@ -1,27 +1,168 @@
 ---
+
 code: wize-prfaq
+description: "Use quando precisar forçar alinhamento escrevendo o press release futuro e FAQ antes de construir — estilo Amazon Working Backwards."
 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 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
 
-**Goal.** Force alignment by drafting the "future press release + FAQ" before building. Amazon-style.
+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

@@ -1,60 +1,133 @@
 ---
+
 code: wize-product-brief
+description: "Use quando uma demanda bruta chegar e precisar ser convertida em um product brief de uma página."
 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. One open decision → ask one clarifying question, then write. More than one → offer a `wize-grill` pass (one question at a time, recommendation attached) and interview until shared understanding; answers land straight in the brief fields below, unresolved ones in *Open questions*.
+
+### 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.
 
-## Brief template (target file)
+### 7. Open questions
+
+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,129 @@
+---
+
+code: wize-refresh-knowledge
+description: "Use quando o document-project acumulou bullets datados durante o sprint e precisar ser consolidado em uma baseline atualizada."
+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 next` (or `/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,49 @@ code: wize-research
 name: Research
 phase: 1-analysis
 owner: wize-agent-analyst   # Pepper Potts
-status: stub
+status: ready
+description: "Use quando precisar pesquisar algo mas não souber qual tipo de pesquisa se aplica."
 ---
 
-# Research
+# Research (Dispatcher)
 
-**Goal.** Synthesize external evidence (market, competitors, analytics, interviews) that informs the brief.
+**Goal.** Classify the user's research question and delegate to the correct variant. This skill does NOT execute research directly — it routes to one of the specialized research skills.
 
-## Inputs
-- Research questions from the brief
-- External access (browser, MCPs) and/or attached docs
+## Classification guide
 
-## Outputs
-- `.wize/planning/research.md`
+Analyze the user's question for these signals. Score each category by keyword hits; delegate to the highest-scoring category.
+
+| Category | Keywords (pt-BR) | Keywords (EN) | Delegate to |
+|---|---|---|---|
+| **Market** | concorrência, concorrentes, mercado, competidor, pricing, preço, posicionamento, cliente, segmento, TAM, SAM, market share, G2, Capterra | competitor, market, pricing, positioning, customer, segment | `wize-market-research` |
+| **Domain** | domínio, indústria, setor, regulatório, regulação, compliance, legislação, lei, normativo, PESTLE, tendências do setor | domain, industry, sector, regulatory, compliance, legislation | `wize-domain-research` |
+| **Technical** | técnico, tecnologia, stack, biblioteca, framework, arquitetura, ferramenta, linguagem, banco de dados, API, protocolo, desempenho, escalabilidade | technical, technology, stack, library, framework, architecture, tool, language, database, API, protocol, performance, scalability | `wize-technical-research` |
 
 ## 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. Read the question
+
+Extract the user's research topic or question. If the user provided a long message, identify the core research intent.
+
+### 2. Classify
+
+Match keywords against the classification guide above. Score each category by keyword hits. Pick the highest-scoring category.
+
+### 3. Delegate or ask
+
+- **Clear match (one category dominates):** Delegate to the corresponding variant. Load that skill and hand off the user's question intact — do not rephrase or summarize.
+- **Ambiguous (multiple categories tie or no clear signal):** Ask one clarifying question:
+
+> Isso é pesquisa de mercado, domínio ou técnica?
+
+Wait for the user's answer, then delegate to the chosen variant.
+
+## Anti-patterns
+
+- Executing research directly instead of delegating.
+- Asking more than one clarifying question.
+- Guessing when the signal is ambiguous — ask, don't assume.
+
+## Hand-off
+
+> Pesquisa classificada como {{category}}. Delegando para {{variant}}.

package/src/method-skills/1-analysis/wize-technical-research/customize.toml

@@ -0,0 +1,14 @@
+# Wize Dev Kit — overrides for the built-in workflow "wize-technical-research".
+# DO NOT EDIT in the installed kit; copy to .wize/custom/workflows/wize-technical-research/
+# for project-level overrides.
+
+[workflow]
+
+activation_steps_prepend = []
+activation_steps_append = []
+
+persistent_facts = [
+  "file:{project-root}/.wize/planning/brief.md",
+]
+
+on_complete = ""

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

@@ -0,0 +1,31 @@
+---
+research_type: technical
+research_topic: "{{research_topic}}"
+research_goals: "{{research_goals}}"
+status: in-progress
+stepsCompleted: []
+owner: Pepper Potts
+created: "{{date}}"
+---
+
+# Technical Research — {{research_topic}}
+
+## Research Overview
+
+[Research overview and methodology will be appended here.]
+
+## Scope Confirmation
+
+## Technology Stack Analysis
+
+## Integration Patterns
+
+## Architectural Patterns
+
+## Implementation Research
+
+## Research Synthesis
+
+## Sources
+
+## Open Questions