wize-dev-kit 0.16.0 → 0.16.1

package/src/method-skills/4-implementation/wize-investigate/workflow.md

@@ -0,0 +1,123 @@
+---
+
+code: wize-investigate
+description: "Use quando um bug ou comportamento inesperado surgir e precisar de investigação estruturada com root cause analysis."
+name: Investigate
+phase: 4-implementation
+owner: wize-agent-dev   # Shuri (+ wize-agent-test-architect Hawkeye on call)
+status: ready
+---
+
+# Investigate
+
+**Goal.** Structured root-cause analysis for a failed test, regression, or unexpected behavior. Produces a written report so the team (and future-you) can retrace the steps.
+
+Shuri drives. Hawkeye on call for test-specific analysis. Wizer is on call for cross-cutting impact.
+
+## When to run
+
+- A test fails and the cause is not obvious from the diff.
+- A regression appears in production or CI.
+- A user reports a bug with unclear repro steps.
+- An incident triggers post-mortem.
+
+## When NOT to run
+
+- The cause is obvious from the diff → use `wize-quick-dev` to fix directly.
+- A new feature is needed (use `wize-create-story`).
+- A security finding is suspected (escalate immediately; do not investigate solo).
+
+## Inputs
+
+- The failing test, error log, or user report.
+- The commit range since the last known-good state.
+- The relevant story file (if any).
+- A free-form description of the symptoms.
+
+## Output
+
+- `.wize/implementation/investigations/{YYYY-MM-DD}-{short-slug}.md` — a written report.
+
+## Steps
+
+### 1. Frame
+
+One paragraph: what broke, when it was first noticed, who reported it, and how serious. If you cannot write this in 3 sentences, the report is too broad.
+
+### 2. Reproduce
+
+Step-by-step: how to reproduce locally. Include environment (OS, Node version, branch), commands, expected vs. actual output. If unreproducible, mark "not reproducible after N attempts" and stop.
+
+### 3. Hypothesize
+
+List 3 root causes, ranked by likelihood. For each:
+- What would explain the symptoms.
+- A 1-line test to confirm or refute.
+- Confidence: low / medium / high.
+
+### 4. Verify
+
+For each hypothesis, run the 1-line test. Record: confirmed / refuted / inconclusive. If all refuted, return to step 3 and re-rank.
+
+### 5. Conclude
+
+Pick the surviving root cause. State:
+- **Root cause:** {description}.
+- **Fix path:** {one paragraph: what to change and why}.
+- **Effort:** S / M / L.
+- **Risk of fix:** low / medium / high.
+- **Recommended next step:** open a quick-dev, open a story, or escalate.
+
+### 6. Hand off
+
+Notify the next workflow:
+- S / low risk → `/wize-quick-dev` (Shuri fixes directly).
+- M+ or higher risk → `/wize-create-story` (new story for the fix).
+- Escalation → `/wize-correct-course` (involve PM + Wizer).
+
+## Output template
+
+```markdown
+---
+date: 2026-06-16
+author: Shuri
+severity: high
+related_story: E04-S02
+related_test: test/document-project-classify.test.js
+status: concluded
+---
+
+# Investigation — {short-slug}
+
+## Frame
+{one paragraph}
+
+## Reproduce
+1. ...
+2. ...
+**Expected:** {x}
+**Actual:** {y}
+
+## Hypotheses
+1. **{hypothesis}** — Confidence: high. Test: {1-liner}. Result: confirmed.
+2. ...
+
+## Conclude
+- **Root cause:** {description}
+- **Fix path:** {one paragraph}
+- **Effort:** M
+- **Risk of fix:** low
+- **Next:** /wize-create-story (E04-S05)
+```
+
+## Anti-patterns Shuri rejects
+
+- Skipping the hypothesis ranking. (Ranking forces you to consider alternatives.)
+- Stopping at "I think it's X" without the verification test. (Confirmation bias.)
+- Mixing the investigation with the fix. (Investigate, then propose; do not edit code yet.)
+- One-paragraph reports. (If it's a real investigation, it's at least 5 sections.)
+- Sharing the report only in chat. (Always write to disk for archival.)
+
+## Hand-off
+
+> "Investigation concluded. Root cause: {summary}. Next: `/wize-create-story` (M+ fix) or `/wize-quick-dev` (S fix)."

package/src/method-skills/4-implementation/wize-quick-dev/workflow.md

@@ -1,33 +1,151 @@
 ---
+
 code: wize-quick-dev
+description: "Use quando a demanda for pequena e bem delimitada (bug fix, copy edit, refactor) e não justificar o ciclo completo."
 name: Quick Dev (lifecycle shortcut)
 phase: 4-implementation
 owner: wize-agent-dev   # Shuri
-status: stub
+status: ready
 ---
 
 # Quick Dev
 
-**Goal.** When the task is small and well-scoped (bug fix, copy edit, small refactor), skip the full lifecycle.
+**Goal.** When the task is small and well-scoped (bug fix, copy edit, small refactor, dep bump, brownfield maintenance), skip Phase 1–3 and execute with light TEA. Save the full lifecycle for new value.
+
+Wizer authorizes the shortcut (via routing). Shuri runs it. Hawkeye does smoke-only.
+
+## Operating contract (light)
+
+Still a **mission contract**, just a small one: `.wize/` + `AGENTS.md` + skills are the instructions. Inspect before editing, reuse ladder before new code, smallest sufficient change, test-first when the change has a testable surface, run the real smoke + checks, no success claim without evidence. If it grows past ~1h or touches a new feature/architecture/UX/security surface, stop and re-route to Full Lifecycle — don't force it through here.
+
+## When to use (yes)
+
+- Bug fix with a clear root cause.
+- Copy or content edit.
+- Small refactor with no behavior change.
+- Dependency bump (security or minor).
+- Brownfield maintenance: rename, structural cleanup, dead-code removal.
+- Hotfix during incident response (post-mortem after).
+
+## When NOT to use (no)
+
+- New feature, even small.
+- Cross-cutting change touching architecture.
+- Changes where ACs need to be agreed.
+- Anything that should be a story.
+- Anything that touches security/auth/payments without senior review.
+
+## Decision tree
+
+```
+Question                              Yes              No
+Is there an AC to write?              → full lifecycle  → next
+Does it touch architecture?           → full lifecycle  → next
+Does it need UX input?                → full lifecycle  → next
+Could it surprise a user?             → full lifecycle  → next
+Is it ≤ 1 hour to a careful dev?      → quick-dev       → full lifecycle
+```
+
+## Inputs
 
-## When to use
-- Bug fix with clear root cause
-- Copy or content edit
-- Small refactor with no behavior change
-- Dependency bump
-- Brownfield maintenance
+- Issue / Slack message / PR comment describing the problem.
+- Repo state.
+- `.wize/config/tea.toml` (smoke-only policy when `policy = "advisory"`).
 
-## When NOT to use
-- New feature
-- Cross-cutting change touching architecture
-- Anything where ACs need to be agreed
+## Output
+
+- Code change (single PR).
+- Single-line entry appended to `.wize/implementation/quick-dev-log.md`.
+- Conventional commit.
 
 ## Steps
-1. **Frame.** One paragraph: what changes and why.
-2. **Implement.** TDD or smoke-test-and-fix, depending on risk.
-3. **Hawkeye lite.** Smoke test + lint only (no design/trace/nfr/review).
-4. **Gate.** Tiny `gate.md` (PASS or CONCERNS) appended to a rolling `.wize/implementation/quick-dev-log.md`.
-5. **Commit.** Conventional commit referencing the change.
+
+### 1. Frame in one paragraph
+
+What changes, why, and what could break. If the paragraph is hard to write, you're not in quick-dev territory.
+
+### 2. Implement
+
+- TDD when reasonable; smoke-test-and-fix when the cost of TDD is greater than the value.
+- Run Shuri's reuse ladder (see `wize-agent-dev` persona) before writing anything new: does this need to exist → already in the codebase → stdlib → native/framework feature → installed dependency → one-liner → only then new code. Don't introduce new abstractions.
+
+### 3. Hawkeye lite
+
+- Smoke test: imports load, the changed flow doesn't break.
+- Lint + format + type-check clean.
+- No `tea-design / trace / review / nfr` written.
+- Single one-line gate entry instead of full `gate.md`.
+
+### 4. Log
+
+Append one line to `.wize/implementation/quick-dev-log.md`:
+
+```
+2026-06-11 | shuri | dep-bump zod 3.22→3.23 | smoke PASS | PR #418
+2026-06-11 | shuri | fix copy on /signin help link | smoke PASS | PR #419
+2026-06-11 | shuri | rename UserService → AccountService | smoke PASS | PR #420
+```
+
+### 5. Knowledge update (only if applicable)
+
+Most quick-dev changes don't touch the baseline axes (copy edit, small refactor, dep bump in a stable lib). When they do — typically a **dependency bump** or a **rename that breaks a public contract** — add **one line** to the matching `document-project/*.md` file:
+
+```markdown
+## 2026-06-11
+- Dependencies: bump zod 3.22 → 3.23. No API changes; validateInviteEmail unaffected.
+- Conventions: `AccountService` replaces `UserService` (rename); imports updated repo-wide.
+```
+
+Heuristic: *"would a new dev hitting `document-project/*.md` next week be misled if I don't add this?"* Yes → write. No → skip.
+
+### 6. Commit + open PR
+
+Conventional commit. PR description: the paragraph from step 1.
+
+```
+fix(auth): typo in error message for AC-04-2 follow-up
+
+The error shown after rate-limit said "Sloow down" — corrected to "Slow down".
+No behavior change; copy-only.
+```
+
+## Quick-dev log template
+
+```markdown
+# Quick-dev log
+
+| Date | Owner | What | Smoke | PR |
+|---|---|---|---|---|
+| 2026-06-11 | shuri | … | PASS | #N |
+```
+
+## Done report (compact)
+
+Report in four lines — no ceremony:
+
+1. What changed + why.
+2. Files changed.
+3. Checks run + results (smoke, lint, format, type-check). Name any that couldn't run and why.
+4. Recommended next action, if any.
 
 ## Disabling
-Set `quick_dev_enabled = false` in `.wize/config/project.toml` to force full lifecycle for everything.
+
+To force every change through the full lifecycle (for very high-stakes products), set in `.wize/config/project.toml`:
+
+```toml
+[install]
+quick_dev_enabled = false
+```
+
+Wizer respects this; quick-dev becomes unavailable; every change must go through Pepper → … → Hawkeye gate.
+
+## Anti-patterns Shuri rejects in herself
+
+- Reaching for quick-dev to skip writing an AC because she doesn't want to argue with Hill.
+- Quick-dev that touches security/auth/payments.
+- A "small refactor" that ends up changing behavior.
+- Skipping the log entry.
+
+## Hand-off
+
+> `dep-bump zod 3.23` is in. PR #418, smoke PASS. Logged. No further TEA artifacts; moving on.

package/src/method-skills/4-implementation/wize-release/workflow.md

@@ -0,0 +1,162 @@
+---
+code: wize-release
+description: "Use quando todas as stories do sprint estiverem gated e você precisar gerar release: bump de versão, changelog e tag git."
+name: Release
+phase: 4-implementation
+owner: wize-agent-dev   # Shuri + Maria Hill
+status: ready
+---
+
+# Release
+
+**Goal.** Bump de versão, changelog a partir das stories gated e tag git. O release é o passo entre "todas as stories passaram no gate" e a retrospectiva.
+
+Shuri executa. Maria Hill confirma o escopo (quais epics entram).
+
+## Pré-requisitos
+
+Antes de iniciar, verificar:
+
+1. **Sprint ativo** — `sprint-status.yaml` deve ter `development_status` com stories.
+2. **Todas as stories gated** — cada story no sprint ativo deve estar `done` no `sprint-status.yaml`. Stories com gate `FAIL` bloqueiam o release. Stories com `CONCERNS` precisam de waiver documentado.
+3. **Git limpo** — `git status --porcelain` deve estar vazio (ou conter apenas arquivos não rastreados que não fazem parte do release).
+4. **Branch main** — releases saem da `main`. Se estiver em feature branch, abortar e orientar merge via PR.
+
+Se qualquer pré-requisito falhar, reportar o bloqueio e parar. Não fazer release parcial.
+
+## Inputs
+
+- `.wize/implementation/sprint-status.yaml` — stories concluídas
+- `.wize/solutioning/stories/{epic}/*.md` — detalhes das stories
+- `package.json` — versão atual
+- `CHANGELOG.md` — changelog existente (se houver)
+- `git tag --list 'v*'` — tags existentes
+
+## Outputs
+
+- `package.json` com versão atualizada
+- `CHANGELOG.md` atualizado com a nova versão
+- Tag git `v{semver}`
+- `sprint-status.yaml` atualizado (sprint marcado como concluído)
+- Resumo do release no terminal
+
+## Steps
+
+### 1. Verificar pré-requisitos
+
+```bash
+git status --porcelain  # deve estar vazio
+git branch --show-current  # deve ser main
+```
+
+Ler `sprint-status.yaml` e validar que todas as stories do sprint ativo estão `done`. Se houver stories `backlog`, `ready-for-dev`, `in-progress` ou `review`, listar cada uma e abortar.
+
+### 2. Coletar stories concluídas
+
+Varrer `development_status` no `sprint-status.yaml`. Para cada story com status `done`:
+
+1. Localizar o arquivo da story em `.wize/solutioning/stories/{epic}/{story}.md`
+2. Extrair do frontmatter: `story_id`, `epic`, `status`
+3. Extrair do corpo: título (linha `# Story:`), acceptance criteria
+
+Agrupar por epic. Se o epic tiver `epic_id` no `sprint-status.yaml`, usar o nome do arquivo do epic em `.wize/solutioning/epics/` para obter o título legível.
+
+### 3. Determinar o bump de versão
+
+Ler a versão atual de `package.json`:
+
+```
+Versão atual: 0.11.0
+Qual o bump?
+  1. patch (0.11.1) — correções, hotfix, docs
+  2. minor (0.12.0) — novas features compatíveis
+  3. major (1.0.0) — breaking changes
+```
+
+Em modo interativo, perguntar ao usuário. Em modo não-interativo, usar o primeiro argumento (`patch`, `minor` ou `major`). Se nenhum argumento for passado, default `patch`.
+
+Calcular a nova versão com `semver.inc(current, bump)` — usar Node built-in (regex parse + increment, sem dependência externa).
+
+### 4. Gerar changelog
+
+Delegar a geração do changelog ao `wize-changelog`:
+
+1. Invocar o fluxo do `wize-changelog` com a nova versão e a lista de stories coletadas no passo 2.
+2. O changelog é gerado no formato Keep a Changelog e pré-pendido ao `CHANGELOG.md`.
+
+Se `CHANGELOG.md` não existir, criar com o cabeçalho padrão.
+
+### 5. Bump de versão
+
+Atualizar o campo `version` em `package.json` com a nova versão. Preservar a formatação existente (indentação, aspas duplas).
+
+### 6. Commit e tag
+
+```bash
+git add package.json CHANGELOG.md
+git commit -m "chore: release v{version}"
+git tag v{version} -m "Release v{version}"
+```
+
+A mensagem de commit deve listar os epics incluídos no release.
+
+### 7. Atualizar sprint-status.yaml
+
+Adicionar ao `sprint-status.yaml`:
+
+```yaml
+release:
+  version: "{version}"
+  date: "{YYYY-MM-DD}"
+  sprint: "{active_cycle}"
+  stories_released: {count}
+```
+
+Marcar o sprint como concluído e adicionar entrada de retrospectiva pendente.
+
+### 8. Resumo
+
+Emitir no terminal:
+
+```
+✓ Release v{version} criado
+
+Epics incluídos:
+  - {epic_name} ({story_count} stories)
+
+Changelog: CHANGELOG.md
+Tag: v{version}
+Commit: {commit_hash}
+
+Próximos passos:
+  - git push origin main --tags
+  - /wize-retrospective
+```
+
+**Não executar `git push` automaticamente.** O push é sempre manual — o desenvolvedor revisa antes de publicar.
+
+## Bump semver (built-in, zero-dep)
+
+```js
+function bumpVersion(current, type) {
+  const [major, minor, patch] = current.split('.').map(Number);
+  switch (type) {
+    case 'major': return `${major + 1}.0.0`;
+    case 'minor': return `${major}.${minor + 1}.0`;
+    case 'patch': return `${major}.${minor}.${patch + 1}`;
+    default: throw new Error(`Tipo de bump inválido: ${type}. Use patch, minor ou major.`);
+  }
+}
+```
+
+## Anti-patterns
+
+- Fazer release com stories não gated — o gate existe para proteger a main.
+- Fazer release de feature branch — releases saem da main.
+- Push automático — o desenvolvedor revisa antes de publicar.
+- Pular o changelog — "depois eu escrevo" = nunca escreve.
+- Bump manual de versão — usar o bump semver para evitar off-by-one.
+
+## Hand-off
+
+> Release v{version} criado. Changelog atualizado, tag aplicada. Execute `git push origin main --tags` quando revisar. Depois: `/wize-retrospective`.

package/src/method-skills/4-implementation/wize-retrospective/workflow.md

@@ -1,36 +1,140 @@
 ---
+
 code: wize-retrospective
+description: "Use quando o sprint terminar e precisar de retrospectiva facilitada com todo o time."
 name: Retrospective
 phase: 4-implementation
 owner: wize-orchestrator   # Wizer facilitates; whole team contributes
-status: stub
+status: ready
 ---
 
 # Retrospective
 
-**Goal.** Capture what worked, what didn't, and what we change next sprint.
+**Goal.** Capture what worked, what didn't, what surprised, and **one concrete change for next sprint**. A retro that ends in a vibe is a retro that didn't ship a change.
+
+Wizer facilitates. Hill enforces output discipline. Everyone (including Pepper, Mantis, Fury) contributes.
+
+## When to run
+
+- End of every sprint (cadence).
+- After any incident (separate; pulls from incident timeline).
+- At major milestones (epic close, release, year-end).
 
 ## Inputs
+
 - `.wize/implementation/sprint-status.md` (current sprint)
 - All `gate.md` files from current sprint
+- `tea/nfr/{epic}.md` if an epic closed this sprint
+- Quick-dev log
+
+## Output
 
-## Outputs
 - `.wize/implementation/retrospective/{YYYY-MM-DD}.md`
 
-## Template
+## Format (60 minutes, fixed)
+
+| Minutes | Section |
+|---|---|
+| 0–5 | Frame: Wizer reads the sprint stats (capacity, shipped, slipped, gates). |
+| 5–15 | **Worked** — what we want to repeat. |
+| 15–25 | **Didn't work** — what we want to change. |
+| 25–35 | **Surprised us** — externalities, signals, anything not on plan. |
+| 35–45 | Pick **1–3 changes**. Vote with effort/impact dots. |
+| 45–55 | Each change gets an owner + deadline. |
+| 55–60 | Wizer reads back the doc; everyone confirms; close. |
+
+Going over 60 minutes is a sign the retro became therapy. Time-box.
+
+## Steps
+
+### 1. Open with stats
+
+Wizer reads the sprint dashboard from `sprint-status.md`:
+- Stories committed vs shipped (a count, not a velocity metric — we don't estimate).
+- Number of gates: PASS / CONCERNS / FAIL / WAIVED.
+- Blockers and their resolution times.
+- Carry-over count.
+
+Stats anchor the retro in observations, not feelings.
+
+### 2. Worked / didn't / surprised
+
+Each engineer brings 2–3 items per section, written in advance ideally. Time-box discussion: any item that takes > 3 min becomes a follow-up.
+
+### 3. Changes (1–3 max)
+
+A change is:
+- **Specific:** "Pair-program for E04-S02 because R-3 is high" — not "communicate more."
+- **Owned:** a person.
+- **Bounded:** a deadline or a sprint to land it.
+
+If you pick 4+ changes, you'll execute 0. Choose.
+
+### 4. Write the doc
+
+Use the template; close the retro with the doc in front of the team.
+
+### 5. Trigger reads
+
+Wizer notifies Hill (who plugs the changes into next sprint planning), Hawkeye (who may revise risk profile), Fury (when an NFR principle change emerges).
+
+## Output template
 
 ```markdown
-# Retrospective — Sprint N
+---
+sprint: 7
+date: 2026-06-25
+facilitator: Wizer
+attendees: [Hill, Tony, Mantis, Pepper, Fury, Hawkeye, Shuri]
+---
+
+# Retrospective — Sprint 7
+
+## Sprint snapshot
+- Committed: 4 stories + 1 stretch
+- Shipped: 4 stories
+- Stretch: not pulled
+- Gates: 4 PASS, 1 CONCERNS, 0 FAIL
+- Blockers: 1 (vendor sandbox, resolved Day 5)
+- Carry-over to S8: 0
 
 ## Worked
-- …
+- Pairing on E03-S02 (auth refresh) — issue caught at integration test instead of in prod.
+- TEA design done at planning for R-3 stories paid off.
+- Mantis' "before/after" recordings in PRs accelerated review.
 
 ## Didn't work
-- …
+- Sprint-status entries went stale mid-sprint (Hill on vacation).
+- E02-S02 was too big for one PR and should have been sliced; it stalled the sprint.
+- Vendor outage with no fallback caught us cold.
 
 ## Surprised us
-- …
+- A11y audit caught 3 issues on a screen Mantis had already signed off on (axe found dynamic-content edge cases).
+- Cost dashboard showed mailer spend doubled — outbox retry was too aggressive.
+
+## Changes for Sprint 8
+
+1. **Sprint-status delegation rotation** — when Hill is OOO, Wizer takes over. *Owner: Wizer. By: Sprint 8 Day 1.*
+2. **Slice-check every story at planning** — any story that can't be described as a single PR gets split before it's pulled. *Owner: Tony. By: Sprint 8 planning.*
+3. **Vendor fallback drill** — quarterly, simulate top-3 vendor outages. *Owner: Hawkeye + Tony. By: end of Q3.*
+
+## Decisions made
+- Mailer retry policy updated (NFR-01-1).
+- Risk profile revised: R-1 mitigation now confirmed.
 
-## Changes next sprint (owner + due date)
-- [ ] … — owner: …
+## Notes for next sprint
+- Carry zero stories; everyone starts S8 fresh.
+- Stretch goal in S8: catch up on REV-01 (copy fix from S7).
 ```
+
+## Anti-patterns Wizer rejects (politely)
+
+- **A retro without a change.** Then it was venting.
+- **"We need to communicate better."** Specific or it doesn't count.
+- **Adopting > 3 changes.** None will land.
+- **No owner / no deadline.** Hopes, not plans.
+- **Skipping the retro to "save time."** The next sprint costs more.
+
+## Hand-off
+
+> Retro at `.wize/implementation/retrospective/2026-06-25.md`. 3 changes; owners assigned. Sprint 8 planning anchors on them. Hawkeye, please update `risk-profile.md` with the R-1 mitigation confirmed.