teqo/docs/plans/work-issue-paradigma-issue-claimada-impl.md

Impl: Work-issue no paradigma de Issue já claimada (+ model-selection volta ao cardápio Cursor)

Status: aprovado Atualizado em: 2026-08-10 Issue: #594 Intenção: docs/plans/work-issue-paradigma-issue-claimada.md Appetite restante: herdado (~1–1,5 dia; entrega pura de skills/scripts/docs — sem schema/UI)

Leitura da intenção

• Outcome: uma sessão /work-issue sem nenhum passo de verificação (sem claim, sem checagem de worktree/branch, sem checagem de modelo) — a skill assume o contrato "Issue já claimada, worktree correto, branch correta, modelo fixo" e vai direto ao impl plan → pausa humana → execução → simplify → débitos → PR.
• O que NÃO negociar: fluxo continua com impl plan → pausa → execução → /simplify → capture-review-debts com gate humano → PR Ready --base main + auto-merge; nunca claimar por conta própria; não duplicar a lógica de claim do pool; não virar guarda-costas (anti-goals).
• O que reavaliar: a hipótese listava AGENTS.md como área — verificada e descartada: o texto de claim do worktree next é do OPS33 (este item é o receptor, não o produtor); a única menção a work-issue no AGENTS.md é o bullet do launch (/work-issue já enviado), que continua válido.

Abordagem recomendada

flowchart LR
  S["Sessão no worktree<br/>(OPS33: já claimada)"] --> C["Contexto: /work-issue --issue N<br/>ou $ARGUMENTS; ausente → 1 pergunta<br/>com validação (gh issue view)"]
  C --> P["Plan mode → docs/plans/&lt;slug&gt;-impl.md<br/>(engineering-brief + template)"]
  P -->|pausa| H["Gate humano"]
  H -->|aprovado| E["Execução → gates"]
  E --> Q["/simplify + fixes"]
  Q --> D["capture-review-debts<br/>com gate humano"]
  D --> PR["PR Ready --base main<br/>Closes #N → auto-merge → checks"]

Opções consideradas: A) work-issue vira fluxo próprio que consome contexto do prompt/args; B) work-issue continua delegando a agent-work-issue só tirando o claim; C) fundir as duas skills. Recomendação: A — o anti-goal da intenção proíbe "um terceiro fluxo", mas B mantém o acoplamento que a intenção quer quebrar ("deixa de ser a versão humana de agent-work-issue": o pool tem regras próprias — prep Cloud, sem pausa, débitos autônomos — e o humano tem gate humano, pergunta de contexto, validate do claim); C duplicaria as duas superfícies de operação (pool vs humano) numa só — o custo de falha do pool (claim coordenado) não cabe na skill humana. Rejeitadas: B porque mantém "base de execução" e arrastaria Prep Cloud/débitos autônomos para a sessão humana; C porque misturaria contratos de atores diferentes.

Componentes / mudanças

• .agents/skills/work-issue/SKILL.md (reescrever): descrição no frontmatter + fluxo próprio — (0) prep pnpm i; (1) contexto: número da Issue vindo de $ARGUMENTS/prompt da sessão (--issue <N> ou número puro — contrato OPS33); ausente → uma pergunta ao humano com validação (gh issue view: OPEN + label in-progress — claim é contrato do ambiente, nunca da skill; checagem falhou → pare e peça o claim fora da skill); plano de intenção recuperado do body da Issue (Plano: [\docs/plans/…`]— mesma regexextractPlanPathdo pool; sem plano linkado → body é spec); (2) sem verificação de modelo —model:é metadata consultiva, sessão da máquina do humano é sempre Flash; (3) Plan mode →*-impl.md(engineering-brief/implementation-template/decision-quality como **materiais de referência**, não pipeline herdado) → **PARA**; (4) após confirmação: execução →/simplify→capture-review-debtscom gate humano → PR. **Extração do /simplify:** a mecânica de execução→fechamento (Passos 4–6) vira material compartilhado novoexecution-pipeline.md(no diretório da work-issue), referenciado pelas duas skills com tabela de deltas por ator (branch, UI, modo do capture-review-debts, Cloud) — elimina a duplicação que o rewrite introduziria. Proibidos: DB de prod, merge sem CI green, editar Issuesin-progress` de outros, pular a pausa, Draft.
• .agents/skills/model-selection/SKILL.md (reescrever seções): remover ambiente Local/Zed, frontmatter model-local: e o mapeamento canônico model:→DeepSeek (tabelas + regras 3 e 8 + "Como aplicar" dual). Fica: cardápio só-Cursor (Composer 2.5 default; Grok 4.5 com effort obrigatório; Kimi K3 Low só exec bipartida), tabela pool×API Cloud, proibição -fast, heurística anti-viés, bipartição, "Issues muito complexas", e gates por fluxo atualizados: work-issue = não verifica modelo (contexto fixo; model: consultivo); agent-work-issue = pool fixou no spawn. Frontmatter description reescrito (sai "Toda Issue declara model-local"). Slug da Issue: model: único.
• .agents/skills/agent-work-issue/SKILL.md (edição pontual): remover "a base de execução de work-issue" (linha 14) e a linha da tabela de relação (work-issue | "Igual, mas claim + confirmação") → passar a descrever work-issue como fluxo humano próprio; Passo 2 (modelo) fica, com wording compatível com cardápio único. Passos 4–6 passam a referenciar o execution-pipeline.md compartilhado, com os deltas do ator pool (branch agent/<id>-<slug>, harden/optimize só sob gatilho, capture-review-debts autônomo com score ≥4, ManagePullRequest com draft: false).
• scripts/agent-claim.mjs (brief): linha model: → "(metadata consultiva — o fluxo work-issue não verifica modelo; o pool spawna nele; ver skill model-selection)"; linha "ausente" → "model: ausente — registrar slug único na Issue (gh issue edit; ver skill model-selection)". Resto do brief intacto (o claim continua existindo como script — transição + OPS33 o invoca).
• scripts/lib/agent-pool-prompt.mjs (uma linha): "a verificação assimétrica de work-issue não se aplica" → "o work-issue não verifica modelo — o spawn do pool já fixa o modelo". Header e demais strings intactos (unit tests pinam "NÃO rode agent:claim" e "agent-work-issue/SKILL.md" — não mudam).
• .opencode/commands/work-issue.md (description): "(claim → plano de implementação → pausa → execução → simplify → PR)" → "(Issue já claimada → plano de implementação → pausa → execução → simplify → PR)". Corpo e frontmatter model: intactos (guard opencodeCommands.unit.spec.ts só pina existência/name/$ARGUMENTS/model pin).
• docs/AGENT-OPS.md (linha Skills): "work-issue (humano: claim → impl plan → confirmação → execução)" → "(humano: Issue já claimada → impl plan → confirmação → execução)".
• docs/CHANGELOG-AGENTS.md: uma entrada no topo (entrega OPS32).
• Migration: sem migration. Access/Consent: N/A. UI: Impeccable A (skills de agente, sem superfície de produto).

Dados → forma

• N/A — sem superfície de dados.

Fases verificáveis

1. Skills (cardápio + desacoplamento + reescrita) — model-selection primeiro (fonte do cardápio), depois agent-work-issue (texto), depois work-issue (fluxo novo) e o command description. Verificação: grep repo-wide de model-local → só hits em docs/plans congelados de outras Issues (história) e no histórico do CHANGELOG — zero hits em código vivo/skills.
2. Scripts + docs — brief do claim, linha do pool prompt, AGENT-OPS, CHANGELOG. Verificação: unit tests do pool prompt e do guard opencodeCommands verdes sem edição; pnpm gate:fast.
3. Gates de entrega — pnpm gate:fast na iteração; entrega com pnpm push (não git push nu); /simplify completo no diff da sessão; capture-review-debts com gate humano.

Rabbit holes / Não escopo (engenharia)

• Editar a intenção (docs/plans/work-issue-paradigma-issue-claimada.md): imutável (Issue in-progress desde o claim).
• Texto de claim do worktree next / skill worktree-next-issue / scripts/worktree.mjs ("claim continua sendo pnpm agent:claim", linha 368): é o OPS33 (produtor do claim) — este item é o receptor.
• plan-issue: verificado — Passo 4 já sugere slug único, zero menções a model-local; única mudança: a linha da tabela de relação (Passo "Divisão com as skills") passa a dizer "Issue já claimada" (achado do /simplify).
• Mudar o comportamento do pool (claim coordenado, agent-pool-models.mjs, spawn): intacto — resolvePoolModel só consome model: (verificado no código; unit tests pinam slugs Cursor).
• Script novo para parsear $ARGUMENTS: a skill é um documento — o agente parseia os args; criar runtime seria guarda-costas.
• Editar impl plans congelados de outras Issues que citam model-local: (ex. porta-e2e-isolada-por-worktree-impl.md, c97-…-impl.md): história, não código.
• README.md / docs/roadmap.md: fluxo genérico ("claim → PR") permanece verdadeiro; sem mudança.

Riscos e mitigação

• Remover model-local quebra o spawn do pool? Não — agent-pool-models.mjs consome só model:; nenhum .mjs referencia model-local (grep). Mitigação: gate:fast cobre os unit do pool.
• Sessão /work-issue sem número da Issue (fallback humano): pergunta única com validação gh issue view (OPEN + in-progress) — nunca claim; 1 round resolve (decisão de produto do gate 2026-08-10).
• Drift do contrato com o OPS33: este item define o consumo (--issue <N> ou número no prompt); o OPS33 define a produção; contrato explícito nas duas skills (worktree-next-issue + work-issue) para o merge de OPS33 não quebrar.
• Sessão desta própria Issue (transição): já rodou pnpm agent:claim pelo fluxo antigo — transição esperada, documentada na intenção (claim fora da skill continua sendo pnpm agent:claim manual).

Aceite de engenharia

• Aceite de produto da intenção ainda coberto (skill sem claim/verificações; contexto do body; cardápio Cursor único; #582 fechado por eliminação da situação)
• Invariantes AGENTS/engineering-standards (nada de DB/access/Consent/migration; docs são a entrega)
• Testes de domínio previstos: unit existentes (pool prompt, opencode commands, worktree) verdes sem edição; sem unit novo (delta é texto/processo)
• Self-score decision-quality: 5/5 (decisões com rejeitadas; cabe no appetite; rabbit holes nomeados; reusa contrato extractPlanPath; intenção preservada)