wizz-method 1.0.3 → 1.1.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "wizz-method",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "description": "Wizz Method — método de agência orientado por IA em PT-BR (fork independente do BMad Method)",
   "keywords": [
     "agile",
@@ -42,9 +42,11 @@
     "prepare": "command -v husky >/dev/null 2>&1 && husky || exit 0",
     "quality": "npm run format:check && npm run lint && npm run lint:md && npm run docs:build && npm run test:install && npm run test:urls && npm run validate:refs && npm run validate:skills && npm run docs:validate-sidebar",
     "rebundle": "node tools/installer/bundlers/bundle-web.js rebundle",
-    "test": "npm run test:refs && npm run test:install && npm run test:urls && npm run test:channels && npm run lint && npm run lint:md && npm run format:check",
+    "test": "npm run test:refs && npm run test:install && npm run test:urls && npm run test:channels && npm run test:mcp && npm run test:cli && npm run lint && npm run lint:md && npm run format:check",
     "test:channels": "node test/test-installer-channels.js",
+    "test:cli": "node test/test-cli-config.js",
     "test:install": "node test/test-installation-components.js",
+    "test:mcp": "node test/test-mcp-config.js",
     "test:refs": "node test/test-file-refs-csv.js",
     "test:urls": "node test/test-parse-source-urls.js",
     "validate:refs": "node tools/validate-file-refs.js --strict",

package/skills-registry.yaml

@@ -0,0 +1,318 @@
+# Wizz Method — Skills Registry (fonte única)
+#
+# Mapeia cada skill global a uma ÁREA (dona = agente wizz), cada SQUAD a um
+# domínio consultivo, e dá um campo "when" curto pra desambiguar skills
+# parecidas. Dois consumidores leem este arquivo:
+#   1. O INSTALLER — decide quais skills copiar pra .claude/skills por área escolhida.
+#   2. O MAESTRO/ROUTER — decide pra qual agente/skill/squad rotear.
+# Mantê-los lendo o MESMO arquivo garante que roteamento e instalação nunca divirjam.
+#
+# Skills vivem em src/skills-lib/<id>/. Squads em src/squads/<id>/ (via wizz-party-mode).
+#
+# MCPs (Model Context Protocol servers) também são declarados aqui, por área, no
+# campo `mcps:` (e `mcp_utility:` para os cross-cutting). Cada entrada tem:
+#   id      — nome do server no config da IDE (chave em mcpServers)
+#   when    — quando esse MCP ajuda (desambigua, igual ao `when` das skills)
+#   server  — { command, args, env } gravado no .mcp.json pelo installer
+# Secrets em `env` são SEMPRE placeholders `${VAR}` — o installer nunca escreve
+# token real. O installer instala/recomenda os MCPs das áreas escolhidas; o
+# maestro/router oferece o MCP certo em runtime. Mesma fonte única das skills.
+
+version: 1
+
+# ─────────────────────────────────────────────────────────────────────────────
+# ÁREAS — cada uma tem um agente dono (executor) e as skills que ele puxa.
+# ─────────────────────────────────────────────────────────────────────────────
+areas:
+  designer:
+    agent: wizz-designer
+    summary: "Design de produto e UI: interfaces, landing pages, design systems, motion, 3D."
+    skills:
+      - id: ui-ux-pro-max
+        when: "Design system, paleta, tipografia, componente; pedido de UI amplo. Principal de busca de padrões/estilos."
+      - id: impeccable
+        when: "Gate de polish/qualidade de frontend: hardening de UI, acessibilidade, anti-padrões. Refina o que já existe."
+      - id: huashu-design
+        when: "Direção visual + protótipo HTML hi-fi, exploração de variantes, review 5-dim, export MP4/GIF."
+      - id: premium-landing-ui-researcher
+        when: "Projeto NOVO (greenfield): cria landing premium do zero, hero, 3D high-end. Estratégia source-first."
+      - id: ui-component-curator
+        when: "Projeto EXISTENTE: qual componente/efeito adicionar que combina com o estilo atual."
+      - id: motion-3d-director
+        when: "Direção de motion/animação, 3D, WebGL, scroll cinematográfico, image-to-video."
+      - id: remotion-best-practices
+        when: "Vídeo programático em React (Remotion) especificamente."
+      - id: taste-skill
+        when: "Anti-slop em briefs NOVOS: lê o brief, define a direção e audita contra defaults de AI."
+      - id: taste-redesign
+        when: "Anti-slop em projeto EXISTENTE: audita o código atual, lista problemas, prioriza fixes."
+      - id: react-components
+        when: "Converter design (Stitch MCP) em componentes React/Vite."
+      - id: decision-maker
+        when: "Brief visual inicial: força 6 decisões de estética + 3 lógicas. Entra no kickoff, antes de construir."
+    mcps:
+      - id: magic
+        when: "Gerar/refinar componentes prontos via 21st.dev (UI builder, inspiration, refiner)."
+        server:
+          command: npx
+          args: ["-y", "@21st-dev/magic"]
+          env:
+            API_KEY: "${MAGIC_API_KEY}"
+    references:
+      - "references/premium-agency-rules.md (regras $150k-tier, importadas por impeccable/huashu no modo high-end)"
+
+  copy:
+    agent: wizz-copy
+    summary: "Copywriting: texto de venda, headlines, páginas, e-mails, sequências."
+    skills:
+      - id: copywriting
+        when: "Escrever copy de venda/página/headline do zero ou reescrever."
+      - id: copy-editing
+        when: "Editar/melhorar copy existente (framework Seven Sweeps). Review editorial geral."
+      - id: humanizer
+        when: "Texto soa AI: remover padrões de escrita de máquina, dar naturalidade."
+      - id: email-sequence
+        when: "Sequências de e-mail (onboarding, nurture, lançamento)."
+      - id: cold-email
+        when: "Cold email / outbound B2B / prospecção."
+      - id: sales-enablement
+        when: "Material de vendas: deck, one-pager, objeções, demo script, playbook."
+
+  seo:
+    agent: wizz-seo
+    summary: "SEO: auditoria, busca, AI search, schema, SEO programático."
+    skills:
+      - id: seo-audit
+        when: "Ponto de partida: auditar/diagnosticar SEO, queda de tráfego, ranking, core web vitals."
+      - id: ai-seo
+        when: "Otimizar pra ser citado por LLMs/AI search (AEO/GEO/LLMO, AI Overviews)."
+      - id: schema-markup
+        when: "Implementar dados estruturados / structured data."
+      - id: programmatic-seo
+        when: "Gerar páginas em escala pra atacar muitas keywords."
+      - id: site-architecture
+        when: "Arquitetura de site / topic clusters / estrutura de URLs."
+
+  growth:
+    agent: wizz-growth
+    summary: "Growth e conversão: marketing, CRO, lançamento, preço, retenção."
+    skills:
+      - id: marketing-ideas
+        when: "Travou / quer inspiração ampla de marketing. Ponto de partida quando não sabe o canal."
+      - id: marketing-psychology
+        when: "Aplicar gatilhos/vieses/modelos mentais à persuasão."
+      - id: product-marketing-context
+        when: "Posicionamento de produto e contexto de marketing do produto."
+      - id: launch-strategy
+        when: "Lançar produto/feature: Product Hunt, GTM, waitlist, beta."
+      - id: pricing-strategy
+        when: "Preço, planos, freemium, packaging, willingness to pay."
+      - id: paywall-upgrade-cro
+        when: "Tela de upgrade in-app / paywall."
+      - id: churn-prevention
+        when: "Churn, retenção, cancelamento, NPS."
+      - id: revops
+        when: "Operações de receita: pipeline, métricas, processo de revenue."
+      - id: page-cro
+        when: "Otimizar conversão de página (home, landing, pricing, feature)."
+      - id: form-cro
+        when: "Otimizar formulários (fora de signup)."
+      - id: popup-cro
+        when: "Otimizar popups/modais."
+      - id: onboarding-cro
+        when: "Ativação pós-signup / onboarding de usuário."
+      - id: signup-flow-cro
+        when: "Fluxo de signup/registro."
+      - id: content-strategy
+        when: "Decidir O QUE produzir de conteúdo (topic clusters, calendário, pilares)."
+      - id: social-content
+        when: "Criar/agendar conteúdo de social (LinkedIn, X, TikTok, IG...)."
+      - id: competitor-alternatives
+        when: "Página de comparação vs concorrente / alternatives / battle card."
+      - id: referral-program
+        when: "Programa de indicação/afiliados."
+      - id: free-tool-strategy
+        when: "Ferramenta grátis pra captação de leads."
+      - id: ab-test-setup
+        when: "Montar A/B test / experimento de conversão."
+      - id: analytics-tracking
+        when: "Setar/auditar tracking e medição (GA4, GTM, eventos, UTM, atribuição)."
+
+  ads:
+    agent: wizz-ads
+    summary: "Mídia paga: campanhas Google/Meta/TikTok/LinkedIn, criativos, tracking."
+    skills:
+      - id: paid-ads
+        when: "Estratégia de campanha, targeting, bidding, ROAS/CPA. Decidir/rodar ads."
+      - id: ad-creative
+        when: "Gerar/iterar criativos e headlines de anúncio em escala (RSA, variações)."
+      - id: analytics-tracking
+        when: "Tracking de conversão pros anúncios (compartilhada com growth)."
+    mcps:
+      - id: meta-ads
+        when: "Gestão real de campanha Meta/Facebook/Instagram via API (criar/editar/medir ads)."
+        server:
+          command: npx
+          args: ["-y", "mcp-meta-ads"]
+          env:
+            META_ACCESS_TOKEN: "${META_ACCESS_TOKEN}"
+
+  architect:
+    agent: wizz-agent-architect
+    summary: "Arquitetura, banco, segurança, infra, decisões técnicas."
+    skills:
+      - id: web-security
+        when: "Auditar segurança web, OWASP, XSS/CSRF/injeção, headers, rate limit, antes de deploy/PR."
+      - id: auth-and-secrets
+        when: "Auth (JWT/OAuth/SSO/Clerk), gestão de secrets, rotação de credenciais."
+      - id: desktop-security
+        when: "Segurança desktop/Electron (contextIsolation, code signing)."
+      - id: database-scaling
+        when: "Banco lento, queries, índices, N+1, sharding, connection pool."
+      - id: caching-and-queues
+        when: "Cache (Redis), filas (BullMQ/SQS/Kafka), jobs assíncronos."
+      - id: infrastructure
+        when: "Escala de infra: Kubernetes, auto-scaling, CDN, SLOs, load test."
+      - id: cloud-and-infra
+        when: "Custo de cloud: right-sizing, spot/reserved, S3 lifecycle, billing AWS/GCP."
+      - id: database-and-deps
+        when: "Dependências/packages, vulnerabilidades, npm audit."
+      - id: supabase-postgres-best-practices
+        when: "Performance e boas práticas de Postgres/Supabase (queries, schema, RLS)."
+    mcps:
+      - id: supabase
+        when: "Operar Supabase de verdade: rodar SQL, migrations, inspecionar schema/RLS, logs."
+        server:
+          command: npx
+          args: ["-y", "@supabase/mcp-server-supabase@latest"]
+          env:
+            SUPABASE_ACCESS_TOKEN: "${SUPABASE_ACCESS_TOKEN}"
+
+  qa:
+    agent: wizz-qa
+    summary: "QA: verificar o código de fora (testes, E2E, review adversarial)."
+    skills:
+      - id: adversarial-reviewer
+        when: "Caçar bugs adversarialmente, stress-test de PR, 'tear this apart'. (Global; o engine usa wizz-review-adversarial-general por dentro.)"
+      - id: agent-browser
+        when: "Verificação visual/browser, preencher forms, screenshots, testar UI no navegador. CLI já instalado (não é MCP); browser SEMPRE via agent-browser, nunca Playwright."
+    # qa NÃO declara mcps: verificação de browser é via agent-browser (CLI/skill),
+    # não via MCP. Não usar o MCP do Playwright.
+    clis:
+      - id: agent-browser
+        when: "Dirigir um browser real pra E2E/verificação: navegar, clicar, preencher form, screenshot, console. É CLI, não MCP."
+        check: "agent-browser --version"
+        install: "npm install -g agent-browser"
+
+  analyst:
+    agent: wizz-agent-analyst
+    summary: "Análise, pesquisa, brief, kickoff de projeto."
+    skills:
+      - id: inicio-de-projeto
+        when: "Kickoff LEVE de engenharia: stack, personas, glossário, princípios, estrutura de pastas, checklist. Atalho sem cerimônia de PRD."
+      - id: implementation-planner
+        when: "Plano técnico de implementação de site/app premium pós-direção aprovada."
+    mcps:
+      - id: exa
+        when: "Pesquisa web/prior-art durante planejamento (web search, descoberta de fontes)."
+        server:
+          command: npx
+          args: ["-y", "exa-mcp-server"]
+          env:
+            EXA_API_KEY: "${EXA_API_KEY}"
+
+  memoria:
+    agent: wizz-memoria
+    summary: "Memória do projeto: o que foi decidido, salvar, ver estado."
+    skills:
+      - id: cerebro
+        when: "Recuperar/salvar decisões, contexto, aprendizados; ver estado do projeto (/ver, /salvar, /decisao, /dump)."
+
+# ─────────────────────────────────────────────────────────────────────────────
+# UTILITÁRIOS — cross-cutting, não pertencem a uma área só.
+# ─────────────────────────────────────────────────────────────────────────────
+utility:
+  - id: graphify
+    when: "Transformar código/docs em knowledge graph; navegar estrutura antes de ler arquivos crus."
+  - id: find-skills
+    when: "Nenhuma skill cobre o pedido: buscar/instalar no marketplace (npx skills find)."
+  - id: enhance-prompt
+    when: "Empacotar um briefing mais completo/estruturado pra mandar a outro agente ou skill."
+  - id: wizz-router
+    when: "Roteador global/flat: descobre skills quando não se sabe a área; escala pro maestro se multi-área."
+
+# ─────────────────────────────────────────────────────────────────────────────
+# MCP_UTILITY — MCPs cross-cutting, oferecidos independente da área escolhida.
+# ─────────────────────────────────────────────────────────────────────────────
+mcp_utility:
+  - id: context7
+    when: "Docs atualizadas de qualquer lib/framework/SDK (React, Next, Prisma, Tailwind...). Útil em todo dev."
+    server:
+      command: npx
+      args: ["-y", "@upstash/context7-mcp"]
+
+# ─────────────────────────────────────────────────────────────────────────────
+# CLIs — ferramentas de linha de comando que os agentes chamam direto (não são
+# MCP nem skill). O installer DETECTA se já estão instaladas (check) e, por
+# padrão, só RECOMENDA o comando de install; instala de verdade apenas se o
+# usuário marcar. `clis:` por área; `cli_utility:` para as cross-cutting.
+# ─────────────────────────────────────────────────────────────────────────────
+cli_utility:
+  - id: rtk
+    when: "Token economy: proxy que corta 60-90% de tokens em comandos de dev. O wizz-router assume RTK ativo (Passo 0). Útil em todo o ecossistema."
+    check: "rtk --version"
+    install: "curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh"
+
+# ─────────────────────────────────────────────────────────────────────────────
+# SQUADS — painéis consultivos de personas (rodam via wizz-party-mode).
+# Aconselham; depois o agente wizz da área executa. Domínio → quem chamar.
+# ─────────────────────────────────────────────────────────────────────────────
+squads:
+  brand-squad:
+    domain: "Branding, posicionamento, arquitetura de marca, naming, arquétipos."
+    advises: [copy, designer]
+    when: "Validar/definir posicionamento, identidade e estratégia de marca. Painel: Al Ries, Byron Sharp, Marty Neumeier, Kapferer, Keller..."
+  copy-squad:
+    domain: "Copywriting, mensagem, oferta, persuasão."
+    advises: [copy]
+    when: "Pressionar/afiar copy e mensagem antes do wizz-copy escrever."
+  design-squad:
+    domain: "Design visual e UX."
+    advises: [designer]
+    when: "Painel de design pra direção visual/UX antes do wizz-designer executar."
+  c-level-squad:
+    domain: "Estratégia de negócio, decisões executivas."
+    advises: [analyst, pm, growth]
+    when: "Decisão estratégica de alto nível, visão de negócio, board simulado."
+  advisory-board:
+    domain: "Consultoria geral multidisciplinar."
+    advises: [analyst, growth]
+    when: "Conselho amplo quando o problema cruza várias áreas."
+  data-squad:
+    domain: "Dados, analytics, métricas."
+    advises: [analyst, growth]
+    when: "Análise de dados, definição de métricas, leitura de resultados."
+  traffic-masters:
+    domain: "Tráfego pago, aquisição."
+    advises: [ads, growth]
+    when: "Estratégia de tráfego pago e aquisição antes do wizz-ads rodar campanha."
+  hormozi-squad:
+    domain: "Ofertas, monetização, growth agressivo."
+    advises: [growth, copy]
+    when: "Desenhar oferta irresistível, pricing/value stack, growth estilo Hormozi."
+  storytelling:
+    domain: "Narrativa, storytelling de marca/conteúdo."
+    advises: [copy, growth]
+    when: "Construir narrativa, história de marca, arco de conteúdo."
+  movement:
+    domain: "Comunidade, construção de movimento."
+    advises: [growth]
+    when: "Construir comunidade/movimento em torno do produto."
+  cybersecurity:
+    domain: "Segurança ofensiva/defensiva."
+    advises: [architect, qa]
+    when: "Painel de segurança pra threat modeling e hardening."
+  claude-code-mastery:
+    domain: "Claude Code, tooling de agentes, automação de dev."
+    advises: [dev, architect]
+    when: "Dominar Claude Code, hooks, skills, workflows de agente."

package/src/bmm-skills/4-implementation/wizz-quick-dev/SKILL.md

@@ -33,6 +33,13 @@ A specification should target a **single user-facing goal** within **900–1600
 - **900–1600 tokens**: Optimal range for LLM consumption. Below 900 risks ambiguity; above 1600 risks context-rot in implementation agents.
 - **Neither limit is a gate.** Both are proposals with user override.
 
+## Handoff — escalate up when scope balloons
+
+You are the leaf: the maestro demotes here for pointed work (bug, tweak, single-goal feature). Re-check scope against the shared complexity signal (areas, steps, needs-planning?, artifact+memory?):
+
+- If clarification reveals the request is actually **multi-goal / multi-area** (2+ top-level shippable deliverables, or it spans several areas), do not silently absorb it. Surface it and propose escalating to `wizz-maestro` to orchestrate the sequence. Proceed solo only if the user confirms a narrowed single goal.
+- Stay solo for genuinely single-goal work, even when it crosses layers/files.
+
 ## Conventions
 
 - Bare paths (e.g. `step-01-clarify-and-route.md`) resolve from the skill root.

package/src/core-skills/wizz-editorial-review-prose/SKILL.md

@@ -7,63 +7,38 @@ description: 'Clinical copy-editor that reviews text for communication issues. U
 
 **Goal:** Review text for communication issues that impede comprehension and output suggested fixes in a three-column table.
 
-**Your Role:** You are a clinical copy-editor: precise, professional, neither warm nor cynical. Apply Microsoft Writing Style Guide principles as your baseline. Focus on communication issues that impede comprehension — not style preferences. NEVER rewrite for preference — only fix genuine issues. Follow ALL steps in the STEPS section IN EXACT ORDER. DO NOT skip steps or change the sequence. HALT immediately when halt-conditions are met. Each action within a step is a REQUIRED action to complete that step.
+**Architecture note (delegating bridge):** This skill is a thin bridge. The substantive review logic lives in the global `copy-editing` skill (Seven Sweeps framework — more rigorous than a linear pass) and, when the text reads as AI-generated, the `humanizer` skill. This bridge keeps a stable name/contract because BMM workflows (`wizz-prd`, `wizz-ux`, `wizz-architecture`, `wizz-product-brief`) invoke `wizz-editorial-review-prose` by name. It always returns the same three-column table so those workflows are unaffected.
 
-**CONTENT IS SACROSANCT:** Never challenge ideas — only clarify how they're expressed.
+**Your Role:** Clinical copy-editor: precise, professional, neither warm nor cynical. Focus on communication issues that impede comprehension — not style preferences. NEVER rewrite for preference — only fix genuine issues.
+
+**CONTENT IS SACROSANCT:** Never challenge ideas — only clarify how they're expressed. This constraint overrides any guidance from the delegated skills.
 
 **Inputs:**
 - **content** (required) — Cohesive unit of text to review (markdown, plain text, or text-heavy XML)
-- **style_guide** (optional) — Project-specific style guide. When provided, overrides all generic principles in this task (except CONTENT IS SACROSANCT). The style guide is the final authority on tone, structure, and language choices.
+- **style_guide** (optional) — Project-specific style guide. When provided, overrides all generic principles (except CONTENT IS SACROSANCT). It is the final authority on tone, structure, and language choices.
 - **reader_type** (optional, default: `humans`) — `humans` for standard editorial, `llm` for precision focus
 
-
-## PRINCIPLES
-
-1. **Minimal intervention:** Apply the smallest fix that achieves clarity
-2. **Preserve structure:** Fix prose within existing structure, never restructure
-3. **Skip code/markup:** Detect and skip code blocks, frontmatter, structural markup
-4. **When uncertain:** Flag with a query rather than suggesting a definitive change
-5. **Deduplicate:** Same issue in multiple places = one entry with locations listed
-6. **No conflicts:** Merge overlapping fixes into single entries
-7. **Respect author voice:** Preserve intentional stylistic choices
-
-> **STYLE GUIDE OVERRIDE:** If a style_guide input is provided, it overrides ALL generic principles in this task (including the Microsoft Writing Style Guide baseline and reader_type-specific priorities). The ONLY exception is CONTENT IS SACROSANCT — never change what ideas say, only how they're expressed. When style guide conflicts with this task, style guide wins.
-
-
 ## STEPS
 
 ### Step 1: Validate Input
+- If content is empty or fewer than 3 words: **HALT** with error: "Content too short for editorial review (minimum 3 words required)"
+- If reader_type is not `humans`, `llm`, or absent: **HALT** with error: "Invalid reader_type. Must be 'humans' or 'llm'"
+- Identify content type; note code blocks, frontmatter, and structural markup to skip (never edit these).
 
-- Check if content is empty or contains fewer than 3 words
-  - If empty or fewer than 3 words: **HALT** with error: "Content too short for editorial review (minimum 3 words required)"
-- Validate reader_type is `humans` or `llm` (or not provided, defaulting to `humans`)
-  - If reader_type is invalid: **HALT** with error: "Invalid reader_type. Must be 'humans' or 'llm'"
-- Identify content type (markdown, plain text, XML with text)
-- Note any code blocks, frontmatter, or structural markup to skip
-
-### Step 2: Analyze Style
+### Step 2: Delegate the review
+Invoke the global `copy-editing` skill via the `Skill` tool, passing:
+- the `content` (prose sections only — code/markup excluded),
+- the `style_guide` if provided (instruct that it is the final authority, except CONTENT IS SACROSANCT),
+- the `reader_type` framing: if `llm`, prioritize unambiguous references, consistent terminology, explicit structure, no hedging; if `humans`, prioritize clarity, flow, readability.
 
-- Analyze the style, tone, and voice of the input text
-- Note any intentional stylistic choices to preserve (informal tone, technical jargon, rhetorical patterns)
-- Calibrate review approach based on reader_type:
-  - If `llm`: Prioritize unambiguous references, consistent terminology, explicit structure, no hedging
-  - If `humans`: Prioritize clarity, flow, readability, natural progression
+Instruct `copy-editing` to operate in **comprehension-only mode**: minimal intervention, fix prose within existing structure (never restructure), preserve author voice, flag uncertain fixes as a query rather than a definitive change, and NEVER alter what ideas say.
 
-### Step 3: Editorial Review (CRITICAL)
+**If `reader_type` is `humans`** and the text shows signs of AI-generated writing (inflated symbolism, rule-of-three padding, em-dash overuse, vague attributions, negative parallelisms): also invoke `humanizer` on the affected passages and fold its fixes in.
 
-- If style_guide provided: Consult style_guide now and note its key requirements — these override default principles for this review
-- Review all prose sections (skip code blocks, frontmatter, structural markup)
-- Identify communication issues that impede comprehension
-- For each issue, determine the minimal fix that achieves clarity
-- Deduplicate: If same issue appears multiple times, create one entry listing all locations
-- Merge overlapping issues into single entries (no conflicting suggestions)
-- For uncertain fixes, phrase as query: "Consider: [suggestion]?" rather than definitive change
-- Preserve author voice — do not "improve" intentional stylistic choices
+**Fallback (skill unavailable):** If `copy-editing` is not installed/resolvable, perform the review inline using these principles — minimal intervention, preserve structure, skip code/markup, query when uncertain, deduplicate identical issues into one entry with all locations listed, merge overlapping fixes, respect author voice — applying Microsoft Writing Style Guide as the baseline.
 
-### Step 4: Output Results
-
-- If issues found: Output a three-column markdown table with all suggested fixes
-- If no issues found: Output "No editorial issues identified"
+### Step 3: Normalize and output
+Map every confirmed fix into the canonical three-column table. Deduplicate (same issue in multiple places = one entry listing all locations) and merge overlapping fixes before output.
 
 **Output format:**
 
@@ -78,9 +53,9 @@ description: 'Clinical copy-editor that reviews text for communication issues. U
 | The system will processes data and it handles errors. | The system processes data and handles errors. | Fixed subject-verb agreement ("will processes" to "processes"); removed redundant "it" |
 | Users can chose from options (lines 12, 45, 78) | Users can choose from options | Fixed spelling: "chose" to "choose" (appears in 3 locations) |
 
+If no issues found after thorough review: output "No editorial issues identified".
 
 ## HALT CONDITIONS
-
 - HALT with error if content is empty or fewer than 3 words
 - HALT with error if reader_type is not `humans` or `llm`
-- If no issues found after thorough review, output "No editorial issues identified" (this is valid completion, not an error)
+- "No editorial issues identified" is valid completion, not an error