edercnj/x-refine-business

Skill: x-refine-business (Business Refinement — single persona PO)

Purpose

Executar o refinamento de NEGÓCIO de uma feature OU de uma história, sob a ótica exclusiva do Product Owner. É um passo leve que valida se a necessidade de negócio está 100% entendida antes de avançar: problema, hipótese de valor, persona primária, limites de escopo (in/out), critérios de aceite de negócio e KPI de sucesso.

Esta skill NÃO entra em contratos de dados, arquitetura, segurança técnica, performance ou decomposição em tasks — isso é responsabilidade do refinamento técnico (x-refine-feature / x-refine-story), que roda depois do desenho de arquitetura.

Posição no pipeline (feature-as-unit): ideate → refine-business (feature) → criar histórias → refine-business (histórias) → [GATE] arquitetura → refine-técnico (histórias) → implement. Esta skill cobre os dois passos de refine-business (feature e história), orquestrados por x-create-feature.

Gate contract (discriminador de escopo): Esta skill escreve refinementVerdict.scope = "business-feature" ou "business-story". Esses verdicts NÃO destravam os gates técnicos (enforce-refinement-gate.sh exige scope: "feature"/"story"). Eles destravam apenas a progressão de estágios dentro de x-create-feature.

When to Use

• Logo após a ideação da feature, para confirmar o entendimento de negócio antes de criar histórias.
• Após a criação automática das histórias, para validar o valor de negócio de cada história, uma a uma.
• Sempre que o valor/escopo de negócio de uma feature ou história mudar e precisar de reaprovação.

Triggers

/x-refine-business --feature docs/specs/SPEC-pagamentos-v1.md   — refino de negócio da feature
/x-refine-business --feature FEAT-0007                          — resolve a feature por ID
/x-refine-business --story story-0007-0003 --feature-id 0007    — refino de negócio de uma história
/x-refine-business --story story-0007-0003 --non-interactive    — verdict sem perguntas ao operador
/x-refine-business --feature <spec> --dry-run                   — roda sem gravar estado/markdown

Parameters

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | --feature <spec-or-id> | String | Condicional | Caminho da spec ou ID da feature. Exclusivo com --story. | | --story <story-id> | String | Condicional | ID da história (story-XXXX-YYYY). Exclusivo com --feature. | | --feature-id <id> | String | Não | ID da feature dona da história (deriva o feature-state.json alvo). Auto-derivado de story-XXXX-* quando ausente. | | --non-interactive | Flag | Não | Pula a entrevista SIP; verdict baseado apenas na análise PO. | | --dry-run | Flag | Não | Executa a análise sem gravar feature-state.json nem o markdown. |

Exatamente um entre --feature e --story deve ser informado.

Output Contract

| Field | Type | Description | |-------|------|-------------| | target | String | ID/caminho da feature ou história refinada | | scope | Enum | business-feature \| business-story | | verdict | Enum | approved \| rejected \| tbd | | verdictHash | String | SHA-256 do JSON do verdict (detecção de drift) | | blockers | List<String> | Dimensões NO-GO de negócio (vazio se approved) | | openQuestions | List<String> | IDs de perguntas técnicas registradas (não bloqueiam) | | refinedAt | ISO-8601 | Timestamp do verdict | | statePath | String | feature-state.json mutado |

Error Codes

| Exit | Code | Condition | |------|------|-----------| | 1 | TARGET_NOT_FOUND | Spec/feature/história não encontrada no caminho esperado | | 2 | FEATURE_STATE_MISSING | feature-state.json ausente para a feature alvo | | 3 | INVALID_USAGE | Nenhum ou ambos --feature/--story informados | | 4 | VERDICT_WRITE_FAILED | x-internal-update-status retornou não-zero |

CRITICAL EXECUTION RULE

4 passos (PO-Analyze → SIP Q&A → Verdict → Persist). O passo SIP é pulado com --non-interactive. Imprima >>> Passo X concluído. entre passos. Ao final, >>> Business refinement verdict gravado.

Dimensões de negócio (PO)

A análise cobre 6 dimensões de negócio (sem entrar no técnico):

1. Problema — qual dor/oportunidade de negócio justifica o item; está clara e específica?
2. Hipótese de valor — qual resultado mensurável se espera; o valor é tangível e não puramente técnico?
3. Persona & jornada — persona primária e contexto de uso; a jornada de negócio está completa?
4. Escopo in/out — limites explícitos; o que está deliberadamente fora?
5. Critérios de aceite de negócio — observáveis pelo usuário/negócio (não testes técnicos/contratos).
6. KPI de sucesso — métrica prioritária e como será medida.

Cada dimensão recebe um veredito GO / NO-GO. Qualquer NO-GO de negócio → verdict = rejected com a dimensão listada em blockers. Tudo GO → approved. Lacuna não resolvível sem terceiros → tbd.

Workflow Overview

Passo 1 — PO-ANALYZE
  - Resolver alvo:
      --feature: glob docs/specs/**/*<id|slug>*.md OU .aikittools/features/**/*.md  (→ TARGET_NOT_FOUND)
      --story:   glob .aikittools/**/story-<id>.md                                   (→ TARGET_NOT_FOUND)
  - Derivar feature-id (de --feature-id ou de story-XXXX-*) e localizar feature-state.json (→ FEATURE_STATE_MISSING).
  - Ler o artefato e avaliar as 6 dimensões de negócio. Explorar a spec/feature antes de perguntar.
  - Produzir, por dimensão: {gap?, question?, noGo?}.

Passo 2 — SIP Q&A  (pulado com --non-interactive)
  - Aplicar o Sequential Interview Protocol: uma AskUserQuestion por lacuna, uma de cada vez.
  - NUNCA perguntar em texto puro; sempre AskUserQuestion com default recomendado em primeiro lugar.
  - Pergunta TÉCNICA que o PO não sabe responder → registrar em openQuestions[] (audience: tech), NÃO bloquear.

Passo 3 — VERDICT
  - Consolidar GO/NO-GO das 6 dimensões → {scope, verdict, blockers, verdictHash, refinedAt}.
  - verdictHash = sha256 do JSON canônico do verdict.

Passo 4 — PERSIST  (pulado com --dry-run)
  - feature: x-internal-update-status grava stages.refineBusinessFeature.verdict + openQuestions no feature-state.json.
  - story:   x-internal-update-status grava stages.refineBusinessStories.stories.<story-id>.{status,verdict}
             e o bloco "## Business Refinement Verdict" no markdown da história (dual-write).

Persistência (via x-internal-update-status)

Toda mutação de estado passa pelo mutador canônico (disciplina de flock), igual ao restante do ciclo:

Feature:

Skill(skill: "x-internal-update-status",
      args: "--feature-state .aikittools/features/feature-<slug>/feature-state.json \
             --set stages.refineBusinessFeature.status=DONE \
             --set stages.refineBusinessFeature.verdict=<verdict>")

História (dual-write — estado + markdown):

Skill(skill: "x-internal-update-status",
      args: "--feature-state .aikittools/features/feature-<slug>/feature-state.json \
             --set stages.refineBusinessStories.stories.<story-id>.status=DONE \
             --set stages.refineBusinessStories.stories.<story-id>.verdict=<verdict>")

Em seguida, Edit insere/atualiza no markdown da história um bloco separado do verdict técnico:

## Business Refinement Verdict

- Scope: business-story
- Verdict: <approved|rejected|tbd>
- Blockers: <none | lista>
- Verdict hash: <hash>
- Refined at: <ISO-8601>

O bloco ## Business Refinement Verdict é distinto do ## Refinement Verdict (técnico). Os dois coexistem no markdown da história sem colisão; o gate técnico só lê o segundo.

Output Summary

x-refine-business concluído para <target>
  Scope:   <business-feature|business-story>
  Verdict: <approved|rejected|tbd>
  Blockers: <none | lista>
  Open questions (técnicas, não bloqueiam): <none | ids>
  State:   .aikittools/features/feature-<slug>/feature-state.json
  Próximo passo: <criar histórias | próxima história | desenho de arquitetura>

Knowledge Pack References

• knowledge/shared/interview-protocol/sequential-interview-protocol.md — protocolo SIP (uma pergunta por vez).
• knowledge/shared/refinement-decomposition/dimensions/knowledge.md (§ dimensões de Produto/Valor) — guia de NO-GO de negócio. Leia apenas as dimensões de negócio; ignore as dimensões técnicas (cobertas no refino técnico).

Integration Notes

• Caller principal: x-create-feature (Modo A) — invoca esta skill no Stage 2 (feature) e no Stage 4 (histórias, uma a uma, com estado).
• Precede: criação automática de histórias (após aprovação de negócio da feature) e o desenho de arquitetura (após aprovação de negócio de todas as histórias).
• Distinta de: x-refine-feature / x-refine-story — estas são o refinamento técnico multi-persona, pós-arquitetura, por história. Esta skill é PO-only e pré-arquitetura.
• Depende de: x-internal-update-status (mutador canônico, Rule 13 Pattern 1 — INLINE-SKILL).
• Scope discriminator: escreve business-feature/business-story; não destrava gates técnicos.