wicttor/pwrl

PWRL Plan — Orquestrador de Habilidades Puras

Crie planos de implementação duráveis que podem ser entregues para execução. Orquestra um pipeline determinístico de micro-habilidades: escopo → pesquisa → design → gerar. Sem dependência de agente, sem caminhos de fallback.

Propósito

Os planos capturam decisões, estrutura e abordagem antes da execução. Eles permitem:

• Escopo claro e critérios de sucesso
• Riscos e dependências identificados
• Unidades de implementação concretas com critérios de aceitação
• Reutilização de conhecimento por meio de aprendizados relacionados
• Confiança de que o trabalho não sairá dos trilhos

Fluxo de Trabalho Central: Pipeline de Quatro Fases

ENTRADA (descrição da tarefa)
  ↓
FASE 1: Escopo (pwrl-plan-scope)
  → Coletar contexto, validar domínio, iniciar requisitos
  → Saída: artefato de contexto com escopo
  ↓
FASE 2: Pesquisa (pwrl-plan-research)
  → Descobrir padrões, identificar riscos, recomendar pesquisa externa
  → Saída: artefato de descobertas de pesquisa
  ↓
FASE 3: Design (pwrl-plan-design)
  → Decompor em unidades, mapear dependências, avaliar complexidade
  → Saída: artefato de design com decomposição em unidades
  ↓
FASE 4: Gerar (pwrl-plan-generate)
  → Selecionar nível, renderizar plano, incorporar aprendizados, salvar em docs/plans/
  → Saída: documento de plano final salvo em arquivo
  ↓
SAÍDA (arquivo de plano pronto para execução)

Detalhes das Fases

Fase 1: Escopo (pwrl-plan-scope)

Propósito: Ponto de entrada do fluxo de planejamento. Coleta contexto, verifica planos e aprendizados existentes, valida o domínio e retorna um objeto de contexto com escopo.

Micro-habilidade: pwrl-plan-scope

Entrada:

• O usuário fornece descrição da tarefa, documento de requisitos ou objetivo
• Entrada vazia solicita ao usuário: "O que você gostaria de planejar?"

Processamento:

1. Verificar planos existentes em docs/plans/; sugerir retomar/revisar/arquivar/excluir/novo
2. Validar domínio (software vs. não-software)
3. Iniciar estrutura do problema, comportamento pretendido, critérios de sucesso
4. Pesquisar docs/learnings/INDEX.md por aprendizados relacionados
5. Pesquisar docs/requirements/ e docs/brainstorms/ por documentos correspondentes
6. Confirmar contexto com o usuário
7. Perguntar modo de interação:
   • Detalhado: Interação passo a passo em cada fase (revisar, confirmar, ajustar)
   • Yolo: Automação total da Fase 1 à Fase 4, apenas confirmação final
8. Gerar artefato de escopo com interaction_mode

Saída: Artefato de contexto com escopo contendo:

• Estrutura do problema, comportamento pretendido, critérios de sucesso
• Aprendizados relacionados (relevância ALTA)
• Lacunas de aprendizado identificadas
• Requisitos encontrados
• interaction_mode (detalhado ou yolo)

Veja: pwrl-plan-scope/SKILL.md para fluxo de trabalho detalhado

Fase 2: Pesquisa (pwrl-plan-research)

Propósito: Descobrir padrões locais, pilha de tecnologia e áreas de alto risco. Recomendar pesquisa externa, se necessário.

Micro-habilidade: pwrl-plan-research

Entrada: Artefato de contexto com escopo da Fase 1

Processamento:

1. Detectar pilha de tecnologia a partir de package.json, Dockerfile, estrutura do código-fonte
2. Descobrir padrões locais (arquitetura, estilo assíncrono, testes, organização)
3. Identificar áreas de alto risco (segurança, desempenho, migrações, sistemas distribuídos, conformidade)
4. Recomendar pesquisa externa para áreas de alto risco (opcional)
5. Integrar insights de aprendizados relacionados
6. Compilar descobertas da pesquisa

Saída: Artefato de pesquisa contendo:

• Detecção da pilha de tecnologia
• Padrões locais identificados
• Áreas de risco com recomendações
• Descobertas de pesquisa externa (se realizada)
• Notas de integração de aprendizados

Veja: pwrl-plan-research/SKILL.md para fluxo de trabalho detalhado

Fase 3: Design (pwrl-plan-design)

Propósito: Decompor o trabalho em unidades de implementação, identificar dependências e riscos, avaliar complexidade.

Micro-habilidade: pwrl-plan-design

Entrada: Contexto com escopo + Descobertas da pesquisa

Processamento:

1. Identificar unidades de trabalho a partir dos critérios de sucesso e áreas de risco
2. Mapear dependências entre unidades (ordenação topológica)
3. Detectar dependências circulares; solicitar refatoração
4. Criar unidades de mitigação de risco
5. Gerar diagramas Mermaid para fluxos de trabalho complexos (5+ unidades)
6. Avaliar complexidade (BAIXA/MÉDIA/ALTA)
7. Estimar esforço
8. Confirmar decomposição com o usuário

Saída: Artefato de design contendo:

• Unidades de implementação (U1, U2, ..., UX) com cenários de teste e critérios de aceitação
• Grafo de dependências e ordenação topológica
• Mitigações de risco
• Diagramas Mermaid (se complexo)
• Avaliação de complexidade e estimativa de esforço

Veja: pwrl-plan-design/SKILL.md para fluxo de trabalho detalhado

Fase 4: Gerar (pwrl-plan-generate)

Propósito: Selecionar nível (Rápido/Padrão/Profundo), renderizar plano usando o template do nível, incorporar aprendizados, salvar em docs/plans/.

Micro-habilidade: pwrl-plan-generate

Entrada: Artefato de design (da Fase 3) + Artefato de escopo (da Fase 1)

Processamento:

1. Auto-selecionar nível com base na complexidade/unidades/esforço; solicitar se ambíguo
   • RÁPIDO: Complexidade BAIXA, 1-3 unidades, <5 horas
   • PADRÃO: Complexidade MÉDIA, 4-8 unidades, 5-20 horas
   • PROFUNDO: Complexidade ALTA, 9+ unidades, 20+ horas
2. Renderizar plano usando template específico do nível
3. Incorporar os 3-5 principais aprendizados de alta relevância do escopo
4. Gerar nome de arquivo único: YYYY-MM-DD-NNN-<slug>.md
5. Tratar colisões de nome de arquivo (incrementar sequência ou atualizar existente)
6. Salvar plano em docs/plans/

Saída: Documento de plano salvo em arquivo contendo:

• Problema e escopo
• Critérios de sucesso
• Unidades de implementação (nível de detalhe específico do nível)
• Análise de risco (PADRÃO/PROFUNDO)
• Aprendizados relacionados (PADRÃO/PROFUNDO)
• Lacunas de aprendizado (PROFUNDO)
• Notas de implantação (PADRÃO/PROFUNDO)

Veja: pwrl-plan-generate/SKILL.md para fluxo de trabalho detalhado

Níveis de Planejamento

Nível	Melhor Para	Arquivos	Risco	Tempo
RÁPIDO	Correções de bugs, pequenos ajustes	1-3	BAIXO	5-15 min
PADRÃO	Maioria das funcionalidades	4-8	MÉDIO	30-45 min
PROFUNDO	Arquitetura, segurança, migrações	9+	ALTO	1-2 horas

Veja references/planning-tiers.md para critérios completos de decisão de nível e exemplos de template.

Princípios Fundamentais

• Pipeline Determinístico: As fases sempre executam em sequência: escopo → pesquisa → design → gerar (sem ramificações, sem fallback)
• Foco em Decisões: Capturar abordagem, estrutura, riscos e sequenciamento (não simulação de código)
• Tamanho Adequado: Tarefas pequenas → planos curtos; trabalho complexo → mais estrutura
• Separar Planejamento da Execução: Não simular implementação durante o planejamento
• Seja Concreto: Usar arquivos, componentes e dependências específicos
• Mantenha-se Portátil: Usar apenas caminhos relativos ao repositório
• Artefatos Transparentes: Cada fase produz um artefato de saída explícito para a próxima fase

Tratamento de Erros e Recuperação

Filosofia: Falhar explicitamente, não silenciosamente. Cada fase possui tratamento de erro claro com sugestões de recuperação.

Erros da Fase 1 (Escopo)

• Entrada Vazia: Solicitar descrição da tarefa ao usuário; tentar novamente
• Domínio Não-Software: Retornar erro; sugerir ferramenta alternativa
• Entrada Ambígua: Fazer perguntas esclarecedoras; iniciar com respostas do usuário
• Nenhum Aprendizado/Requisito: Continuar (não é um erro)

Recuperação: O usuário pode tentar novamente, fornecer esclarecimento ou abortar

Erros da Fase 2 (Pesquisa)

• Falha na Análise do Código-Fonte: Continuar com informações mínimas da pilha de tecnologia
• Área de Alto Risco Identificada: Recomendar pesquisa externa; usuário pode aprovar ou pular

Recuperação: O usuário pode aprovar a pesquisa, pular ou investigar manualmente

Erros da Fase 3 (Design)

• Dependência Circular Detectada: Relatar caminho do ciclo; solicitar ao usuário que refatore
• Muitas Unidades (15+): Avisar sobre complexidade; sugerir consolidação
• Detalhamento Insuficiente: Solicitar adição de cenários de teste ou divisão de unidades

Recuperação: O usuário pode refatorar, consolidar ou prosseguir com ciência

Erros da Fase 4 (Gerar)

• Colisão de Nome de Arquivo: Oferecer opções: atualizar, incrementar ou cancelar
• Seleção de Nível Ambígua: Solicitar ao usuário que escolha o nível
• Falha na Escrita do Arquivo: Verificar permissões/diretório; tentar novamente ou sugerir salvamento manual

Recuperação: O usuário pode escolher uma ação ou salvar manualmente

Principais Saídas

Cada plano inclui (dependendo do nível):

• Problema e Escopo: Estrutura clara do problema e comportamento pretendido
• Critérios de Sucesso: 1-3 condições específicas para conclusão
• Unidades de Implementação: U-IDs nomeadas com dependências, arquivos, abordagem e critérios de aceitação
• Aprendizados Relacionados: Arquivos de aprendizado vinculados com notas de aplicabilidade (PADRÃO/PROFUNDO)
• Lacunas de Aprendizado: Áreas que precisam de documentação pós-implementação (PROFUNDO)
• Seções Específicas do Nível: Análise de risco, alternativas, notas de implantação (PADRÃO/PROFUNDO)

Método de Interação

• Usar a extensão ask_user_questions da plataforma para todas as decisões
• Fazer uma pergunta de cada vez
• Usar perguntas de múltipla escolha quando possível
• Se a entrada estiver vazia, perguntar: "O que você gostaria de planejar? Descreva a tarefa ou projeto."
• Fornecer sugestões claras de recuperação quando ocorrerem erros

Arquitetura: Sem Roteamento de Agente

Diferença da Versão Anterior:

Antes: A habilidade detectava se o agente estava disponível e então delegava ao agente OU executava o fallback monolítico (dois caminhos de código)

Depois: A habilidade chama diretamente as micro-habilidades em sequência—um único pipeline determinístico, sem ramificações:

orquestrador pwrl-plan
├── 1. Chamar pwrl-plan-scope → obter artefato de escopo
├── 2. Chamar pwrl-plan-research → obter artefato de pesquisa
├── 3. Chamar pwrl-plan-design → obter artefato de design
└── 4. Chamar pwrl-plan-generate → salvar arquivo de plano

Benefícios:

• ✅ Mais simples de entender (caminho de código único)
• ✅ Mais fácil de testar (sem lógica de ramificação)
• ✅ Mais sustentável (micro-habilidades testáveis independentemente)
• ✅ Mais componível (micro-habilidades reutilizáveis em outros fluxos de trabalho)
• ✅ Melhor tratamento de erros (explícito em cada fase)

Referências de Micro-Habilidades

• pwrl-plan-scope — Coleta de contexto e escopo
• pwrl-plan-research — Descoberta de padrões e identificação de riscos
• pwrl-plan-design — Decomposição em unidades e mapeamento de dependências
• pwrl-plan-generate — Renderização de plano e geração de arquivo

Documentação Relacionada

• references/planning-tiers.md — Definições de níveis e critérios de decisão
• docs/guides/micro-skill-patterns.md — Como estender com novas micro-habilidades
• docs/guides/skill-architecture-refactoring.md — Fundamentação para a refatoração

Testes e Validação

Cobertura abrangente de testes:

• 30+ testes para pwrl-plan-scope (U1.1)
• 25+ testes para pwrl-plan-research (U1.2)
• 35+ testes para pwrl-plan-design (U1.3)
• 30+ testes para pwrl-plan-generate (U1.4)
• 30+ testes de integração para o pipeline de orquestração completo

Compatibilidade Retroativa:

• Mesmo comportamento de entrada/saída da versão anterior
• Planos existentes gerados com sucesso
• Nenhuma mudança que quebre para usuários

Perguntas Frequentes

P: E se uma fase falhar? Posso pulá-la ou tentar novamente?

R: Sim. Cada fase possui tratamento de erro explícito com sugestões de recuperação. Você pode tentar novamente, fornecer esclarecimento, modificar o escopo ou abortar. Sem falhas silenciosas.

P: Posso usar apenas uma micro-habilidade (por exemplo, apenas gerar a partir do design)?

R: O orquestrador espera chamar todas as quatro fases em sequência. Se você quiser usar uma única micro-habilidade, chame-a diretamente pelo nome: /pwrl-plan-scope, /pwrl-plan-design, etc.

P: Por que não há roteamento de agente?

R: Os agentes estavam adicionando complexidade sem valor agregado. O pipeline de micro-habilidades é determinístico, testável e mais fácil de entender. A chamada direta de habilidades é mais simples e sustentável.

P: Posso estender isso para outros fluxos de trabalho?

R: Sim! As micro-habilidades são reutilizáveis. Por exemplo, pwrl-work pode usar pwrl-plan-design para decomposição em unidades. Veja docs/guides/micro-skill-patterns.md.

---

Status: Pipeline de habilidade pura (sem roteamento de agente) Versão: 2.0 (refatorado a partir de arquitetura dependente de agente) Criado: 2026-06-11