# PRD — SDD CLI (TUI)

**Etapa:** 2 — Product Requirements (PRD) · **Data:** 2026-06-06 · **Estado:** draft

---

## Resumo

O SDD CLI (TUI) é um modo interativo do binário `sdd` que transforma o terminal em um cockpit determinístico para conduzir o fluxo Spec-Driven completo, de ponta a ponta, sem depender de nenhum agente ou editor externo. A TUI orquestra etapas, apresenta checkpoints humanos explícitos, exibe loaders durante operações de filesystem e execução de subcomandos, renderiza artefatos Markdown inline e persiste tudo em `docs/<slug>/` + `traceability-map.yaml`.

O produto é voltado ao engenheiro que trabalha diretamente no terminal — seja por preferência, por ambiente sem GUI, por não ter licença de Claude Code, ou por querer conduzir revisões e aprovações do fluxo SDD sem sair do shell. A geração de conteúdo dos artefatos permanece responsabilidade do scaffolding determinístico dos subcomandos `sdd` existentes e, opcionalmente, de um agente externo — a TUI não embarca IA nem chama providers de IA por HTTP.

---

## Objetivos

- **OBJ-1:** Disponibilizar `sdd tui` como ponto de entrada de uma TUI interativa, com tempo de abertura até a primeira tela útil inferior a 1 segundo.
- **OBJ-2:** Guiar o usuário pelo fluxo completo (Ideia → PRD → Tech Spec → Tasks → Refinement opcional → Execution → Review → Memory) com visibilidade de estado, etapa atual e artefatos aprovados.
- **OBJ-3:** Exibir loaders a cada operação com duração perceptível (filesystem, subcomando `sdd`), sem deixar espera longa sem feedback por mais de 200ms.
- **OBJ-4:** Implementar checkpoints humanos explícitos (Aprovar / Regenerar / Editar via `$EDITOR`) para PRD, Tech Spec, Refinement e Merge/Deploy, bloqueando avanço sem aprovação.
- **OBJ-5:** Renderizar artefatos Markdown inline no terminal, sem editor externo para visualização.
- **OBJ-6:** Persistir artefatos aprovados em `docs/<slug>/` e atualizar `traceability-map.yaml` com contrato idêntico ao harness.
- **OBJ-7:** Rodar sem regressão em macOS e Linux (iTerm2, Terminal.app, alacritty, kitty, tmux).

---

## Não objetivos

- **NO-1:** A TUI **não embarca IA**, não chama providers por HTTP e não replica prompts dos subagents. Geração de conteúdo é delegada ao scaffolding `sdd` ou a agente externo. Decisão travada.
- **NO-2:** Não substitui o harness para usuários com Claude Code/Codex.
- **NO-3:** Editor inline completo de artefatos (suporte só via `$EDITOR`).
- **NO-4:** Diff visual entre versões.
- **NO-5:** Agent Teams paralelos conduzidos pela TUI.
- **NO-6:** Integrações externas (Jira/Confluence/Bitbucket) operadas pela TUI (exibir links é permitido; ações remotas não).
- **NO-7:** Seletor de provider na TUI.
- **NO-8:** Windows no MVP.
- **NO-9:** Instalador empacotado / package manager no MVP.

---

## Usuários

### Persona primária — Engenheiro solo / tech lead no terminal
Usa o terminal como ambiente principal (scripts, CI interativo, SSH, sem GUI). Confortável com TUIs (`lazygit`, `k9s`, `htop`). Quer conduzir o fluxo SDD, revisar e aprovar artefatos e navegar entre etapas com contexto, sem abrir editor/agente. Dor atual: subcomandos isolados, sem visibilidade de estado/progresso.

### Persona secundária — Dev em projetos pessoais / OSS
Sem licença de Claude Code ou sem querer depender de agente pago. Quer experiência guiada e gratuita do fluxo SDD. Dor atual: CLI opaca para quem não memoriza subcomandos.

---

## Requisitos

### Requisitos Funcionais

**RF-01 — Entrada `sdd tui`.** O binário inicializa a TUI ao receber `sdd tui`. **RN-01:** sem instalação SDD detectável (`.sdd/`/`sdd.config.yaml`), exibe aviso com instrução `sdd init` antes de permitir criar orquestração. (Ver R-08: `sdd` sem subcomando mantém comportamento atual de ajuda; entrada da TUI é exclusivamente `sdd tui`.)

**RF-02 — Tela de orquestrações.** Lista orquestrações de `docs/` com nome, slug, estado e etapa corrente. **RN-02:** estado lido do `traceability-map.yaml`; ausente → `unknown`. Ações: selecionar, criar nova, sair.

**RF-03 — Criação de orquestração.** Campo de texto para a ideia em linguagem natural; ao confirmar executa `sdd init "<ideia>"`. **RN-03:** slug com a mesma normalização do `sdd init` atual.

**RF-04 — Navegação por etapas com estado.** Painel de progresso com todas as etapas e estado (pending/in_progress/approved/skipped). Navegação livre para etapas anteriores/aprovadas; etapas futuras não aprovadas bloqueadas. **RN-04:** estado derivado do `traceability-map.yaml`.

**RF-05 — Loaders dinâmicos.** Toda operação perceptível exibe spinner com descrição. **RN-05:** loader aparece em até 200ms; operações < 200ms podem não exibir loader (evita flash).

**RF-06 — Execução de etapa via subcomando `sdd`.** A TUI invoca o subcomando correspondente (`sdd idea`/`prd`/...), captura stdout/stderr, exibe resultado. **RN-06:** a TUI não replica a lógica de geração — é orquestrador de processos.

**RF-07 — Viewer Markdown inline.** Renderiza o `.md` gerado (cabeçalhos, negrito/itálico, listas, código, tabelas) com scroll.

**RF-08 — Checkpoint de aprovação.** Painel com Aprovar / Regenerar / Editar (`$EDITOR`, fallback `vi`). **RN-07:** Aprovar disponível após exibição integral (relaxável por config). **RN-08:** checkpoints PRD/Tech Spec/Refinement/Merge obrigatórios; intermediários (Tasks/Execution/Review) podem ser auto-aprovação por config.

**RF-09 — Persistência de artefato aprovado.** Grava em `docs/<slug>/` (ex.: `02-prd.md`) e atualiza `state: approved` + `approved_at` (ISO-8601) no `traceability-map.yaml`. **RN-09:** schema e contrato idênticos ao harness.

**RF-10 — Atalhos de teclado.** `q`/`Ctrl+C` sair; `Enter` confirmar; `Esc` voltar; `↑/↓/j/k` navegar/scroll; `a` aprovar; `r` regenerar; `e` editar; `?` ajuda.

**RF-11 — Degradação sem suporte a TUI.** Sem TTY, `TERM=dumb` ou stdout redirecionado → não inicia, mensagem clara, exit não-zero, sem corromper terminal. **RN-10:** detecção antes de qualquer renderização; sugere subcomandos individuais.

**RF-12 — Ajuda contextual.** `?` exibe atalhos do contexto atual.

**RF-13 — Estado de erro e recuperação.** Subcomando com exit não-zero → painel de erro com stderr; opções Tentar novamente / Editar configuração; não avança. **RN-11:** erros não sobrescrevem artefatos aprovados.

**RF-14 — Refinement condicional.** Exibida como opcional; a TUI pergunta antes de Tasks→Execution; resposta registrada (`skipped`/`pending`).

**RF-15 — Resumo final.** Após Memory, tela de resumo: nome, slug, artefatos aprovados com caminhos e timestamps.

### Requisitos Não Funcionais

- **RNF-01 — Inicialização:** `sdd tui` → primeira tela útil < 1s em hardware típico.
- **RNF-02 — Responsividade:** adapta a SIGWINCH sem corromper nem travar.
- **RNF-03 — Compatibilidade:** iTerm2, Terminal.app, alacritty, kitty, tmux, screen, em macOS e Linux.
- **RNF-04 — Tamanho do binário:** acréscimo ≤ 5 MB em release com `strip = true`.
- **RNF-05 — Sem regressão:** subcomandos existentes mantêm stdout/stderr/exit code.
- **RNF-06 — Escrita atômica:** gravação write-then-rename.
- **RNF-07 — Acessibilidade:** uso só por teclado; contraste para fundo claro/escuro.
- **RNF-08 — Sem rede:** a TUI não faz chamadas de rede; toda comunicação externa via subcomandos filhos.

---

## Critérios de aceite

### CA-RF01 — Entrada na TUI
```gherkin
Cenário: Abrir TUI em projeto SDD configurado
  Dado que o diretório corrente contém sdd.config.yaml ou .sdd/
  Quando o usuário executa "sdd tui"
  Então a TUI inicia e a tela de orquestrações é renderizada em menos de 1 segundo

Cenário: Abrir TUI sem instalação SDD
  Dado que o diretório não contém sdd.config.yaml nem .sdd/
  Quando o usuário executa "sdd tui"
  Então a TUI exibe "Instalação SDD não encontrada. Execute sdd init."
  E não permite criar orquestração até a instalação ser detectada
```

### CA-RF02 — Tela de orquestrações
```gherkin
Cenário: Listar orquestrações existentes
  Dado que existem diretórios em docs/ com traceability-map.yaml
  Quando a tela de orquestrações é exibida
  Então cada orquestração aparece com nome, slug, estado e etapa corrente

Cenário: Orquestração sem traceability-map.yaml
  Dado um diretório em docs/ sem traceability-map.yaml
  Quando a tela é exibida
  Então a orquestração é listada com estado "unknown"
```

### CA-RF05 — Loaders
```gherkin
Cenário: Loader durante execução de subcomando
  Dado que o usuário iniciou uma etapa do fluxo
  Quando o subcomando sdd está em execução
  Então um spinner com descrição aparece em até 200ms e permanece até concluir

Cenário: Operação rápida não pisca loader
  Dado uma operação de filesystem
  Quando ela conclui em menos de 200ms
  Então o spinner não é exibido
```

### CA-RF08 — Checkpoint
```gherkin
Cenário: Aprovar artefato no checkpoint do PRD
  Dado que 02-prd.md foi gerado e exibido
  E o usuário navegou até o fim
  Quando pressiona "a"
  Então docs/<slug>/02-prd.md é gravado
  E o traceability-map.yaml recebe state: approved e approved_at
  E a TUI avança para Tech Spec

Cenário: Regenerar
  Dado um artefato em exibição
  Quando o usuário pressiona "r"
  Então o subcomando da etapa é re-executado
  E o arquivo em docs/<slug>/ não é sobrescrito até nova aprovação

Cenário: Editar via $EDITOR
  Dado um artefato em exibição no checkpoint
  Quando o usuário pressiona "e"
  Então o arquivo abre no $EDITOR (fallback vi)
  E ao fechar, a TUI restaura a tela e reapresenta o checkpoint

Cenário: Bloquear avanço sem aprovar etapa obrigatória
  Dado que o PRD está pending
  Quando o usuário tenta ir para Tech Spec
  Então a navegação é bloqueada com "Aprovação do PRD obrigatória"
```

### CA-RF09 — Persistência e contrato
```gherkin
Cenário: Artefato aprovado preserva contrato do harness
  Dado que 02-prd.md foi aprovado via TUI
  Quando o arquivo é validado com sdd validate-artifact
  Então ele contém as seções obrigatórias de schemas/artifact-sections.json

Cenário: Escrita atômica
  Dado que o usuário aprovou um artefato
  Quando o processo é interrompido durante a gravação
  Então o artefato anterior permanece intacto e não há arquivo corrompido
```

### CA-RF11 — Degradação
```gherkin
Cenário: Terminal sem TTY
  Dado que stdout está redirecionado para arquivo/pipe
  Quando o usuário executa "sdd tui"
  Então a TUI não inicia, exibe mensagem de degradação no stderr e encerra com código 1
```

### CA-RF13 — Erro de subcomando
```gherkin
Cenário: Subcomando falha durante etapa
  Dado que a TUI executa uma etapa
  Quando o subcomando encerra com exit não-zero
  Então o painel de erro mostra o stderr
  E oferece "Tentar novamente" e "Editar configuração"
  E não avança para a próxima etapa
```

### CA-RNF05 — Não regressão
```gherkin
Cenário: Subcomandos intactos após a TUI
  Dado o binário compilado com a TUI
  Quando os subcomandos existentes são invocados diretamente
  Então stdout, stderr e exit code são idênticos ao comportamento anterior
```

---

## Métricas

| Métrica | Meta | Medição |
|---|---|---|
| Orquestração completa pela TUI (Ideia→Memory) | ≥ 1 no projeto interno em 2 semanas | inspeção do `traceability-map.yaml` |
| Abertura até primeira tela útil | < 1s | `time sdd tui` |
| Cobertura de loader | 100% das operações > 200ms | verificação manual |
| Regressões em subcomandos | zero | `cargo test` + testes de contrato |
| Contrato TUI vs harness | divergência zero | `sdd validate-artifact` |
| Crashes em terminais suportados | zero panics | testes manuais por terminal |
| Corrupção de artefato aprovado | zero | SIGKILL durante escrita |
| Checkpoints obrigatórios não ignoráveis | 100% bloqueiam avanço | teste de navegação sem aprovação |

---

## Riscos

| ID | Risco | Sev. | Mitigação |
|---|---|---|---|
| R-01 | Complexidade de Markdown + scroll na TUI | Médio | MVP renderiza subconjunto (cabeçalhos/listas/código/tabelas); streaming fora do MVP (exibe artefato completo após o subcomando) |
| R-02 | Deps novas (ratatui/crossterm/tokio) | Médio | Tech Spec decide se tokio é necessário (subcomandos são processos síncronos); medir binário com `cargo bloat` |
| R-03 | Fragmentação harness vs TUI | Baixo-Médio | RN-09 exige contrato idêntico; `sdd validate-artifact` verifica |
| R-04 | Compatibilidade de terminal | Baixo | RF-11 (detecção + degradação) e RNF-03 (lista explícita) |
| R-05 | Divergência de estado vs traceability-map | Médio | RF-09 atualização atômica e imediata; relê estado ao abrir |
| R-06 | Subcomando produz output diferente como processo filho | Médio | Tech Spec define invocação (stdin/env) e contrato; testes de integração |
| R-07 | `$EDITOR` corrompe estado do terminal | Médio | Suspender alternate screen, aguardar editor, restaurar; validar ciclo na Tech Spec |
| R-08 | `sdd` sem subcomando quebrar scripts | Baixo-Médio | Entrada exclusiva por `sdd tui`; `sdd` sem args mantém ajuda atual |

---

## Rastreabilidade

| Campo | Valor |
|---|---|
| Orquestração | `criar-um-cli-poderoso-...-sdd-cli` |
| Artefato de origem | etapa anterior `01-idea.md` (aprovada) |
| Classificação de risco | `00-risk-classification.md` — risco: medium, fator: external_dependency |
| Próximo artefato | `03-techspec.md` |

---

*Aguarda aprovação humana (checkpoint PRD) antes do avanço para Tech Spec.*
