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/skills/openspdd-workflow/SKILL.md
GitHubSkill — 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:
spdd-analysis: Analisa a proposta OpenSpec e disseca as 4 divisões COBOL, variáveis e riscos.spdd-reasons-canvas: Converte a análise num contrato executável rígido de 7 dimensões (REASONS).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:
- Lê integralmente os artefatos da change OpenSpec (
proposal.md,design.md,tasks.md). - Lê o código atual em
src/CALCULADORA.cble as regras emAGENTS.md. - 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áveisWS-, cláusulasPIC(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 ePERFORM.
- 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:
- Desbloqueia o Gate de Fase:
python3 scripts/harness/phase_cli.py set apply <proposta> - Lê o REASONS Canvas: Carrega o arquivo
spdd/prompt/{reasons-canvas}. - Executa as Operações: Segue a lista
Operationsde forma determinística, linha a linha. - 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 - Atualiza a Especificação: Marca as caixas em
openspec/changes/{proposta}/tasks.mde valida:openspec validate <proposta> --strict - 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 |