openspdd-workflow

Skill de engenharia de prompts estruturados via OpenSPDD (Spec-Driven Prompt Development / REASONS Canvas). Use quando precisar conduzir a análise estratégica de uma proposta OpenSpec (spdd-analysis),

SKILL.md

GitHub

Skill — OpenSPDD Workflow (REASONS Canvas)

Este skill define o padrão do OpenSPDD (Spec-Driven Prompt Development), a metodologia de transição entre a especificação arquitetural e a geração determinística de código COBOL.


🎯 Por que OpenSPDD?

Em linguagens antigas e de formato estrito como COBOL (onde um erro na coluna 7 ou 11 quebra o compilador), pedir para uma IA "gerar o código diretamente" causa alucinações de formatação e quebra de regras.

O OpenSPDD resolve isso dividindo o processo em 3 operações:

  1. spdd-analysis: Analisa a proposta OpenSpec e disseca as 4 divisões COBOL, variáveis e riscos.
  2. spdd-reasons-canvas: Converte a análise num contrato executável rígido de 7 dimensões (REASONS).
  3. spdd-generate: Executa as operações do Canvas com tolerância zero a desvios e validação mecânica imediata.

🔄 As Três Operações do OpenSPDD

┌────────────────────────────────────────────────────────┐
│                   CICLO OPENSPDD                       │
├────────────────────────────────────────────────────────┤
│ 1. spdd-analysis        (openspec/change/ → Análise)   │
│ 2. spdd-reasons-canvas  (Análise → REASONS Canvas)     │
│ 3. spdd-generate        (REASONS Canvas → Código COBOL)│
└────────────────────────────────────────────────────────┘

Operação 1: spdd-analysis /openspec/change/{proposta}

Agente executor: cobol-planner.agent
Destino do arquivo: spdd/analysis/{ID}-[Analysis]-{proposta}.md
(Convenção de ID: COB-XXX-YYYYMMDDHHmm, ex.: COB-001-202609061730-[Analysis]-modulo.md)

O que faz:

  1. Lê integralmente os artefatos da change OpenSpec (proposal.md, design.md, tasks.md).
  2. Lê o código atual em src/CALCULADORA.cbl e as regras em AGENTS.md.
  3. Elabora a análise cobrindo 4 seções:
    • 1. Contexto e Objetivos: Resumo executivo da mudança e valor de negócio.
    • 2. Inventário Conceitual COBOL:
      • IDENTIFICATION DIVISION: PROGRAM-ID, autor, data.
      • ENVIRONMENT DIVISION: configurações de máquina.
      • DATA DIVISION (WORKING-STORAGE): novas variáveis WS-, cláusulas PIC (ex.: 9(5), S9(10)), níveis (01, 77).
      • PROCEDURE DIVISION: parágrafos a criar/modificar, instruções aritméticas (ADD, SUBTRACT, MULTIPLY, DIVIDE, COMPUTE), pontos de decisão e PERFORM.
    • 3. Riscos, Ambiguidade e Salvaguardas: Limite de 72 colunas, transbordamento de picture (ON SIZE ERROR), divisão por zero, compatibilidade com compilador GnuCOBOL.
    • 4. Rastreabilidade de Quality Gates: Fitness functions impactadas, comandos de compilação e teste.

Operação 2: spdd-reasons-canvas /spdd/analysis/{analysis}

Agente executor: cobol-planner.agent
Destino do arquivo: spdd/prompt/{ID}-[Code]-{proposta}.md

O que faz:

Transforma a análise estratégica no prompt estruturado canônico REASONS Canvas:

# REASONS Canvas — [Nome da Feature]

**ID:** COB-XXX-YYYYMMDDHHmm-[Code]-[proposta]  
**Data:** YYYY-MM-DD  
**Origem:** spdd/analysis/[arquivo-de-analise].md  
**Alvo:** src/CALCULADORA.cbl  

---

## 1. Requirements (Requisitos)
- REQ-01: Descrição do cálculo matemático exato.
- REQ-02: Entrada de dados via ACCEPT e saída formatada com PIC Z ou PIC -.
- REQ-03: Não quebrar nenhuma operação existente (soma, subtração, divisão, etc.).
- REQ-04: Passar nas 13 fitness functions de arquitetura (make fitness).

## 2. Entities (Entidades COBOL)
- Arquivo alvo: src/CALCULADORA.cbl
- Novas variáveis Working-Storage:
  - WS-VARIAVEL-X: PIC 9(5) VALUE ZEROS.
- Parágrafos afetados: PROCESSAR-OPCAO, CALCULAR-OPERACAO.

## 3. Approach (Abordagem)
- Sequência de passos para a implementação do código sem replanejar.

## 4. Structure (Estrutura e Colunas)
- Colunas 1-6: Vazio
- Coluna 7: Espaço (ou '*' para comentários)
- Área A (colunas 8-11): Declarações de nível 01, nomes de SECTION e parágrafos.
- Área B (colunas 12-72): Sentenças COBOL, DISPLAY, ACCEPT, COMPUTE, PERFORM.

## 5. Operations (Operações de Execução para o Coder)
- OP-01: Transicionar fase do harness com `python3 scripts/harness/phase_cli.py set apply <proposta>`.
- OP-02: Adicionar a nova opção no menu DISPLAY.
- OP-03: Declarar as novas variáveis na WORKING-STORAGE SECTION.
- OP-04: Implementar o parágrafo de cálculo na PROCEDURE DIVISION.
- OP-05: Executar compilação com `make build` (ou cobc -x).
- OP-06: Executar sensores de arquitetura com `make fitness`.
- OP-07: Executar teste funcional com `make smoke-test`.
- OP-08: Atualizar tarefas em `openspec/changes/<proposta>/tasks.md` e rodar `openspec validate <proposta> --strict`.

## 6. Norms (Normas e Convenções)
- Ponto final obrigatório ao fim de cada sentença.
- Nomes em MAIÚSCULAS com hífens.
- Prefixo WS- para variáveis de Working Storage.
- Comentários em português iniciando na coluna 7.

## 7. Safeguards (Salvaguardas de Qualidade)
- Rollback: git checkout -- src/CALCULADORA.cbl em caso de falha irreversível.
- Gate de compilação: cobc -x deve retornar exit code 0.
- Gate de arquitetura: make fitness deve retornar 13/13 OK.

Operação 3: spdd-generate /spdd/prompt/{reasons-canvas}

Agente executor: cobol-coder.agent

O que faz:

  1. Desbloqueia o Gate de Fase:
    python3 scripts/harness/phase_cli.py set apply <proposta>
    
  2. Lê o REASONS Canvas: Carrega o arquivo spdd/prompt/{reasons-canvas}.
  3. Executa as Operações: Segue a lista Operations de forma determinística, linha a linha.
  4. Executa os Sensores:
    make build        # cobc -x -o calculadora src/CALCULADORA.cbl
    make fitness      # python3 -m unittest discover -s tests/fitness
    make smoke-test   # ./calculadora com input simulado
    
  5. Atualiza a Especificação: Marca as caixas em openspec/changes/{proposta}/tasks.md e valida:
    openspec validate <proposta> --strict
    
  6. Emite Handoff: Sugere handoff para o cobol-reviewer.agent.

🛡️ Benefícios do Fluxo no SDLC

Benefício Sem OpenSPDD Com OpenSPDD
Formatação de Colunas Fácil quebrar colunas 8/12/72 Definida estritamente na seção Structure
Alucinação de Lógica Agente decide lógica no impulso Agente segue as Operations do Canvas
Rastreabilidade Código sem vínculo com a spec ID único liga Spec → Análise → Canvas → Código
Segurança de Fase Edições prematuras bloqueadas Escrita só é liberada com transição para apply