planner

Resumo

Cria planos de implementação estruturados com workflows para feature, refactor, investigation e migration.

Skills Relacionadas

Skill	Quando usar junto
spec	Para usar specs como source de requisitos
sprint	Para usar sprints como source de tarefas
coder	Para executar o plano criado
qa	Para validar a qualidade da implementação
architecture	Para definir arquitetura no plano

Quando usar

Use esta skill quando precisar:

• Planejar a implementação de uma nova feature
• Estruturar um refactoring complexo
• Investigar um bug ou comportamento inesperado
• Planejar uma migration de dados ou infraestrutura
• Criar planos de implementação acionáveis

Não use para:

• Tarefas triviais (use o workflow "simple")
• Análise de codebase sem objetivo de implementação
• Planejamento estratégico de produto (use roadmap-strategy)

---

Workflow Types

Escolha o workflow apropriado baseado no tipo de tarefa:

Workflow	Quando usar	Exemplos
feature	Nova funcionalidade	Adicionar autenticação OAuth, criar dashboard
refactor	Melhorar código existente	Extrair componentes, renomear módulos
investigation	Entender/debugar	Bug investigation, performance analysis
migration	Mover dados/infra	Database migration, framework upgrade
simple	Tarefas diretas	Fix typo, atualizar config

Feature Workflow

Para novas funcionalidades que adicionam valor ao produto:

1. Analise requisitos e dependências
2. Design da solução (API, componentes, fluxo)
3. Implementação por camadas (backend → frontend)
4. Testes e validação
5. Documentação

Refactor Workflow

Para melhorias de código sem mudança de comportamento:

1. Identifique o que será refatorado
2. Garanta testes existentes passando
3. Faça mudanças incrementais
4. Rode testes após cada mudança
5. Valide comportamento inalterado

Investigation Workflow

Para bugs ou comportamentos inesperados:

1. Defina o problema claramente
2. Colete evidências (logs, stack traces)
3. Forme hipóteses
4. Teste hipóteses sistematicamente
5. Documente causa raiz e solução

Migration Workflow

Para migrações de dados ou infraestrutura:

1. Mapeie estado atual → estado desejado
2. Identifique dependências e riscos
3. Crie plano de rollback
4. Execute em fases
5. Valide cada fase

Simple Workflow

Para tarefas triviais:

1. Entenda a mudança
2. Implemente
3. Verifique
4. Commit

---

Estrutura do Plano

O plano de implementação segue esta estrutura JSON:

{
  "spec_id": "spec-001",
  "workflow_type": "feature",
  "phases": [
    {
      "id": 0,
      "name": "Pre-Planning",
      "subtasks": [
        {
          "id": "st-0-1",
          "title": "Load context",
          "status": "pending"
        }
      ]
    }
  ],
  "verification_strategy": {
    "type": "command",
    "command": "npm test"
  }
}

Fases do Plano

Fase	Nome	Objetivo
0	Pre-Planning	Carregar contexto, entender requisitos
1	Analysis	Analisar codebase, identificar arquivos
2	Design	Design da solução, estrutura
3	Implementation	Implementação principal
4	Testing	Testes unitários, integração
5	Review	Code review, ajustes
6	Integration	Merge, deployment
7	Verification	Validação final

Estrutura de Subtasks

Cada subtask deve ter:

• id: Identificador único (st-fase-numero)
• title: Título descritivo e acionável
• description: Detalhes da tarefa (opcional)
• status: pending | in_progress | completed | blocked
• verification: Como verificar conclusão (opcional)
• files: Arquivos relacionados (opcional)

---

Verification Strategy

Cada plano deve incluir uma estratégia de verificação. Veja references/verification-types.md para detalhes.

Tipo	Quando usar	Exemplo
command	Testes, builds	npm test, make build
api	APIs REST/GraphQL	curl localhost:3000/api/health
browser	UI web	Puppeteer, screenshots
e2e	Fluxos completos	Playwright, Cypress
manual	Verificação humana	Code review, UX testing
none	Não verificável automaticamente	Documentação

---

Pre-Planning Checklist

Antes de criar o plano, verifique:

• Li e entendi a spec/task
• Identifiquei o workflow type apropriado
• Selecionei a verification strategy
• Mapeei arquivos que serão modificados
• Identifiquei dependências
• Avaliei riscos e complexidade
• Defini critérios de sucesso

---

Exemplo de Plano

{
  "spec_id": "spec-add-oauth",
  "workflow_type": "feature",
  "phases": [
    {
      "id": 0,
      "name": "Pre-Planning",
      "subtasks": [
        {"id": "st-0-1", "title": "Load spec and understand requirements", "status": "pending"},
        {"id": "st-0-2", "title": "Review existing auth implementation", "status": "pending"}
      ]
    },
    {
      "id": 1,
      "name": "Analysis",
      "subtasks": [
        {"id": "st-1-1", "title": "Identify files to modify", "status": "pending"},
        {"id": "st-1-2", "title": "Check OAuth provider docs", "status": "pending"}
      ]
    },
    {
      "id": 3,
      "name": "Implementation",
      "subtasks": [
        {"id": "st-3-1", "title": "Add OAuth provider config", "status": "pending", "files": ["src/auth/config.ts"]},
        {"id": "st-3-2", "title": "Create OAuth callback handler", "status": "pending", "files": ["src/auth/oauth.ts"]},
        {"id": "st-3-3", "title": "Update login UI", "status": "pending", "files": ["src/components/Login.tsx"]}
      ]
    },
    {
      "id": 4,
      "name": "Testing",
      "subtasks": [
        {"id": "st-4-1", "title": "Add OAuth unit tests", "status": "pending"},
        {"id": "st-4-2", "title": "Test OAuth flow manually", "status": "pending"}
      ]
    }
  ],
  "verification_strategy": {
    "type": "browser",
    "steps": ["Navigate to login", "Click OAuth button", "Verify redirect", "Verify login success"]
  }
}

---

Referências

• references/verification-types.md - Tipos de verificação detalhados
• references/workflow-patterns.md - Padrões de workflow
• references/plan-structure.md - Schema JSON completo