openspec-details.md

Openspec Details

Aqui está a explicação detalhada de cada um:

1. proposal.md (A Proposta)

Este é o documento de "alto nível". Ele foca no PORQUÊ e no O QUE, sem entrar em detalhes técnicos de implementação.

• Objetivo: Alinhar a intenção. Ele registra que estamos gastando muitos minutos (~955/mês) e define o sucesso como a redução desse custo.
• Conteúdo: Problema atual, lista de mudanças esperadas (ex: Concorrência, Filtros de Path) e o impacto esperado no projeto e no custo operacional.

---

2. specs/pipeline/spec.md (A Especificação)

Este arquivo define as Regras de Negócio e Requisitos Técnicos. É o contrato do que o sistema "deve" fazer.

• Objetivo: Ser a base para testes e validação. Ele usa termos como SHALL/MUST (DEVE) para definir comportamentos obrigatórios.
• Conteúdo: Requisitos específicos como: "O sistema DEVE cancelar execuções obsoletas". Cada requisito vem acompanhado de um Cenário (WHEN/THEN), que descreve o comportamento esperado em uma situação real.

---

3. design.md (O Design Técnico)

Aqui é onde descrevemos o COMO. É o documento de arquitetura da mudança.

• Objetivo: Resolver ambiguidades técnicas antes de começar a codar. Ele explica as decisões tomadas (ex: por que usar filtros de path YAML em vez de uma action externa).
• Conteúdo: Decisões arquiteturais, análise de riscos (ex: risco de omitir um filtro de path e quebrar o build) e diagramas Mermaid que visualizam o novo fluxo de execução.

---

4. tasks.md (As Tarefas)

Este é o Plano de Execução prático.

• Objetivo: Quebrar o design em passos acionáveis e rastreáveis. É o arquivo que guia o comando /opsx:apply.
• Conteúdo: Uma lista de checkboxes dividida em fases (Concorrência, Filtros de Path, Cache, Verificação). Cada item é uma unidade de trabalho pequena e verificável.

---

Visualizando a Relação entre os Arquivos

    1   ┌─────────────┐       ┌─────────────┐
    2   │ proposal.md │──────▶│  specs/     │ (O que o sistema deve fazer)
    3   │ (Intenção)  │       │  spec.md    │
    4   └──────┬──────┘       └──────┬──────┘
    5          │                     │
    6          │      ┌──────────────┘
    7          ▼      ▼
    8   ┌─────────────┐       ┌─────────────┐
    9   │  design.md  │──────▶│  tasks.md   │ (Passos para construir)
   10   │  (Como)     │       │  (Checklist)│
   11   └─────────────┘       └─────────────┘

Em resumo:

• Se você quer saber por que estamos fazendo isso: leia proposal.md.
• Se você quer saber quais as regras de funcionamento: leia specs/pipeline/spec.md.
• Se você quer saber a estratégia técnica: leia design.md.
• Se você quer saber o que falta fazer: leia tasks.md.