@guilhermefsousa/open-spec-kit 0.0.1

package/templates/agents/skills/discovery/SKILL.md

@@ -0,0 +1,406 @@
+---
+name: discovery
+description: "Reads PO demands and project context, identifies gaps and ambiguities, generates structured questions or a PRD. Handles the Q&A loop with the PO via Confluence."
+metadata:
+  works_on: [copilot, antigravity, claude]
+argument-hint: "[feature name or Confluence page ID]"
+---
+
+# Discovery
+
+## Objective
+
+Read all available inputs (PO demand, domain docs, architecture, existing code), identify what's missing or ambiguous, and either generate structured questions for the PO or produce a complete PRD.
+
+## Before you start
+
+### Validate prerequisites
+
+Before anything, verify that the project was set up correctly:
+
+1. Read `projects.yml` — if empty or has only template content, **stop** with message: "/setup não foi executado. Execute /setup antes de /discovery."
+2. **Confluence access — ALWAYS use MCP:**
+   - All Confluence operations (read pages, create pages, labels) MUST use the MCP server (`confluence` in `.mcp.json`).
+   - **Do NOT use curl, fetch, or direct REST calls** — even if `.env` has credentials.
+   - If MCP is not responding → **STOP**: "MCP Confluence não disponível. Execute 'open-spec-kit doctor' para diagnosticar."
+3. Verify these pages exist under the project root (`root_page_id` from `projects.yml`):
+   - `Visão do Produto` — if not found, **stop** with message: "Página 'Visão do Produto' não encontrada. Execute /setup primeiro."
+   - `Glossário` — if not found, **stop** with same message pattern
+   - `Domínio/` (with children: Regras, Fluxos, Tabelas, Integrações) — if not found, **stop**
+   - `Features/` — if not found, **stop**
+4. If any prerequisite fails, do NOT proceed. Report clearly what is missing.
+
+### Feature selection (BUG-032)
+
+If NO argument was passed (user ran `/discovery` without a feature name):
+
+1. List ALL features under `Features/` in Confluence
+2. For each feature, read the metadata table ("Depende de" field)
+3. Filter features with label `em-discovery` (ready for discovery)
+4. **Check dependencies**: a feature can only enter discovery if ALL features it depends on already have label `em-spec` or `done`. Features with unsatisfied dependencies: mark as "(blocked — depends on {SIGLA}-NNN)"
+5. Present the dev with the list of available (non-blocked) features, sorted by ID:
+   ```
+   Features disponíveis para /discovery:
+   1. ⚙️ TFB-000 - Infraestrutura e Scaffold
+   2. 🚀 TFB-001 - Importação de Faturas
+   3. 🚀 TFB-003 - Consulta de Faturas
+
+   Bloqueadas:
+   - 🚀 TFB-002 - Conferência (depende de TFB-001)
+   ```
+6. Ask: "Qual feature deseja trabalhar?"
+7. Proceed with the chosen feature.
+
+If argument WAS passed (e.g., `/discovery TFB-001`):
+- Locate the corresponding feature page and proceed normally.
+- If the feature has unsatisfied dependencies, **warn** but continue (dev may be working out of order intentionally).
+
+### Read context
+
+Read these files FIRST:
+1. `projects.yml` — repos, stack, dependencies, Confluence space
+2. `docs/architecture.md` — system structure
+3. ALL files in `docs/lessons/` — past mistakes to avoid
+4. ALL files in `docs/decisions/` — technical choices
+5. Recent specs in `specs/` — what was done before
+
+## Flow
+
+### 1. Compile all information
+
+From Confluence (via MCP), read:
+- The feature page in `Features/` (demand extracted by /setup)
+- `Dominio/` — business rules, flows, reference tables, integrations
+- `Visao do Produto` — product scope and success metrics
+- Previous Q&A rounds on the feature page (if any)
+
+From the spec repo, read:
+- `docs/architecture.md` — current system design
+- `docs/lessons/` — what went wrong before
+- `docs/decisions/` — technical constraints
+- `specs/` — ALL existing specs (brief.md, contracts.md, scenarios.md). These are the **baseline** for evolution.
+
+### 1b. Detect evolution context
+
+If `specs/` contains existing feature specs:
+- Read their `contracts.md` files — identify entities, endpoints, types, and error formats already defined
+- Read their `scenarios.md` files — identify behaviors already tested
+- This is the **existing system context**. The new feature builds ON TOP of this, not in isolation.
+
+When generating the PRD (Step 6), the discovery MUST:
+- **Reference** existing entities/endpoints instead of redefining them (e.g., "Utiliza a entidade `Usuario` já definida em specs/001")
+- **Identify impacts** on existing features (e.g., "Adiciona campo `saldo` à entidade `Conta` da feature 002")
+- **Reuse** existing types (ErrorResponse, PaginatedResponse) by reference, not copy
+- **Flag conflicts** if the new feature contradicts an existing spec (e.g., "Feature 003 diz que `Conta` não tem `saldo`, mas esta feature precisa de saldo")
+
+This ensures the PRD is a **complete description of the new feature** with explicit connections to the existing system — not a delta document, not a redefinition.
+
+### 1c. Read Figma design context (opcional)
+
+**Condition**: this step ONLY runs if BOTH conditions are true:
+1. `projects.yml` has a `figma:` section with `file_url` filled
+2. The Figma MCP is available (`figma` server configured)
+
+If either condition fails, **skip silently**.
+
+**If available:**
+1. Extract the file key from the URL in `projects.yml` → `figma.file_url` (segment after `/design/` or `/file/`)
+2. Use `get_design_context` with the file key to get an overview
+3. Use `search_design_system` with the feature name being analyzed to find relevant frames
+4. If related frames are found, use `get_metadata` on the specific frames to extract:
+   - Visible form fields (names, types, required indicators)
+   - Screen states (empty, loaded, error, loading)
+   - Navigation flows between screens
+   - Design system variables used (colors, spacing, tokens)
+
+**Impact on gap analysis (step 3):**
+- In the **UX** category: compare Figma design against demand requirements. If Figma shows fields or flows not mentioned in the demand, register as gap: "DESIGN: Figma mostra {elemento} mas demanda não menciona. Confirmar com PO se está no escopo."
+- In the **DATA** category: if Figma shows form fields, use them to validate/complete the entity and attribute list
+- In the **SCOPE** category: if Figma has screens not covered by the demand, register as scope gap
+
+**Impact on PRD (step 6):**
+- In the "Requisitos aceitos" section, reference Figma frames: "REQ-NN: [description] (ref: Figma frame '{frame_name}')"
+- Add optional section to the PRD: "### Referências visuais" with list of relevant frames and file keys
+
+**Rule**: if Figma shows behavior NOT described in the demand, register as business gap: "DESIGN: Figma mostra {X} mas demanda não menciona. PO precisa confirmar."
+
+### 2. Scan existing code (if repos exist)
+
+If `projects.yml` lists repos with `status: active` that already have code:
+- **Read** (in this order, stop when sufficient context is gathered):
+  1. Endpoints/controllers/routes — what APIs already exist
+  2. Entities/models — what data structures are defined
+  3. Event handlers/publishers — what async events exist
+  4. Tests — what behaviors are already validated
+- **Skip**: internal services, helpers, utilities, infrastructure code
+- Identify reuse opportunities (existing types, shared patterns) and constraints (naming conventions, error formats)
+
+### 3. Identify gaps
+
+**3a. Check for duplicates:**
+- Read existing specs in `specs/` — does a spec already cover this feature?
+- Read the PRD principal and existing feature pages — is this feature already described elsewhere?
+- If duplicate found: **warn** — "Feature já existe em specs/NNN ou na feature page {title}."
+  - If the feature page has label `prd-rejeitado`: this is a re-discovery — proceed normally (the previous PRD was rejected)
+  - If the feature page has label `em-spec` or `done`: **stop** — "Feature já especificada/implementada. Para re-fazer discovery, remova o label em-spec primeiro."
+  - Otherwise: ask the dev whether to continue or stop
+
+**3b. Cross-validate with existing rules AND specs:**
+- Read `Domínio/Regras` and compare against the feature requirements
+- If ANY requirement contradicts an existing RN, register it as a **critical gap** that MUST be resolved before generating the PRD
+- Format: "CONTRADIÇÃO: REQ-XX diz Y, mas RN-ZZ diz W. PO precisa decidir qual prevalece."
+- **Cross-validate with existing specs**: read `scenarios.md` and `contracts.md` from ALL existing specs in `specs/`. Check:
+  - Does this feature contradict a scenario from another feature? (ex: different error format, different ownership behavior)
+  - Does this feature reuse types defined in another feature? If yes, reference — do NOT redefine.
+  - Does this feature share endpoints with another? If yes, document explicitly which feature owns the endpoint and which extends it.
+  - If contradictions found, register as critical gap: "CONTRADIÇÃO COM SPEC: feature {NNN} scenarios.md CT-XX assume Y, mas esta feature requer W."
+
+**3c. Verify Glossary completeness:**
+- Read `Glossário` on Confluence
+- List every new term, entity, enum, or concept that this feature introduces and that is NOT yet in the Glossário
+- If new terms found, register them as a **glossary update** to be added when the PRD is finalized
+- Format: "GLOSSÁRIO: termos novos a adicionar — {term1} ({definition}), {term2} ({definition})"
+- This includes: new entities, new enum values, new technical concepts (ex: PaginatedResponse), new domain concepts (ex: "tarefa vencida")
+
+**3d. Coverage scan and gap compilation:**
+
+Scan the demand using this taxonomy. For each category, mark status:
+Covered / Partial / Missing.
+
+| Category | What to verify |
+|----------|---------------|
+| SCOPE | What's in/out? Duplicates existing feature? |
+| BUSINESS_RULES | Ambiguous logic? Contradicts existing RN? |
+| DATA | Entities clear? Types/formats defined? Estimated volume? |
+| INTEGRATION | External systems? Failure modes? Sync/async? |
+| SECURITY | Sensitive data? Auth requirements? Redaction needed? |
+| PERFORMANCE | SLAs? Expected load? Rate limits? |
+| UX | Error messages? Empty states? (if frontend) |
+
+**Special rule — PERFORMANCE**: this category can NEVER be marked as "Covered" without at least one question about: data limits (how many records per entity?), response SLA (max acceptable response time per endpoint), or expected throughput (requests/second, concurrent users). If the PO demand does not mention performance, ASK — absence of a performance requirement does not mean "no requirement", it means "undocumented implicit requirement".
+
+For each category marked Partial or Missing, generate a candidate question.
+
+**Prioritize:** Impact (High/Medium/Low) x Blocks spec? (Yes/No).
+Select at most **5 questions**, prioritizing those that block.
+
+Categorize each gap as:
+- **Business gap** — PO needs to decide (business rules, scope, priorities)
+- **Technical gap** — team needs to decide (architecture, patterns, tech choices)
+
+### 4. Assess feature scope
+
+Before deciding questions vs PRD, assess the scope:
+- Count how many distinct behaviors/capabilities the feature introduces
+- If the feature has **more than 15 distinct behaviors** or spans **4+ repos**, flag it: "Feature potencialmente grande — considerar quebra em sub-features antes de prosseguir."
+- This is a suggestion, not a blocker. The PO/dev decides whether to break it up.
+- If kept as-is, document the scope assessment in the PRD under "### Premissas".
+
+### 5. Locate the feature page
+
+Before generating questions or PRD, find the feature page:
+
+1. Search for an existing feature page in `Features/` matching the feature name/argument (created by /setup in Step 4.5)
+2. **If found**: use it (read existing content, detect previous Q&A rounds)
+3. **If NOT found**: the /setup may have failed to create it. Create it under `Features/` as fallback:
+   - Title: `{SIGLA}-NNN - Feature name` (next sequential number, using project sigla from projects.yml)
+   - Content: 1-2 paragraphs describing the feature (from PO documents or argument context)
+   - Label: `em-discovery`
+   - Log: "Feature page not found — created as fallback. Check if /setup ran correctly."
+4. The feature page is the SINGLE source of truth for this feature's discovery process
+
+### 6. Decision: questions or PRD?
+
+**IF there are business gaps (PO needs to answer):**
+
+Generate structured questions on the feature page in Confluence:
+
+```
+## Dúvidas & Decisões — Rodada N
+
+### Dúvida N.1: [short title]
+**Contexto:** [why this matters]
+**Opções:**
+- A) [option] — Trade-off: [pros/cons]
+- B) [option] — Trade-off: [pros/cons]
+- C) [option] — Trade-off: [pros/cons]
+**Recomendação:** [if you have one, with justification]
+**Resposta PO:** _aguardando_
+```
+
+Then:
+- Change feature label → `aguardando-po`
+- Notify Google Chat (if `GCHAT_WEBHOOK_URL` is not set, the script skips silently):
+
+      ./scripts/notify-gchat.sh --card \
+        --title "❓ Dúvidas aguardando PO" \
+        --subtitle "{project_name}" \
+        --body "<b>Feature:</b> {feature_name}
+
+      {question_count} dúvidas precisam de resposta antes de gerar o PRD." \
+        --next "PO responder as dúvidas no Confluence" \
+        --button-text "Responder no Confluence" \
+        --button-url "{feature_page_url}"
+
+  Replace `{}` placeholders with actual values. Notifications always in pt-BR.
+- STOP and wait for PO to respond
+
+**Timeout and escalation:** if the PO does not respond in a reasonable time, the dev can re-run /discovery on the same feature. The agent must detect previous questions (existing "Dúvidas & Decisões — Rodada N" section) and:
+- Check the page's `modified` field (via MCP). If the last modification was more than 3 business days ago and responses still contain "_aguardando_": escalate.
+- If there are pending responses but within the deadline: re-notify via Google Chat (same command as the previous step)
+- If more than 3 business days have passed: escalate to TL:
+
+      ./scripts/notify-gchat.sh --card \
+        --title "⚠️ Dúvidas sem resposta há {days} dias" \
+        --subtitle "{project_name}" \
+        --body "<b>Feature:</b> {feature_name}
+
+      Escalando ao TL. {pending_count} dúvidas pendentes bloqueiam o PRD." \
+        --next "TL intervir para desbloquear" \
+        --button-text "Ver dúvidas" \
+        --button-url "{feature_page_url}"
+
+**IF there are only technical gaps (team decides):**
+
+For architectural trade-offs, read `projects.yml` → `agents.principal`. If configured (not null), consult that agent to validate options. Document the decision in the PRD.
+
+**Fallback**: if `principal-engineer` agent is not available, document the options with trade-offs in the PRD and mark as "DECISÃO TÉCNICA — a validar com TL antes do /spec".
+
+After documenting technical decisions, **return to step 6** and re-evaluate: if no gaps remain, proceed to generate the full PRD.
+
+**IF no gaps remain (or all answered):**
+
+Generate the PRD on the feature page in Confluence:
+
+```
+## PRD
+
+### Resumo executivo
+[2-3 sentences: what, why, for whom]
+
+### Requisitos aceitos
+- REQ-01: [requirement from PO answers]
+- REQ-02: [requirement]
+- ...
+
+### Fora de escopo
+- [explicitly excluded items]
+
+### Premissas
+- [assumptions that were validated with PO]
+
+### Métricas de sucesso
+- [how to measure if this feature works]
+
+### Decisões tomadas
+- Duvida N.1: [decision] — Justificativa: [why]
+- ...
+```
+
+Then:
+- Change feature label → `prd-review`
+- Notify Google Chat:
+
+      ./scripts/notify-gchat.sh --card \
+        --title "📋 PRD pronto pra review" \
+        --subtitle "{project_name}" \
+        --body "<b>Feature:</b> {feature_name}
+
+      📊 <b>Métricas:</b>
+      • {req_count} requisitos aceitos
+      • {decision_count} decisões tomadas
+      • {out_of_scope_count} itens fora de escopo" \
+        --next "PO revisar e aprovar (label prd-aprovado)" \
+        --button-text "Revisar PRD" \
+        --button-url "{feature_page_url}"
+
+  Replace `{}` placeholders with actual values. Notifications always in pt-BR.
+
+### 7. Handle partial PO responses
+
+If the PO responded to SOME but not ALL questions:
+- Generate a NEW round of questions (Rodada N+1) containing ONLY the unanswered questions
+- Do NOT generate the PRD with open business gaps — every gap MUST be resolved first
+- Notify GChat: "{pending_count} dúvidas ainda pendentes na feature {name}"
+
+### 8. Handle PRD rejection
+
+If the PO adds label `prd-rejeitado` on the feature page:
+1. Read the rejection comments (page comments or inline notes)
+2. Identify what needs to change (new requirements? scope change? wrong assumptions?)
+3. Generate a new round of questions addressing the rejection reasons
+4. Change label → `aguardando-po`
+5. Notify GChat: "PRD da feature {name} rejeitado — nova rodada de dúvidas gerada"
+
+The flow returns to step 6 (questions loop) until the PO approves.
+
+**Escalation**: if the PRD is rejected 3 or more times, notify the TL (Tech Lead) via GChat:
+
+    ./scripts/notify-gchat.sh --card \
+      --title "⚠️ PRD rejeitado {rejection_count}x" \
+      --subtitle "{project_name}" \
+      --body "<b>Feature:</b> {feature_name}
+
+    PRD rejeitado {rejection_count} vezes. Possível desalinhamento entre PO e time técnico." \
+      --next "TL mediar entre PO e time" \
+      --button-text "Ver feature" \
+      --button-url "{feature_page_url}"
+
+### Label transition summary
+
+```
+(feature page created) → em-discovery → aguardando-po → prd-review → prd-aprovado (by PO)
+                                  ↑                          |
+                                  └── prd-rejeitado ─────────┘
+```
+
+**Who adds `prd-aprovado`**: the PO, manually, after reviewing the PRD. This is NOT automated — it's a human approval gate.
+
+## Agents used
+
+- Agent configured in `projects.yml` → `agents.principal` — to validate architectural trade-offs when technical gaps are found
+
+## MCP failure recovery
+
+If a Confluence operation fails mid-flow (publishing questions, updating PRD, changing labels):
+1. Log which operations succeeded and which failed
+2. Save pending operations to `docs/pending-confluence-updates.md` with: target page, content to add/update, operation type, date
+3. Report to dev: "Confluence indisponível — {N} operações pendentes salvas em docs/pending-confluence-updates.md."
+4. On re-execution, check if `docs/pending-confluence-updates.md` exists and attempt to apply pending operations FIRST before proceeding with new work. Remove applied entries from the file.
+
+## Rules
+
+1. NEVER invent business context — if you don't know, ask
+2. Questions must have options with trade-offs (never open-ended)
+3. Each question must explain WHY it matters (context)
+4. PRD requirements must be verifiable (not vague)
+5. **Language**: ALL generated content — Confluence pages AND local files — MUST be in **Brazilian Portuguese (pt-BR) with correct accents** (e.g., "não" NOT "nao", "autenticação" NOT "autenticacao", "código" NOT "codigo"). Technical terms stay in English (e.g., endpoint, status, token).
+6. Reference lessons from `docs/lessons/` when relevant
+7. Mark assumptions clearly as "PREMISSA" in the PRD
+8. **Cross-platform scripts**: when running `./scripts/notify-gchat.*`, detect the OS. On Windows use `powershell -ExecutionPolicy Bypass -File ./scripts/notify-gchat.ps1`, on Linux/macOS use `bash ./scripts/notify-gchat.sh`. Parameters are the same for both.
+
+## Validation checklist
+
+- [ ] All Confluence pages read (demand, domain, vision, glossário)
+- [ ] Spec repo context read (architecture, lessons, decisions, specs)
+- [ ] Existing code scanned (if repos exist)
+- [ ] Cross-validated with existing specs (no contradictions with scenarios/contracts of other features)
+- [ ] Glossary checked — new terms identified and listed for addition
+- [ ] Feature scope assessed (flagged if >15 behaviors or 4+ repos)
+- [ ] Gaps categorized as business or technical
+- [ ] Questions have options with trade-offs (not open-ended)
+- [ ] PRD has all sections (resumo, requisitos, fora de escopo, premissas, metricas)
+- [ ] Every REQ is verifiable (can be tested in a Given/When/Then scenario)
+- [ ] Feature label updated on Confluence
+- [ ] GChat notification sent
+- [ ] Figma context read (if configured) — design gaps identified and incorporated
+- [ ] No business context was invented
+
+## Exit gate (BLOCKING — cannot close the loop without these)
+
+The /discovery CANNOT be considered done until ALL of the following are true. If any item fails, fix it before proceeding.
+
+1. **Glossary updated on Confluence** — if the PRD section "GLOSSÁRIO: termos novos" lists any terms, they MUST be added to the Glossário page on Confluence BEFORE closing. Read the current page, add the terms, update. Do NOT leave this for /spec.
+2. **All "A CONFIRMAR" in Glossário resolved** — if any term in the Glossário still has "A CONFIRMAR" and the /discovery answered that question (e.g., PO confirmed enum values), update the Glossário to remove the "A CONFIRMAR" and replace with the confirmed value.
+3. **Decisions attributed correctly** — business decisions (scope, enums, features) marked as "PO". Technical decisions (cascade, notification rules, filtering) marked as "Dev". Never mix them.
+4. **architecture.md updated** — if the /discovery resolved any open decision listed in architecture.md, update the Status column from `aberta` to `resolvida — [decisão tomada]`. Do NOT leave stale "A CONFIRMAR" when the answer exists.