# PRD — Project Intelligence Layer
## Rastreabilidade
- Orquestração: Project Intelligence Layer
- Slug: project-intelligence-layer
- Origem: docs/project-intelligence-layer/01-idea.md
- Estado atual: approved
- Decisão humana anterior: direção aprovada em 2026-06-08.
- Próximo checkpoint: aprovação deste PRD antes da Tech Spec.
- Fonte canônica local: docs/project-intelligence-layer/traceability-map.yaml
## Resumo
Construir uma camada de inteligência evolutiva para o SDD que garanta que toda ideia, planejamento, execução e review considere o contexto máximo disponível do projeto sem transformar memória derivada em fonte de verdade.
A solução introduz três capacidades principais:
- **Ingestão rastreável:** extrair aprendizados de artefatos canônicos, ADRs, reviews, memórias e sinais `.sdd`.
- **Context Pack obrigatório:** montar contexto curto, auditável e específico antes de cada etapa SDD.
- **Saúde evolutiva:** revelar padrões recorrentes, riscos, conflitos, lacunas de rastreabilidade e oportunidades de promover conhecimento para docs, rules ou skills.
O núcleo deve funcionar com Markdown, YAML, JSONL, CLI `sdd` e validação local. Busca semântica, embeddings, vector DB, MCP e integrações externas são aceleradores opcionais, não dependências do contrato.
## Objetivos
- Garantir que cada etapa SDD comece com contexto relevante, rastreável e atualizado.
- Unificar a leitura de artefatos históricos sem duplicar conteúdo entre sistemas.
- Preservar `docs/<slug-da-orquestracao>/` como fonte canônica quando não houver sistema externo confiável.
- Tratar `.sdd/memory/learnings.jsonl` e futuros índices como cache derivado e reconstruível.
- Reduzir redescoberta de decisões, padrões e riscos já documentados.
- Detectar conflitos entre artefatos antes de etapas de alto impacto.
- Criar base para melhoria contínua da saúde do projeto.
- Manter compatibilidade com qualquer provider/modelo/client que consiga operar com Markdown, arquivos e comandos `sdd`.
## Não objetivos
- Não criar uma base paralela que substitua PRD, Tech Spec, ADR, Review ou Memory.
- Não depender de vector DB, embeddings ou API externa para o MVP.
- Não exigir MCP, browser, subagents ou ferramenta visual para o comportamento essencial.
- Não copiar documentos inteiros para índices derivados.
- Não promover automaticamente aprendizados para rules, skills ou AGENTS sem checkpoint humano.
- Não implementar dashboard visual no primeiro corte.
- Não resolver integrações Jira, Confluence, GitHub, GitLab ou Bitbucket além de guardar ponteiros canônicos quando existirem.
## Usuários
- **Lead humano do SDD:** precisa aprovar decisões com evidência e ver se o projeto está ficando mais saudável.
- **Agente de planejamento:** precisa criar Idea, PRD, Tech Spec e Tasks com base no histórico real.
- **Agente executor:** precisa saber decisões, limites, comandos e riscos antes de alterar código.
- **Agente reviewer:** precisa relacionar diffs a critérios de aceite, ADRs, riscos e padrões já existentes.
- **Mantenedor da camada SDD:** precisa evoluir comandos, schemas e skills sem quebrar provider-compatibility.
- **Projeto instalado:** precisa operar com fallback local quando integrações externas estiverem ausentes ou parciais.
## Requisitos
### RF-01 — Inventário de fontes canônicas
O SDD deve conseguir inventariar fontes relevantes do projeto:
- `AGENTS.md`, `CLAUDE.md` e rules instaladas;
- `sdd.config.yaml`;
- `docs/<slug-da-orquestracao>/traceability-map.yaml`;
- artefatos SDD por etapa;
- ADRs;
- reviews;
- memórias finais;
- diretórios `docs/_project-intelligence/`, quando existirem;
- eventos locais `.sdd/*.jsonl`, quando seguros e úteis;
- manifests e comandos conhecidos do projeto, quando o stage exigir contexto operacional.
### RF-02 — Índices derivados reconstruíveis
O SDD deve armazenar learnings em JSONL derivado, com no mínimo:
- tipo do aprendizado;
- resumo curto;
- origem da orquestração;
- estágio de origem;
- `source_artifact`;
- `source_hash`;
- tags;
- confiança;
- estado (`active`, `stale`, `superseded`, `conflict`);
- timestamp de aprendizado;
- marcação `derived: true`.
### RF-03 — Context Pack por etapa
Antes de gerar ou executar uma etapa principal, o SDD deve produzir um Context Pack específico para o stage:
- `/idea`: contexto de produto, histórico de features similares, riscos e objetivos recorrentes;
- `/prd`: decisões de produto, usuários, métricas e critérios já usados;
- `/techspec`: ADRs, padrões de arquitetura, contratos, áreas do código e riscos técnicos;
- `/tasks`: plano técnico aprovado, dependências, DoD, prompts agent e comandos prováveis;
- `/execution`: task atual, escopo permitido, arquivos prováveis, padrões, riscos e validação;
- `/review`: critérios de aceite, diffs, evidências, riscos e padrões de review;
- `/memory`: decisões finais, pendências, padrões úteis e ponteiros canônicos.
### RF-04 — Manifesto de contexto
Todo Context Pack deve incluir um manifesto auditável com:
- fontes consideradas;
- fontes incluídas;
- fontes excluídas e motivo;
- fontes obsoletas por hash;
- conflitos detectados;
- limite de tamanho aplicado;
- comandos ou validações recomendadas.
### RF-05 — Precedência de verdade
Quando houver conflito, a camada deve aplicar precedência explícita:
1. ADR aprovada;
2. Tech Spec aprovada;
3. PRD aprovado;
4. Tasks registradas;
5. Execution e Review;
6. Memory final;
7. índice derivado.
Quando a precedência não resolver, o Context Pack deve marcar conflito e exigir checkpoint antes da próxima etapa crítica.
### RF-06 — Redação de segredos
Todo índice, Context Pack, evento e relatório deve passar pelo redactor central antes de persistir conteúdo derivado.
### RF-07 — Health signals
O SDD deve calcular sinais mínimos de saúde:
- orquestrações sem memória final;
- artefatos obrigatórios ausentes;
- PRDs ou Tech Specs sem validação;
- ADRs ausentes após decisões arquiteturais;
- riscos recorrentes sem mitigação;
- reviews com achados repetidos;
- comandos de validação recorrentes;
- padrões úteis ainda não promovidos;
- fontes derivadas `stale` por mudança de hash.
### RF-08 — Promoção com checkpoint
Learnings recorrentes podem sugerir atualizações em:
- `docs/_project-intelligence/project-profile.md`;
- `docs/_project-intelligence/architecture-map.md`;
- `docs/_project-intelligence/decision-index.md`;
- `docs/_project-intelligence/patterns-and-conventions.md`;
- `docs/_project-intelligence/risk-register.md`;
- `docs/_project-intelligence/quality-health.md`;
- `.agents/skills/*`;
- rules de clients.
Nenhuma promoção deve ser aplicada sem checkpoint humano explícito.
### RF-09 — Provider compatibility
O MVP deve funcionar com:
- Markdown;
- YAML;
- JSONL;
- comandos `sdd`;
- validação local;
- artifact store local.
Busca semântica, embeddings, vector DB, MCP, browser, subagents e screenshots devem ser opcionais.
### RF-10 — Comandos propostos
O MVP deve introduzir ou evoluir comandos determinísticos:
```bash
sdd context build --name "<orquestracao>" --stage <stage>
sdd intelligence learn --name "<orquestracao>"
sdd intelligence status --json
sdd intelligence health --json
```
Se for melhor para compatibilidade inicial, `sdd memory learn` pode ser preservado como alias ou base do `sdd intelligence learn`.
## Critérios de aceite
```gherkin
Funcionalidade: Context Pack obrigatório
Cenário: Gerar contexto para Tech Spec
Dado que existe uma orquestração com Idea e PRD salvos em docs/project-intelligence-layer
Quando eu executar sdd context build --name "Project Intelligence Layer" --stage techspec
Então o SDD deve gerar um Context Pack com origem, fontes incluídas, decisões relevantes, riscos e próximo artefato esperado
E o pacote deve citar os caminhos dos artefatos usados
```
```gherkin
Funcionalidade: Índice derivado reconstruível
Cenário: Aprender a partir dos artefatos locais
Dado que existem artefatos em docs/project-intelligence-layer
Quando eu executar sdd intelligence learn --name "Project Intelligence Layer"
Então o SDD deve escrever registros JSONL derivados com source_artifact e source_hash
E nenhum registro deve ser tratado como fonte canônica
```
```gherkin
Funcionalidade: Detecção de obsolescência
Cenário: Artefato muda depois de indexado
Dado que um aprendizado possui source_hash calculado
Quando o arquivo de origem for alterado
Então o status do aprendizado deve ser marcado como stale ou reprocessado
E o Context Pack deve evitar usar esse aprendizado como verdade confirmada
```
```gherkin
Funcionalidade: Precedência entre fontes
Cenário: Memory contradiz ADR aprovada
Dado que uma Memory final contradiz uma ADR aprovada
Quando eu gerar um Context Pack para execução
Então a ADR deve ter precedência
E o conflito deve aparecer no manifesto de contexto
```
```gherkin
Funcionalidade: Operação provider-neutral
Cenário: Rodar sem vector DB ou MCP
Dado que o projeto está em modo local/offline
Quando eu executar intelligence learn e context build
Então o fluxo deve funcionar usando apenas arquivos locais, JSONL, YAML, Markdown e o CLI sdd
```
## Métricas
- Percentual de etapas com Context Pack gerado antes da produção do artefato.
- Número de fontes canônicas consideradas por Context Pack.
- Número de conflitos detectados antes de Tech Spec, Execution ou Review.
- Número de aprendizados marcados como `stale` e reprocessados.
- Redução de achados repetidos em reviews.
- Percentual de orquestrações com `08-memory.md` salvo.
- Número de padrões promovidos para docs/rules/skills após checkpoint humano.
- Tempo médio para um agente localizar comandos, decisões e riscos relevantes.
## Riscos
- **Escopo amplo demais:** tentar entregar busca semântica, health, promoção de rules e contexto perfeito no primeiro corte. Mitigação: começar com inventário, JSONL e Context Pack determinístico.
- **Segunda fonte de verdade:** índices derivados podem ser confundidos com documentação canônica. Mitigação: campo `derived: true`, precedência explícita e documentação clara.
- **Contexto excessivo:** pacotes grandes podem piorar a resposta do modelo. Mitigação: ranking por stage, manifesto de exclusões e limite de tamanho.
- **Conflitos silenciosos:** artefatos antigos podem contradizer decisões recentes. Mitigação: hashes, status `stale` e precedência.
- **Vazamento de segredo:** eventos e logs podem conter tokens. Mitigação: redactor central obrigatório antes de persistir derivados.
- **Dependência de provider específico:** recursos avançados podem quebrar portabilidade. Mitigação: núcleo baseado em arquivos e CLI.
## Diagramas
```mermaid
flowchart TD
A["Artefatos canônicos em docs/<slug>/"] --> B["Ingestão intelligence learn"]
C["Traceability map"] --> B
D["ADRs, reviews e memory"] --> B
E["Eventos .sdd seguros"] --> B
B --> F["Índices derivados JSONL"]
F --> G["Context build por stage"]
A --> G
C --> G
G --> H["Context Pack auditável"]
H --> I["Agente SDD gera ou executa etapa"]
I --> J["Novo artefato salvo"]
J --> A
```
```mermaid
flowchart LR
ADR["ADR aprovada"] --> P["Precedência"]
TS["Tech Spec aprovada"] --> P
PRD["PRD aprovado"] --> P
MEM["Memory final"] --> P
IDX["Índice derivado"] --> P
P --> OK["Fonte escolhida"]
P --> C["Conflito para checkpoint"]
```