Req Discovery

Requirement Discovery

Analisar um sistema existente (qualquer linguagem ou arquitetura) e extrair requisitos funcionais e não-funcionais documentados em DDD e Clean Architecture.

IMPORTANTE: Este skill é de análise, não de implementação. Você pode navegar, ler código, capturar telas e investigar, mas NÃO deve alterar o sistema analisado.

Fluxo: o sistema fonte pode ser PHP/MVC, Go, Python, Java, monolito — qualquer coisa. A saída é sempre estruturada em Bounded Contexts, Entities, Value Objects e camadas Clean Architecture, pronta para ser implementada com os skills deste repositório (TypeScript, Kotlin ou C#). Consultar references/ddd-clean-mapping.md para o mapa completo.

Full-stack na análise: além do domínio/API, documentar quais superfícies o legado expõe (painel web, app mobile, só API) em delivery-inventory.md — isso alimenta req-ddd-modeling (seções Apresentação — Web/Mobile por BC), depois delivery-profile.md e req-agile-planning (subseções Telas e fluxos por US).

Entrada

O usuário deve fornecer uma das seguintes fontes:

Se o usuário não especificar, pergunte:

"Qual sistema você quer analisar? Me passe a URL (para web app) ou o caminho local (para codebase). Se tiver ambos, melhor ainda."

Workflow

Fase 1 — Reconhecimento

Se URL fornecida (análise via browser):

1. Navegar para a URL e capturar a tela inicial
2. Mapear navegação principal — menus, sidebar, breadcrumbs, links
3. Identificar telas/páginas — listar todas as rotas/views acessíveis
4. Para cada tela relevante:
   • Capturar screenshot
   • Listar elementos interativos (formulários, botões, tabelas, filtros)
   • Documentar campos de formulário (tipo, validação visível, obrigatoriedade)
   • Identificar ações disponíveis (CRUD, upload, export, etc.)
5. Mapear fluxos — sequências de telas que formam processos (ex.: cadastro → confirmação → dashboard)
6. Identificar perfis de acesso — se há login, roles visíveis, áreas restritas

Se caminho local fornecido (análise de código):

1. Escanear estrutura de diretórios — identificar padrão arquitetural (monolito, monorepo, microservices)
2. Identificar stack tecnológica — frameworks, linguagens, ORM, banco de dados
3. Mapear entidades/modelos — schemas de banco, entities, models
4. Mapear rotas/endpoints — controllers, routes, API definitions
5. Identificar regras de negócio — use cases, services, validators, domain logic
6. Mapear testes existentes — o que está coberto, o que revela sobre comportamento esperado
7. Identificar integrações — APIs externas, filas, webhooks, email, pagamento

Dicas por linguagem (sistema fonte) — onde encontrar conceitos que serão mapeados para DDD:

O sistema analisado pode seguir MVC, monolito, ou qualquer padrão. A tabela abaixo indica onde procurar no código-fonte os equivalentes que serão traduzidos para conceitos DDD na saída.

Tradução MVC → DDD (para sistemas que não seguem DDD):

A saída (requirements.md, ddd-analysis.md) é sempre em DDD/Clean Architecture, independente do padrão do sistema fonte. O objetivo é documentar o domínio para reimplementação usando os skills deste repositório.

Se ambos fornecidos:

• Executar ambas as análises
• Cruzar informações: telas do browser com endpoints do código
• Identificar funcionalidades no código que não aparecem na UI (APIs internas, jobs, etc.)

Fase 2 — Classificação

Organizar os achados em categorias:

1. Módulos/Domínios — agrupar funcionalidades por contexto de negócio
2. Requisitos Funcionais — o que o sistema faz (cada funcionalidade)
3. Requisitos Não-Funcionais — como o sistema faz (performance, segurança, UX)
4. Integrações — sistemas externos conectados
5. Regras de Negócio — validações, cálculos, fluxos condicionais
6. Perfis de Acesso — quem pode fazer o quê

Fase 3 — Análise DDD / Clean Architecture

Mapear os achados para conceitos de DDD e camadas da Clean Architecture:

3.1 — Identificar Bounded Contexts

Cada contexto é um limite de domínio autônomo. Sinais:

Cada Bounded Context identificado → 1 módulo no código → 1 Épico no planejamento.

3.2 — Mapear Entidades e Value Objects

Para cada Bounded Context:

┌──────────────────────────────────────┐
│ Bounded Context: <nome>              │
├──────────────────────────────────────┤
│ Entities (com identidade):           │
│   • Customer (id, name, email, ...)  │
│   • Order (id, items, total, ...)    │
│                                      │
│ Value Objects (sem identidade):      │
│   • Email (validação de formato)     │
│   • Money (valor + moeda)            │
│   • Address (rua, cidade, cep)       │
│                                      │
│ Aggregates:                          │
│   • Order → [OrderItem, Payment]     │
│                                      │
│ Domain Services:                     │
│   • PricingPolicy                    │
│   • ShippingCalculator               │
└──────────────────────────────────────┘

Critérios de classificação:

3.3 — Mapear Camadas de Aplicação

Para cada funcionalidade identificada, classificar por camada:

3.4 — Gerar Diagrama de Contexto

┌─────────────────────────────────────────────────┐
│                 CONTEXT MAP                     │
│                                                 │
│  ┌───────────┐         ┌───────────┐           │
│  │   Auth    │────────▶│  Billing  │           │
│  │ (upstream)│         │(downstream)│           │
│  └───────────┘         └───────────┘           │
│       │                                         │
│       ▼                                         │
│  ┌───────────┐         ┌───────────┐           │
│  │  Catalog  │◀───────▶│  Orders   │           │
│  │           │ shared  │           │           │
│  └───────────┘ kernel  └───────────┘           │
│                                                 │
│  Relações: ──▶ upstream/downstream              │
│             ◀──▶ shared kernel                  │
│             ···▶ conformist                     │
└─────────────────────────────────────────────────┘

Fase 3.5 — Inventário de entrega (superfícies UI/mobile)

Obrigatório quando o legado tiver painel web, telas PHP renderizadas ou app mobile — mesmo que a stack alvo ainda não esteja definida.

1. Listar módulos/telas web (menu, rotas .php, SPA) agrupados por área de negócio.
2. Listar apps mobile ou “campo/PDV” se existirem no legado ou no roadmap.
3. Marcar o que é somente API (integrações, cron, relatórios export).
4. Gerar delivery-inventory.md (template abaixo) — será copiado/resumido em planning/<projeto>/delivery-profile.md no req-agile-planning.

Se a análise for só codebase sem UI óbvia: inferir telas a partir de sistema/paginas/, views/, rotas web.php, menus no layout.

Fase 4 — Documentação

Gerar os artefatos de saída no diretório configurado (incluindo delivery-inventory.md quando houver UI/mobile).

Diretório de Saída

Os artefatos são salvos no diretório do projeto consumidor (não do repositório de skills):

<projectRoot>/
├── <docsPath>/                          ← configurável via skills.config.json
│   └── discovery/
│       └── <nome-do-sistema>/           ← kebab-case do nome do sistema
│           ├── requirements.md          ← requisitos funcionais/não-funcionais (obrigatório)
│           ├── ddd-analysis.md          ← bounded contexts, entities, VOs, camadas (obrigatório)
│           ├── screens.md               ← mapeamento de telas (se via browser)
│           ├── delivery-inventory.md    ← superfícies web/mobile/API por área (obrigatório se houver UI)
│           └── domain-model.md          ← modelo de domínio detalhado (se via código)

Resolução do caminho

O docsPath é resolvido pela precedência:

1. Argumento explícito do usuário: "salve em docs/analise"
2. skills.config.json → defaults.docsPath (ex.: "docs")
3. skills.config.local.json → override local
4. Fallback: docs

Exemplo concreto — se o sistema se chama "meu-erp" e docsPath = "docs":

meu-projeto/
├── docs/
│   └── discovery/
│       └── meu-erp/
│           ├── requirements.md
│           ├── screens.md
│           └── domain-model.md
├── apps/
├── packages/
└── ...

Se o diretório <docsPath>/discovery/ não existir, crie-o automaticamente.

Artefatos de Saída

requirements.md (obrigatório)

Registro de Regras de Negócio (Desacoplado)

Documente regras de negócio de forma independente dos requisitos funcionais, facilitando validação, reutilização e controle de mudanças:

Regras de preenchimento:

• Registre a fonte da regra (política, norma, área) para facilitar resolução de conflitos
• Se uma regra substituir outra, preserve o histórico e a vigência
• Valide limites, faixas e exceções com exemplos numéricos
• Não confunda regra de negócio com interface ou implementação
• Toda regra deve ter um validador com autoridade para alterá-la

Registro de Dúvidas e Pendências (Matriz de Controle)

Sempre que houver lacunas, dúvidas ou validações pendentes durante a análise, registre-as na seguinte matriz para garantir rastreabilidade e ação:

Regras de preenchimento:

• Toda pendência crítica deve aparecer em reuniões de acompanhamento
• Feche o item somente com resposta, decisão ou evidência documentada
• Use o impacto para priorizar cobranças e decisões
• Relacione a pendência aos requisitos afetados (ex: REQ-XXX)

# Requisitos — <Nome do Sistema>

**Fonte**: <URL e/ou caminho local>
**Data da análise**: <data>
**Método**: <browser / código / combinado>

## Visão Geral

<Resumo do sistema em 2-3 parágrafos: propósito, público-alvo, principais funcionalidades>

## Stack Tecnológica

| Camada         | Tecnologia |
| -------------- | ---------- |
| Frontend       | ...        |
| Backend        | ...        |
| Banco de Dados | ...        |
| Infra          | ...        |

## Módulos Identificados

### <Módulo 1>

**Descrição**: <o que este módulo faz>

#### Requisitos Funcionais

- **RF-001**: <descrição clara da funcionalidade>
  - Tela/Endpoint: <referência>
  - Campos: <se formulário, listar campos>
  - Validações: <regras identificadas>
  - Ações: <o que acontece>

#### Regras de Negócio

- **RN-001**: <descrição da regra>

### <Módulo 2>

...

## Requisitos Não-Funcionais

- **RNF-001**: <descrição> (ex.: autenticação JWT, rate limiting, etc.)

## Integrações

| Sistema | Tipo                     | Descrição |
| ------- | ------------------------ | --------- |
| ...     | API REST / Webhook / ... | ...       |

## Perfis de Acesso

| Perfil  | Permissões |
| ------- | ---------- |
| Admin   | ...        |
| Usuário | ...        |

## Fluxos Principais

### <Fluxo 1>: <nome>

Tela A → Ação → Tela B → Confirmação → Tela C

<descrição do fluxo>

## Lacunas e Observações

- <funcionalidade sem teste>
- <endpoint sem documentação>
- <comportamento ambíguo>

delivery-inventory.md (obrigatório se legado tiver UI web e/ou mobile)

# Inventário de entrega — <Nome do Sistema>

**Fonte**: discovery <data>
**Legado**: <URL ou path>

## Resumo

| Superfície | Presente no legado? | Observação |
|------------|-------------------|------------|
| Painel web admin | Sim/Não | ex.: PHP `sistema/` |
| App mobile / PDV campo | Sim/Não | |
| API/integrações only | Sim/Não | |

## Telas web por área de negócio

| Área (≈ BC futuro) | Telas / rotas principais | CRUD? | Relatórios? |
|--------------------|--------------------------|-------|-------------|
| Auth | login, usuários, permissões | | |
| Vendas | PDV, abertura caixa | | |

## Mobile (se aplicável)

| Fluxo | Telas | Paridade MVP? |
|-------|-------|---------------|
| Perfil | login, home | Sim/Não |

## Próximo passo

→ `req-ddd-modeling` deve espelhar colunas **API | Web | Mobile** por BC.
→ `req-agile-planning` cria `planning/<projeto>/delivery-profile.md` antes do `backlog.md`.

screens.md (quando análise via browser)

# Mapeamento de Telas — <Nome do Sistema>

## <Tela 1>: <nome/rota>

**URL**: <url completa>
**Tipo**: dashboard / formulário / listagem / detalhe / ...

### Elementos

- <elemento 1>: <tipo> — <descrição>
- <elemento 2>: <tipo> — <descrição>

### Ações Disponíveis

- <ação 1>: <o que faz> → <para onde vai>

ddd-analysis.md (obrigatório — análise DDD/Clean Architecture)

# Análise DDD / Clean Architecture — <Nome do Sistema>

**Baseado em**: <fonte dos requisitos>
**Data da análise**: <data>

## Context Map

<diagrama ASCII do mapa de contextos com relações upstream/downstream>

## Bounded Contexts

### BC-001: <Nome do Contexto>

**Descrição**: <propósito deste contexto>
**Relação**: upstream de BC-002 / downstream de BC-003 / shared kernel com BC-004

#### Entities

| Entity   | Atributos Principais    | Aggregate Root?         |
| -------- | ----------------------- | ----------------------- |
| Customer | id, name, email, status | Sim                     |
| Address  | id, street, city, zip   | Não (child de Customer) |

#### Value Objects

| VO           | Tipo            | Validação                |
| ------------ | --------------- | ------------------------ |
| Email        | string          | formato email, lowercase |
| Money        | number + string | valor >= 0, moeda ISO    |
| CustomerName | string          | não vazio, max 100 chars |

#### Domain Services

| Service       | Regra                              |
| ------------- | ---------------------------------- |
| PricingPolicy | Calcula desconto baseado em volume |

#### Repository Ports

| Repository         | Operações                                     |
| ------------------ | --------------------------------------------- |
| CustomerRepository | create, findById, findByEmail, update, delete |

#### Use Cases

| Use Case         | Tipo    | Descrição                            |
| ---------------- | ------- | ------------------------------------ |
| CreateCustomer   | comando | Cadastra novo cliente com validações |
| FindCustomerById | query   | Busca cliente por ID                 |
| ListCustomers    | query   | Lista paginada com filtros           |

#### DTOs

| DTO                 | Direção | Campos                     |
| ------------------- | ------- | -------------------------- |
| CreateCustomerInDTO | entrada | name, email, address       |
| CustomerOutDTO      | saída   | id, name, email, createdAt |

#### Controllers/Endpoints

| Verbo | Rota               | Use Case         |
| ----- | ------------------ | ---------------- |
| POST  | /api/customers     | CreateCustomer   |
| GET   | /api/customers/:id | FindCustomerById |
| GET   | /api/customers     | ListCustomers    |

### BC-002: <Nome do Contexto>

...

## Mapeamento de Camadas (Clean Architecture)

| Camada         | Artefatos Identificados                          | Skill Agnóstico                                                      |
| -------------- | ------------------------------------------------ | -------------------------------------------------------------------- |
| Domain         | Entities, VOs, Domain Services, Repository ports | core-entity, core-value-object, core-domain-service, core-repository |
| Application    | Use Cases, DTOs, Queries                         | core-use-case, core-dto, core-query-cqrs                             |
| Infrastructure | Adapters de persistência, integrações            | backend-prisma-data / backend-data-kt / backend-data-cs              |
| Interface      | Controllers, Forms                               | backend-controller / backend-controller-cs / frontend-form-schema    |

## Dependências entre Contexts

| De     | Para    | Tipo                | Dados Compartilhados   |
| ------ | ------- | ------------------- | ---------------------- |
| Orders | Auth    | upstream/downstream | userId                 |
| Orders | Catalog | shared kernel       | productId, productName |

## Recomendações Arquiteturais

- <recomendação 1>
- <recomendação 2>

domain-model.md (quando análise de código — detalhamento técnico)

# Modelo de Domínio — <Nome do Sistema>

## Entidades por Bounded Context

### BC-001: <Nome>

#### <Entidade 1>

- campo1: tipo (obrigatório) → candidato a VO: sim/não
- campo2: tipo (opcional) → candidato a VO: sim/não
- Relações: <relação com outras entidades>
- Aggregate Root: sim/não
- Regras de negócio internas: <lista>

## Diagrama de Aggregates

<diagrama ASCII dos aggregates com entities raiz e filhas>

## Mapeamento Entity ↔ Tabela/Collection

| Entity   | Tabela/Collection | Observações     |
| -------- | ----------------- | --------------- |
| Customer | customers         | -               |
| Order    | orders            | FK: customer_id |

Visualização

Use diagramas ASCII extensivamente durante a análise:

┌─────────────────────────────────────────┐
│           ARQUITETURA GERAL            │
├─────────────────────────────────────────┤
│                                         │
│  ┌─────────┐    ┌─────────┐            │
│  │ Frontend │───▶│ Backend │            │
│  │ Next.js  │    │ NestJS  │            │
│  └─────────┘    └────┬────┘            │
│                      │                  │
│                 ┌────▼────┐            │
│                 │   DB    │            │
│                 │ Postgres│            │
│                 └─────────┘            │
│                                         │
└─────────────────────────────────────────┘

Integração com Outros Skills

Pipeline completo

Sistema fonte            req-discovery       req-ddd-modeling          req-migration-strategy   delivery-profile.md      req-agile-planning
(qualquer linguagem) →   (leitura) →         (modelagem DDD) →        [opcional]         →   (stack+superfícies) →   (backlog full-stack)
                         requirements.md     ddd-strategic-model.md   migration-strategy.md  planning/*/              backlog.md
                         delivery-inventory  ddd-tactical-model.md    acl-design.md          delivery-profile.md      + openspec-propose/apply
                         ddd-analysis.md     (+ superfícies/BC)                                epics-summary.md         + core/frontend/mobile/*
                         screens.md
                         domain-model.md

O sistema fonte é apenas lido. A saída é sempre DDD/Clean Architecture. A implementação usa os skills deste repositório (TS, KT, CS + frontend/mobile).

Próximos passos após discovery

Tasks → Skills deste repositório

• TypeScript: skills sem sufixo → NestJS + Prisma
• Kotlin: skills -kt → Spring Boot + JPA
• C#: skills -cs → ASP.NET Core + EF Core
• Frontend: -angular / -vue com entity → usecase → repository → page/form
• Mobile: -flutter / -android com entity → usecase → repository → screen/form

Consultar references/ddd-clean-mapping.md.

Ofereça essas opções ao finalizar:

"Análise concluída! Artefatos: requirements.md, ddd-analysis.md, delivery-inventory.md (se houver UI). Próximos passos:

1. Aprofundar modelagem DDD (req-ddd-modeling)
2. [Se legado] Definir estratégia de migração (req-migration-strategy)
3. Gerar backlog com docker/cicd no bootstrap (req-agile-planning)
4. Criar projeto full-stack (config-project-fullstack + openspec-propose \"bootstrap-<nome>\")"

Guardrails

• Não altere o sistema analisado — apenas observe e documente
• Não invente requisitos — documente apenas o que foi observado ou inferido do código
• Marque inferências — quando um requisito é inferido (não explícito), indique com [inferido]
• Marque lacunas — funcionalidades ambíguas devem ser listadas como "Observações"
• Peça credenciais se necessário — se o sistema requer login, pergunte ao usuário
• Respeite limites — não tente acessar áreas que requerem credenciais não fornecidas
• Seja factual — descreva o que o sistema faz, não o que deveria fazer

Global Standards

• Consultar ../skills-standards.md para padroes globais de nomenclatura e convencoes gerais entre skills.

References

Templates de Análise de Requisitos (Luiza Silva)

Consultar ../references/templates-luiza-silva.md para os formatos exatos dos seguintes templates:

• T01: Roteiro de Entrevista com Stakeholders → Usar ANTES de iniciar o levantamento, para preparar conversas estruturadas com stakeholders.
• T02: Ata de Reunião de Levantamento → Usar LOGO APÓS reuniões para criar memória objetiva e reduzir interpretações divergentes.
• T03: Ficha Individual de Requisito → Usar para requisitos complexos ou críticos que precisam ser rastreáveis, revisáveis e testáveis.
• T05: Registro de Regra de Negócio → Usar para documentar políticas, condições, limites ou cálculos de forma independente dos requisitos funcionais.
• T07: Registro de Dúvidas e Pendências → Usar DURANTE TODO o ciclo de discovery para controlar itens que impedem confirmação ou avanço.

Instruções de Uso

Ao gerar documentação de saída (requirements.md, ddd-analysis.md, screens.md):

1. Utilize o formato T03 para requisitos críticos identificados durante a análise.
2. Utilize o formato T05 para cada regra de negócio extraída do código ou entrevistas.
3. Utilize o formato T07 para toda lacuna, dúvida ou pendência encontrada durante o discovery.
4. Se houver reuniões de levantamento, gere atas no formato T02.
5. Antes de entrevistas, prepare roteiros no formato T01.

Regra Prática

Template bom é o que ajuda o time a pensar, comunicar e decidir melhor. Se um campo não agrega valor, adapte ou remova conforme o contexto do projeto.