get-shit-done/docs/pt-BR/USER-GUIDE.md

Guia do Usuário do GSD

Referência detalhada de workflows, troubleshooting e configuração. Para setup rápido, veja o README.

---

Sumário

• Fluxo de trabalho
• Contrato de UI
• Backlog e Threads
• Workstreams
• Segurança
• Referência de comandos
• Configuração
• Exemplos de uso
• Troubleshooting
• Recuperação rápida

---

Fluxo de trabalho

Fluxo recomendado por fase:

1. /gsd:discuss-phase [N] — trava preferências de implementação
2. /gsd:ui-phase [N] — contrato visual para fases frontend
3. /gsd:plan-phase [N] — pesquisa + plano + validação
4. /gsd:execute-phase [N] — execução em ondas paralelas
5. /gsd:verify-work [N] — UAT manual com diagnóstico
6. /gsd:ship [N] — cria PR (opcional)

Para iniciar projeto novo:

/gsd:new-project

Para seguir automaticamente o próximo passo:

/gsd:next

Nyquist Validation

Durante plan-phase, o GSD pode mapear requisitos para comandos de teste automáticos antes da implementação. Isso gera {phase}-VALIDATION.md e aumenta a confiabilidade de verificação pós-execução.

Desativar:

{
  "workflow": {
    "nyquist_validation": false
  }
}

Modo de discussão por suposições

Com workflow.discuss_mode: "assumptions", o GSD analisa o código antes de perguntar, apresenta suposições estruturadas e pede apenas correções.

---

Contrato de UI

Comandos

Comando	Descrição
/gsd:ui-phase [N]	Gera contrato de design UI-SPEC.md para a fase
/gsd:ui-review [N]	Auditoria visual retroativa em 6 pilares

Quando usar

• Rode /gsd:ui-phase depois de /gsd:discuss-phase e antes de /gsd:plan-phase.
• Rode /gsd:ui-review após execução/validação para avaliar qualidade visual e consistência.

Configurações relacionadas

Setting	Padrão	O que controla
workflow.ui_phase	true	Gera contratos de UI para fases frontend
workflow.ui_safety_gate	true	Ativa gate de segurança para componentes de registry

---

Backlog e Threads

Backlog (999.x)

Ideias fora da sequência ativa vão para backlog:

/gsd:add-backlog "Camada GraphQL"
/gsd:add-backlog "Responsividade mobile"

Promover/revisar:

/gsd:review-backlog

Seeds

Seeds guardam ideias futuras com condição de gatilho:

/gsd:plant-seed "Adicionar colaboração real-time quando infra de WebSocket estiver pronta"

Threads persistentes

Threads são contexto leve entre sessões:

/gsd:thread
/gsd:thread fix-deploy-key-auth
/gsd:thread "Investigar timeout TCP"

---

Workstreams

Workstreams permitem trabalho paralelo sem colisão de estado de planejamento.

Comando	Função
/gsd:workstreams create <name>	Cria workstream isolado
/gsd:workstreams switch <name>	Troca workstream ativo
/gsd:workstreams list	Lista workstreams
/gsd:workstreams complete <name>	Finaliza e arquiva workstream

workstreams compartilham o mesmo código/git, mas isolam artefatos de .planning/.

---

Segurança

O GSD aplica defesa em profundidade:

• prevenção de path traversal em entradas de arquivo
• detecção de prompt injection em texto do usuário
• hooks de proteção para escrita em .planning/
• scanner CI para padrões de injeção em agentes/workflows/comandos

Para arquivos sensíveis, use deny list no Claude Code.

---

Referência de comandos

Fluxo principal

Comando	Quando usar
/gsd:new-project	Início de projeto
/gsd:discuss-phase [N]	Definir preferências antes do plano
/gsd:plan-phase [N]	Criar e validar planos
/gsd:execute-phase [N]	Executar planos em ondas
/gsd:verify-work [N]	UAT manual
/gsd:ship [N]	Gerar PR da fase
/gsd:next	Próximo passo automático

Gestão e utilidades

Comando	Quando usar
/gsd:progress	Ver status atual
/gsd:resume-work	Retomar sessão
/gsd:pause-work	Pausar com handoff
/gsd:session-report	Resumo da sessão
/gsd:quick	Tarefa ad-hoc com garantias GSD
/gsd:debug [desc]	Debug sistemático
/gsd:forensics	Diagnóstico de workflow quebrado
/gsd:settings	Ajustar workflow/modelos
/gsd:set-profile <profile>	Troca rápida de perfil

Para lista completa e flags avançadas, consulte Command Reference.

---

Configuração

Arquivo de configuração: .planning/config.json

Núcleo

Setting	Opções	Padrão
mode	interactive, yolo	interactive
granularity	coarse, standard, fine	standard
model_profile	quality, balanced, budget, inherit	balanced

Workflow

Setting	Padrão
workflow.research	true
workflow.plan_check	true
workflow.verifier	true
workflow.nyquist_validation	true
workflow.ui_phase	true
workflow.ui_safety_gate	true

Perfis de modelo

Perfil	Uso recomendado
quality	trabalho crítico, maior qualidade
balanced	padrão recomendado
budget	reduzir custo de tokens
inherit	seguir modelo da sessão/runtime

Detalhes completos: Configuration Reference.

---

Exemplos de uso

Projeto novo

claude --dangerously-skip-permissions
/gsd:new-project
/gsd:discuss-phase 1
/gsd:ui-phase 1
/gsd:plan-phase 1
/gsd:execute-phase 1
/gsd:verify-work 1
/gsd:ship 1

Código já existente

/gsd:map-codebase
/gsd:new-project

Correção rápida

/gsd:quick
> "Corrigir botão de login no mobile Safari"

Preparação para release

/gsd:audit-milestone
/gsd:plan-milestone-gaps
/gsd:complete-milestone

---

Troubleshooting

"Project already initialized"

.planning/PROJECT.md já existe. Apague .planning/ se quiser reiniciar do zero.

Sessão longa degradando contexto

Use /clear entre etapas grandes e retome com /gsd:resume-work ou /gsd:progress.

Plano desalinhado

Rode /gsd:discuss-phase [N] antes do plano e valide suposições com /gsd:list-phase-assumptions [N].

Execução falhou ou saiu com stubs

Replaneje com escopo menor (tarefas menores por plano).

Custo alto

Use perfil budget:

/gsd:set-profile budget

Runtime não-Claude (Codex/OpenCode/Gemini/Kilo)

Use resolve_model_ids: "omit" para deixar o runtime resolver modelos padrão.

---

Recuperação rápida

Problema	Solução
Perdeu contexto	/gsd:resume-work ou /gsd:progress
Fase deu errado	git revert + replanejar
Precisa alterar escopo	/gsd:add-phase, /gsd:insert-phase, /gsd:remove-phase
Bug em workflow	/gsd:forensics
Correção pontual	/gsd:quick
Custo alto	/gsd:set-profile budget
Não sabe próximo passo	/gsd:next

---

Estrutura de arquivos do projeto

.planning/
  PROJECT.md
  REQUIREMENTS.md
  ROADMAP.md
  STATE.md
  config.json
  MILESTONES.md
  HANDOFF.json
  research/
  reports/
  todos/
  debug/
  codebase/
  phases/
    XX-phase-name/
      XX-YY-PLAN.md
      XX-YY-SUMMARY.md
      CONTEXT.md
      RESEARCH.md
      VERIFICATION.md
      XX-UI-SPEC.md
      XX-UI-REVIEW.md
  ui-reviews/

Note

Esta é a versão pt-BR do guia para uso diário. Para detalhes técnicos exatos e cobertura completa de parâmetros avançados, consulte também o guia original em inglês.