wize-dev-kit 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -5,6 +5,22 @@ Format inspired by [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.10.0] — 2026-07-31
+
+Entrada da demanda ganha entrevista estruturada (**`wize-grill`**, adaptado do princípio grill-me) e o loop de implementação ganha verificação automática com guardas de ciclo. Suite verde (246 testes, validate 74 arquivos).
+
+### Added
+
+- **`wize-grill`** (nova skill core) — entrevista exaustiva do usuário até entendimento compartilhado, antes de redigir briefs, PRDs, epics, stories ou planos. 5 regras: uma pergunta por vez · toda pergunta traz resposta recomendada · fatos são buscados no repo/`.wize/` (só decisões vão ao usuário) · árvore de decisão em ordem de dependência · nada de redigir antes da confirmação. Question ladder de 7 degraus (problema → outcome → audiência → escopo → constraints → riscos → validação) mapeada aos campos dos artefatos; profundidade calibrada por classe (Quick Dev nunca é grelhado; incremental usa passe curto; new value usa a escada inteira); atalho de momentum (3 "como você recomenda" seguidos → modo batch). Sem artefato próprio: decisões vão para os campos do artefato alvo, pendências viram Open questions com dono.
+- **`wize-dev-story`** — Step 7.5 "Loop verification": auto-check antes de declarar o loop concluído (evidência de iteração no `git log`, mapa AC→teste completo, todos os testes de AC verdes) com retorno ao passo correto em caso de falha, e **max-cycles guard** (mesmo AC falhando 3+ ciclos → escala pra Wizer). Step 11 ganha **loop-back protocol** para findings de gate (blocking → volta ao Red; non-blocking → corrige no mesmo PR) com max-retry guard.
+- **`wize-correct-course`** — auto-trigger pelo max-cycles guard e monitor de staleness, além da invocação manual.
+
+### Changed
+
+- **`wize-help`** — sugere `wize-grill` (sempre sugestivo, nunca imposto): no Step 2 quando a demanda difusa ruma a um passo de autoria, no Step 4 como oferta, e em `/wize-help mission` antes de emitir um contrato oco (Objective/Scope/ACs sem resposta no estado do projeto).
+- **`wize-product-brief` / `wize-create-prd` / `wize-create-epics-and-stories`** — ganchos de grill nos pontos de autoria: mais de uma decisão aberta → oferecer entrevista em vez de chutar; respostas caem direto nos campos do artefato.
+- **`wize-spec`** — modo guided referencia o protocolo grill (uma pergunta por turno, recomendação anexada).
+
 ## [0.9.0] — 2026-07-14
 
 A cadeia do WDK passa a operar por **mission contracts** — cada etapa declara objetivo, fontes de verdade, escopo, critérios de aceite, contratos de execução/validação e persistência em `.wize/`, no formato que modelos de longo horizonte executam melhor. Suite verde (246 testes, validate 73 arquivos).

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "wize-dev-kit",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Full-lifecycle AI-assisted development kit with Test Architect and Whiteport Design Studio embedded. Inspired by BMAD Method and WDS.",
   "keywords": [
     "ai",

package/src/core-skills/module.yaml

@@ -13,6 +13,9 @@ skills:
   - code: wize-advanced-elicitation
     name: "Advanced Elicitation"
     description: "Structured technique stack (laddering, 5-why, SCAMPER) callable by any agent."
+  - 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-brainstorming
     name: "Brainstorming"
     description: "Divergent-then-convergent ideation; produces idea-pool.md."

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

@@ -0,0 +1,75 @@
+---
+code: wize-grill
+name: Grill
+module: core
+status: ready
+---
+
+# Grill
+
+**Goal.** Interview the user exhaustively about a demand until both sides reach **shared understanding** — before any artifact is drafted. Sharper answers make a sharper brief, PRD, epic, story, or plan. Grill is an input-quality tool, not an artifact of its own.
+
+Any persona about to author an artifact can invoke it: Pepper before a brief, Maria Hill before a PRD, Tony before epics/stories/architecture, Wizer when a demand arrives fuzzy. Wizer also **suggests** it from `/wize-help` — always suggest, never force.
+
+## The five rules
+
+1. **One question at a time.** Ask, then wait for the answer. A batch of questions is bewildering and produces shallow answers.
+2. **Every question ships with a recommendation.** State your recommended answer and a one-line reason. The user confirms or corrects — far cheaper than answering from scratch.
+3. **Facts are looked up; decisions are asked.** If the answer lives in the repo, `.wize/`, or the environment (stack, existing behavior, conventions, prior artifacts), fetch it — never ask. Only genuine decisions — trade-offs, priorities, scope calls — go to the user.
+4. **Walk the decision tree in dependency order.** Resolve upstream decisions before the downstream ones that depend on them. Don't ask about scope before the problem is agreed.
+5. **No drafting until confirmed.** Close with a compact summary of every decision made and ask for confirmation of shared understanding. Only then hand back to the authoring workflow.
+
+## Question ladder (dependency order)
+
+Climb top-down; **skip any rung an existing artifact already answers** (brief, trigger map, PRD, architecture — check first, rule 3).
+
+| Rung | Resolves | Feeds |
+|---|---|---|
+| 1. Problem | What hurts, for whom, what's the evidence it hurts | Brief vision / story context |
+| 2. Outcome | The observable result that means "solved" — metric, target, deadline | Success criteria / PRD goals |
+| 3. Audience | Primary user (role + JTBD), who else is affected | Brief audience / trigger map |
+| 4. Scope | What's in, what's explicitly out, non-goals | PRD scope table / story restrictions |
+| 5. Constraints | Deadline, budget, compliance, integrations, protected behaviors | Brief constraints / restrictions |
+| 6. Risks & assumptions | What, if wrong, changes the plan | PRD assumptions / risk profile |
+| 7. Validation | How we'll verify — which checks, which ACs, what "done" means | ACs / validation contract |
+
+When an answer comes back vague, apply a technique from `wize-advanced-elicitation` (5 Whys, laddering, premortem) to that one rung before moving on.
+
+## Calibration — how hard to grill
+
+| Demand class | Depth |
+|---|---|
+| **Quick Dev** (bug fix, copy edit, dep bump) | Don't grill. One clarifying question max — grilling a typo fix is theater. |
+| **Full Lifecycle, incremental** (new story in a known epic) | Short pass: rungs 4, 5, 7 only — the upstream rungs live in the PRD. |
+| **Full Lifecycle, new value** (new feature, new product, new plan) | Full ladder. |
+
+Momentum shortcut: after **three consecutive "as you recommend"** answers, switch to batch mode — state the remaining recommendations as one list and ask for a single confirmation. Respect the user's time; the point is clarity, not ceremony.
+
+## Where answers land
+
+Grill produces no separate file. Route each decision to its home:
+
+- **Decisions** → the target artifact's fields (brief sections, PRD scope/ACs, story restrictions/validation contract) — in the artifact's own words, not chat quotes.
+- **Unresolved questions** → the artifact's *Open questions*, each with owner + priority (`blocker` / `important` / `nice-to-know`).
+- **Load-bearing trade-offs** → the artifact's decision log (or `DECISIONS.md` / an ADR when architectural).
+
+## Stop conditions
+
+Stop grilling when **any** of these hits:
+
+- Every relevant rung is resolved or explicitly parked as an open question with an owner.
+- The user says "enough" / "just go" — park the rest as open questions and proceed with your recommendations, flagged as assumptions.
+- The summary is confirmed — shared understanding reached.
+
+## Anti-patterns
+
+- Multiple questions in one message.
+- Asking a fact `grep` or `.wize/` would answer.
+- A question without a recommendation ("So… what do you want?").
+- Grilling a Quick Dev demand.
+- Re-opening a confirmed decision without new information.
+- Continuing to interrogate after confirmation — grill is a phase, not a personality.
+
+## Hand-off
+
+> Shared understanding confirmed: {n} decisions captured, {m} open questions parked with owners. Handing back to {persona} / `{workflow}` to draft the {artifact}.

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

@@ -50,7 +50,7 @@ Inside the spec folder:
 4. When input is mixed (brain dump, transcript, email), sort claims using the three-lens load-bearing test and route to the kernel field or a companion.
 5. Distill into the five-field kernel using `assets/spec-template.md`. When input is rich, extract directly. When input is sparse, choose:
    - **express** — best-effort distill, every gap becomes an `open_questions[]` entry
-   - **guided** — walk the five fields with the user one at a time
+   - **guided** — walk the five fields with the user one at a time, `wize-grill` style: one question per turn, recommendation attached
 6. Write lean: every sentence must earn its place.
 7. If input is genuinely too thin (e.g. "an app for hikers" with no context), stop and suggest `wize-product-brief` or `wize-create-prd`.
 

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

@@ -28,7 +28,7 @@ Pepper drives. Peggy edits prose. Output lands in `.wize/planning/brief.md`.
 
 ### 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.
+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
 

package/src/method-skills/2-plan-workflows/wize-create-prd/workflow.md

@@ -12,6 +12,8 @@ status: ready
 
 Maria Hill drives. Peggy edits prose. Output lands in `.wize/planning/prd.md`.
 
+Before drafting: if goals, scope, or ACs would need guessing beyond what the brief + trigger map answer, offer a `wize-grill` pass with the user first — decisions land in the PRD fields, leftovers in *Open questions*. Don't guess scope; ask.
+
 ## Inputs
 
 - `.wize/planning/brief.md` (vision, audience, success criteria).

package/src/method-skills/3-solutioning/wize-create-epics-and-stories/workflow.md

@@ -12,6 +12,8 @@ status: ready
 
 Tony drives. Output lands in `.wize/solutioning/epics/` and `.wize/solutioning/stories/`.
 
+When slicing raises decisions the PRD doesn't answer — priority order, sequencing, protected behaviors, what's out of a story — offer a short `wize-grill` pass with the user instead of guessing. Decisions land in the epic/story fields; unresolved ones become open questions with owners.
+
 ## Inputs
 
 Read central docs first, then expand by dependency — don't load unrelated files for padding:

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

@@ -14,10 +14,12 @@ Maria Hill chairs. Wizer is on call for cross-cutting decisions. The human alway
 
 ## When to run
 
-- `wize-sprint-status` flagged a risk: “slipping” or “at risk”.
-- The team says "we won’t make it" during a stand-up.
-- A story’s TEA gate came back as `FAIL` mid-sprint.
+- `wize-sprint-status` flagged a risk: "slipping" or "at risk".
+- The team says "we won't make it" during a stand-up.
+- A story's TEA gate came back as `FAIL` mid-sprint.
 - An external event (incident, vendor outage) consumed capacity.
+- **Automatic trigger:** any skill that completes step 7.5 (loop verification) and hits the max-cycles guard escalates to Wizer, who runs this skill.
+- **Staleness monitor:** if `wize-sprint-status` has not been updated in 2+ days, Wizer auto-runs this skill on session start (detected in step 1).
 
 ## Inputs
 

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

@@ -91,6 +91,18 @@ feat(invite): validate email per AC-02-1 / AC-02-2
 
 Until every AC has at least one test + minimum code that makes it pass.
 
+### 7.5. Loop verification (auto-check)
+
+Before declaring the loop done, run these checks:
+
+| Check | How | Fail → |
+|---|---|---|
+| **Evidence of iteration** | `git log --oneline` shows ≥2 commits with AC IDs (skip if story has only 1 AC) | Return to step 2 |
+| **AC-to-test mapping** | Every AC in the story file has a corresponding test case name | Return to step 3 (Red) |
+| **All AC tests green** | `npx vitest run --reporter=verbose` (or equivalent) — grep output for each AC's test name | Return to step 4 (Green) |
+
+**Max-cycles guard.** If the same AC cycles through Red→Green→Refactor 3+ times without staying green, stop and escalate to Wizer: the test design may be wrong, the AC may be mis-sized, or the approach may need Tony.
+
 ### 8. Knowledge update (inline, ~60s)
 
 Before opening the PR, ask: **did this story touch any of the 5 baseline axes** documented in `.wize/knowledge/document-project/`?
@@ -137,7 +149,13 @@ PR description includes:
 
 ### 11. Address gate findings
 
-If `tea-review` flags issues, fix them in the same PR or open a follow-up if the story has shipped a separate value-bearing slice.
+If `tea-review` or `tea-gate` flags issues, fix them in the same PR or open a follow-up if the story has shipped a separate value-bearing slice.
+
+**Loop-back protocol:**
+1. Read each finding's `severity` and `blocking` flag.
+2. For each `blocking: true` finding → return to step 3 (Red) for the affected AC.
+3. For each `blocking: false` finding → log in story `notes` and fix in same PR before re-submitting to gate.
+4. **Max-retry guard:** if the same story cycles through gate → fix → gate 3+ times, stop and escalate to Wizer. The story may be mis-sized, the test design may be wrong, or the ACs may need renegotiation with Hill.
 
 ## Security + perf during implementation
 

package/src/orchestrator-skills/wize-help/skill.md

@@ -50,6 +50,8 @@ Read these if they exist (absence is information too):
 
 Never pick Quick Dev to dodge writing artifacts. If the demand needs an AC, it is Full Lifecycle. When unsure, ask one question rather than guess the class.
 
+**Fuzzy demand → suggest a grill.** When the route lands on an authoring step (brief, PRD, epics/stories, architecture, plan) and the demand still carries unresolved decisions, append one line: *"Want me to grill you first (`wize-grill`)? Sharper answers, sharper {artifact}."* Suggest, never force — and never for Quick Dev.
+
 Otherwise apply this heuristic top-down; stop at the first match:
 
 | # | State | Next step |
@@ -108,11 +110,11 @@ For `mission`, emit the filled **Mission contract** (see the section below) from
 
 ## Step 4 — offer to act
 
-End with one of: "Want me to call {persona}?" · "Want me to baseline the repo first?" (brownfield, no document-project) · "Want me to convene party-mode with {p1} + {p2}?" (cross-cutting decision).
+End with one of: "Want me to call {persona}?" · "Want me to baseline the repo first?" (brownfield, no document-project) · "Want me to convene party-mode with {p1} + {p2}?" (cross-cutting decision) · "Want me to grill you first (`wize-grill`)?" (fuzzy demand heading into an authoring step).
 
 ## Mission contract (`/wize-help mission`)
 
-When asked for a mission, fill this from project state and hand it to the executing persona. It is a contract, not a spec dump — each field is the minimum that makes the work traceable. Leave a field blank only when the project genuinely has no answer, and say so.
+When asked for a mission, fill this from project state and hand it to the executing persona. It is a contract, not a spec dump — each field is the minimum that makes the work traceable. Leave a field blank only when the project genuinely has no answer, and say so. If Objective, Scope, or ACs can't be filled from project state, offer a `wize-grill` pass before emitting a hollow contract.
 
 ```
 MISSION CONTRACT — {demand in one line}