wize-dev-kit 0.15.0 → 0.16.0

package/src/builder-skills/wize-create-skill/workflow.md

@@ -1,7 +1,5 @@
 ---
-
 code: wize-create-skill
-description: "Use quando precisar criar uma nova skill single-step sob .wize/custom/skills/."
 name: Create Skill
 owner: builder
 status: stub

package/src/builder-skills/wize-create-workflow/workflow.md

@@ -1,7 +1,5 @@
 ---
-
 code: wize-create-workflow
-description: "Use quando precisar criar um novo workflow multi-step sob .wize/custom/workflows/."
 name: Create Workflow
 owner: builder
 status: stub

package/src/core-skills/module.yaml

@@ -16,6 +16,9 @@ skills:
   - code: wize-grill
     name: "Grill"
     description: "Exhaustive one-question-at-a-time interview to reach shared understanding before drafting briefs, PRDs, epics, stories, or plans."
+  - code: wize-eli5
+    name: "ELI5"
+    description: "Explain anything to anyone — adapts vocabulary, analogies, tone, depth and framing to the audience (age, role, relationship)."
   - code: wize-brainstorming
     name: "Brainstorming"
     description: "Divergent-then-convergent ideation; produces idea-pool.md."

package/src/core-skills/wize-advanced-elicitation/skill.md

@@ -1,7 +1,5 @@
 ---
-
 code: wize-advanced-elicitation
-description: "Use quando uma resposta do usuário parecer subespecificada e precisar de técnicas de elicitação (5 Whys, laddering, premortem) para aprofundar o entendimento."
 name: Advanced Elicitation
 module: core
 status: stub

package/src/core-skills/wize-brainstorming/skill.md

@@ -1,7 +1,5 @@
 ---
-
 code: wize-brainstorming
-description: "Use quando precisar gerar ideias divergentes e convergir para as melhores opções em qualquer fase de decisão."
 name: Brainstorming
 module: core
 status: stub

package/src/core-skills/wize-eli5/skill.md

@@ -0,0 +1,72 @@
+---
+code: wize-eli5
+description: "Use quando alguém pedir para explicar um conceito, trecho de código, erro ou decisão para um público específico — adapta vocabulário, analogias, tom, profundidade e framing ao ouvinte."
+name: ELI5
+module: core
+status: ready
+---
+
+# ELI5 — Explain Like I Am 5
+
+**Goal.** Explain anything to anyone — a concept, a piece of code, an error, an architecture decision, a business rule — calibrated to the listener. The same idea gets a different explanation for a 5-year-old, a manager, an engineer, or a client. ELI5 is a communication tool, not an artifact of its own: it produces the explanation in the conversation (or as a short doc when asked).
+
+Inspired by [ELI5](https://github.com/dreambigou/eli5) by Andrew Ou — adapted to the Wize method: audience detection first, explicit calibration, and a comprehension check before handing off.
+
+## Step 1 — Detect the audience
+
+Read the prompt for an explicit or implicit audience. If none is given, ask **one** question with a recommendation (rule 2 of `wize-grill`): "I'll explain it for a non-technical stakeholder — or would you prefer the engineering version?"
+
+| Category | Examples |
+|---|---|
+| **Ages** | 5, 10, 15, 20, 30, 40+ |
+| **Grade levels** | 5th grade, middle school, high school, college, graduate |
+| **Job roles** | Manager, engineer, designer, director, product manager, client, stakeholder |
+| **Relationships** | Wife, husband, parents, kids, friend, investor |
+
+## Step 2 — Calibrate on five axes
+
+| Axis | Non-technical / child | Technical / peer |
+|---|---|---|
+| **Vocabulary** | No jargon; everyday words; define any term you must use | Proper terminology, precise names |
+| **Analogies** | Toys, playground, kitchen, games | Systems, patterns, prior art, math |
+| **Tone** | Playful, warm, patient | Direct, professional, dense |
+| **Depth** | Short and sweet; one idea at a time | Nuanced; trade-offs; edge cases |
+| **Framing** | What it does for *them*, in their world | Impact/risk, architecture, constraints |
+
+Role-specific framing:
+- **Manager / director** → business outcome, cost, risk, timeline. No implementation detail unless asked.
+- **Designer** → user experience, flow, visual impact.
+- **Engineer** → mechanism, contracts, failure modes.
+- **Client / stakeholder** → what changes for them, what they must decide, what it costs.
+- **Child / layperson** → one concrete analogy, one sentence per idea, check understanding.
+
+## Step 3 — Explain
+
+1. **One idea per beat.** Short sentences. If the explanation needs more than ~5 beats, structure it (numbered steps or a tiny table).
+2. **Lead with the analogy for non-technical audiences** — then, only if asked, bridge to the real mechanism ("it's like a library card catalog… and the actual index is a B-tree").
+3. **For code**: show the *behavior* first (what it does), then the *why* (why it exists), then the *how* (mechanism) — in that order, stopping at the depth the audience needs.
+4. **For errors**: plain-language what happened → why it happened → what we do about it. Never dump a stack trace at a non-technical audience.
+5. **For decisions**: the decision → the reason → the alternative considered → the cost of being wrong.
+
+## Step 4 — Verify comprehension
+
+Close with a lightweight check, matched to the audience:
+
+- **Child / layperson**: "Does that make sense? Want me to say it with a different example?"
+- **Manager / client**: one-line summary + the single decision or action they own.
+- **Engineer**: offer the next level: "Want the implementation details / the failure modes / the alternatives?"
+
+If the listener asks a follow-up, re-calibrate — the audience may have shifted (a manager asking "how does that work technically?" is now an engineer).
+
+## Anti-patterns
+
+- Explaining to a 5-year-old with the same depth as a code review.
+- Dumping jargon at a non-technical audience ("it's a distributed consensus algorithm").
+- Over-simplifying for an engineer (no hand-waving at peers).
+- Skipping the audience check when the prompt is ambiguous.
+- Explaining *everything* — answer the question asked, then stop.
+- Using the same analogy for every audience (a playground analogy lands for a child, not for a CFO).
+
+## Hand-off
+
+> Explained {topic} for {audience} — calibrated on vocabulary, analogies, tone, depth and framing. Comprehension check: {result}. {One-line summary or next action for the listener.}

package/src/core-skills/wize-review-adversarial/skill.md

@@ -1,11 +1,8 @@
 ---
-
 code: wize-review-adversarial
-description: "Use quando um artefato (story, arquitetura, PRD) precisar de revisão adversarial — testar a ideia sob quatro personas hostis."
 name: Adversarial Review
 module: core
 status: stub
-subtask: true
 ---
 
 # Adversarial Review

package/src/core-skills/wize-shard-doc/skill.md

@@ -1,7 +1,5 @@
 ---
-
 code: wize-shard-doc
-description: "Use quando um documento markdown grande (PRD, arquitetura) precisar ser dividido em shards endereçáveis por ID."
 name: Shard Doc
 module: core
 status: stub

package/src/method-skills/1-analysis/wize-agent-analyst/agent.yaml

@@ -23,9 +23,6 @@ absorbs:
 skills:
   - wize-product-brief
   - wize-research
-  - wize-market-research
-  - wize-domain-research
-  - wize-technical-research
   - wize-trigger-map
   - wize-prfaq
   - wize-document-project

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

@@ -1,229 +1,36 @@
 ---
-
 code: wize-document-project
-description: "Use quando o kit for instalado em um repositório existente (brownfield) e precisar documentar o estado atual do projeto."
 name: Document Project (brownfield baseline)
 phase: 1-analysis
-owner: wize-agent-analyst   # Pepper Potts (paired with Peggy Carter and Tony Stark)
-status: ready
+owner: wize-agent-analyst   # Pepper Potts (paired with Peggy Carter)
+status: stub
 ---
 
 # Document Project — Brownfield Baseline
 
-**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/`.
+**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."
 
 ## When to run
-
-- 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.
+- Installer detected `package.json` / `pubspec.yaml` / `Cargo.toml` / `go.mod` + non-trivial `src/` history.
+- User explicitly requests `/wize-document-project`.
 
 ## Inputs
-
-- The target repo (root).
-- `git log --since="1 year ago" --oneline | wc -l` to scope.
-- Any prior README / ARCHITECTURE / docs that exist.
-
-## CLI usage
-
-```bash
-wize-dev-kit document-project                # quick baseline (default)
-wize-dev-kit document-project quick          # same as default
-wize-dev-kit document-project initial_scan   # pattern-only initial scan
-wize-dev-kit document-project initial_scan deep       # reads critical directories
-wize-dev-kit document-project initial_scan exhaustive  # reads all source files in batches
-wize-dev-kit document-project full_rescan    # archives old state, re-runs initial_scan
-wize-dev-kit document-project deep_dive --target src/tools/installer
-```
-
-## Modes
-
-| Mode | What it does | Scan levels |
-|---|---|---|
-| `quick` | Writes the 6 baseline files. Does not read source files. | `quick` only |
-| `initial_scan` | Classifies project type, writes index + overview + source tree + conditional docs. | `quick`, `deep`, `exhaustive` |
-| `full_rescan` | Archives `project-scan-report.json` and re-runs `initial_scan`. | `quick`, `deep`, `exhaustive` |
-| `deep_dive` | Exhaustive analysis of a specific folder/file/feature. | `exhaustive` |
+- The target repo (root)
+- `git log --oneline -50`
+- Existing READMEs / ARCHITECTURE / docs
 
 ## Outputs
-
-- `.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.
-- `.wize/knowledge/document-project/index.md` — master navigation with `_(To be generated)_` markers for missing conditional docs.
-- `.wize/knowledge/document-project/project-scan-report.json` — resume state.
+- `.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`
 
 ## Steps
-
-### 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.
-```
-
-## Update mode (how the baseline stays alive)
-
-The first run of this workflow produces the **baseline**. Two complementary mechanisms keep it current after:
-
-### 1. Inline updates per story (the daily cadence)
-
-Every `wize-dev-story` ends with a Knowledge Update step (step 8). If the story touched any of the 5 axes (architecture, conventions, risk-spots, dependencies, overview), Shuri appends 1–3 dated bullets to the matching `document-project/*.md` file **in the same PR**. Hawkeye verifies in `tea-review`; a touched-but-not-updated story gets a `KN-NN` finding at gate.
-
-`wize-quick-dev` has a lighter version: only when a dep bump or a public rename actually shifts the baseline.
-
-This produces dated bullets like:
-
-```markdown
-## 2026-06-12 — E01-S03
-- Conventions: `data-testid="invite-*"` published as public contract.
-- Risk: R-1 (mailer) mitigation confirmed.
-```
-
-### 2. Sprint-end refresh (the narrative cadence)
-
-`wize-refresh-knowledge` runs at sprint end (triggered by `wize-help next` when it detects the sprint emptied). Pepper + Peggy consolidate the inline bullets into the narrative prose of each axis file, demote stale claims to a "Deprecated" section, freeze a sprint snapshot in `_history/{YYYY-Qn}/sprint-{N}.md`, and stamp `last_refreshed` in each file.
-
-Result: the baseline reads like a single coherent document, not a chronological log. New devs can read it linearly and form a mental model. Forensics readers (six months later, asking "when did X change?") consult `_history/`.
-
-### File frontmatter convention
-
-Each `document-project/*.md` file ships with:
-
-```yaml
----
-status: baseline
-owner: Pepper Potts + Peggy Carter
-created: 2026-04-02
-last_refreshed: 2026-06-25
-sampled: "wkly + sprint refresh"
----
-```
-
-`last_refreshed` tells the reader how much to trust the file vs the inline bullets accumulating since.
-
-## 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.
-- Treating the baseline as one-shot. The mode + refresh exist precisely because point-in-time docs lie within weeks.
-
-## 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.
+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.

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

@@ -1,168 +1,27 @@
 ---
-
 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: ready
+status: stub
 ---
 
-# 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
+# PR/FAQ
 
-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.
+**Goal.** Force alignment by drafting the "future press release + FAQ" before building. Amazon-style.
 
 ## 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. 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.
+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.