edercnj/x-internal-plan-arch-story

Skill: x-internal-plan-arch-story

Purpose

Skill interna (não-chamável) que gera o plano de arquitetura por story (arch-story-XXXX-YYYY.md).

Princípio central — herança, não re-derivação. As decisões macro de arquitetura (stack, versões, estilo arquitetural, NFRs de baseline, observabilidade, resiliência, compliance) já foram tomadas no nível feature/capability/product pela skill canônica x-plan-architecture e estão registradas em docs/architecture/architecture-decisions-backend.md + tech-context.config.json. Esta skill herda essas decisões por referência e produz somente os deltas específicos da story: a fatia de componentes tocada, os sequence diagrams do fluxo, o data model da story e a análise de impacto.

Isso elimina a duplicação histórica em que o plano por story re-derivava o que já vinha do nível feature.

When to Use (apenas pelo pipeline)

Esta skill não é invocada diretamente pelo usuário. É chamada por:

• x-internal-build-story-plan (Step 1A) — gera arch-story-*.md consumido pelos subagents 1B–1F.
• x-implement-story (Phase 1, Step 1A) — quando o plano de arquitetura da story ainda não existe.

A skill user-invocable de arquitetura é x-plan-architecture (níveis product/capability/feature).

Triggers

Skill(skill: "x-internal-plan-arch-story", args: "--story-id story-XXXX-YYYY --feature-id XXXX")
Skill(skill: "x-internal-plan-arch-story", args: "{STORY_PATH}")

Parameters

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | --story-id | String | required* | Story identifier (story-XXXX-YYYY) | | --feature-id | String | required* | Feature identifier (XXXX) | | argument | String | — | Alternativamente, caminho do arquivo da story ({STORY_PATH}) ou nome de feature |

* Quando invocada com {STORY_PATH}, deriva story-id/feature-id do caminho.

Decision Tree

Avalie o escopo da mudança para determinar o nível do plano:

| Condição | Nível do Plano | |-----------|-----------| | Novo serviço / nova integração / mudança de contrato / mudança de infra | Full | | Nova feature, sem mudança de contrato ou infra | Simplified | | Bug fix / refactor / docs-only | Skip |

• Full: novo serviço/módulo, nova integração externa (DB, broker, API terceira), mudança de contrato público (REST, gRPC, GraphQL, schema de evento) ou mudança de topologia de infra.
• Simplified: nova feature em serviço existente sem mudança de contrato/infra — gera apenas as seções afetadas.
• Skip: bug fix sem impacto arquitetural, refactoring interno, ou mudança só de documentação. Reporta "Architecture plan not needed for this change" e encerra.

Workflow

1. PRE-CHECK   -> Idempotência (reusa plano fresco)
2. TEMPLATE    -> Carrega _TEMPLATE-ARCHITECTURE-PLAN.md (fallback inline)
3. READ        -> Lê requisitos da story
4. EVALUATE    -> Determina nível (Full/Simplified/Skip)
5. INHERIT     -> Carrega architecture-decisions-backend.md + tech-context (HERANÇA — obrigatório)
6. CONTEXT     -> Lê apenas os assets relevantes aos deltas da story
7. GENERATE    -> Gera SOMENTE as seções de delta da story
8. VALIDATE    -> Verifica completude das seções de delta

Step 1 — Idempotency Pre-Check

1. Resolver o path de saída:
   .aikittools/features/feature-XXXX/plans/arch-story-XXXX-YYYY.md
2. SE o arquivo NÃO existe → gerar.
3. SE existe:
   a. story_mtime = mtime do arquivo da story; plan_mtime = mtime do plano
   b. SE story_mtime <= plan_mtime → reusar (NÃO regenerar).
   c. SE story_mtime > plan_mtime → regenerar (plano stale).

| Condição | Ação | Log | |-----------|--------|-----| | Plano não existe | Gerar novo | Generating architecture plan for {story} | | Plano existe, story não modificada | Reusar | Reusing existing architecture plan from {date} | | Plano existe, story modificada após o plano | Regenerar | Regenerating stale architecture plan for {story} |

Step 2 — Template Loading

1. Verificar `src/templates/_TEMPLATE-ARCHITECTURE-PLAN.md`.
2. SE existe → usar como estrutura de saída.
3. SE não existe → log WARNING "Template not found, using inline format" e usar a estrutura inline abaixo (sem interromper).

Step 3 — Read Story/Feature Requirements

Ler o arquivo da story (ou descrição passada como argumento). Extrair: escopo, acceptance criteria, integrações, NFRs específicos, constraints.

Step 4 — Evaluate Decision Tree

Determinar Full / Simplified / Skip. Em Skip: reportar "Architecture plan not needed for this change" e encerrar (exit 0).

Step 5 — Inherit Feature-Level Architecture (OBRIGATÓRIO — herança)

Este é o passo que substitui a antiga re-derivação de stack/versões/NFR. Não re-decidir o que já está registrado no nível feature; referenciar.

ARCH_BACKEND_FILE="docs/architecture/architecture-decisions-backend.md"
HAS_ARCH_DECISIONS=false
[ -f "$ARCH_BACKEND_FILE" ] && HAS_ARCH_DECISIONS=true

| Condição | Comportamento | |-----------|----------| | Arquivo de decisões existe | Ler integralmente → ARCHITECTURE_DECISIONS; HAS_ARCH_DECISIONS=true | | Arquivo ausente | ARCHITECTURE_DECISIONS=null; log INFO: architecture-decisions-backend.md não encontrado — execute /x-plan-architecture para gerá-lo |

Quando HAS_ARCH_DECISIONS=true, a skill DEVE:

• Ler docs/architecture/architecture-decisions-backend.md por completo.
• Ler cada path de pattern/knowledge listado na seção "Patterns e Knowledge Obrigatórios" e incorporar o conteúdo.
• Herdar (não recriar) Technology Stack, Technology Versions, Architecture Decisions macro, NFR de baseline, observabilidade e resiliência. No plano da story, essas seções viram referências curtas ao arquivo de decisões (ver "Output Structure" → seção "Decisões Herdadas").

Carregue também o perfil técnico (quando o config existir):

Skill(skill: "x-internal-evaluate-tech-context", args: "--phase plan --capabilities <architecture-scoped-capabilities>")

• Se techProfile.inputsUsed.config = true → TECH_CONTEXT = techProfile.technology.
• Caso contrário → log WARNING: tech-context.config.json não encontrado e TECH_CONTEXT = null.

Step 6 — Read Context (apenas o necessário para os deltas)

Resolva packs canônicos com um conjunto de capabilities derivado do escopo (anti-inflação):

• Sempre inclua architecture.
• Adicione api,security,observability,devops,resilience,compliance apenas quando justificado pelo escopo da story.
• Nunca amplie capabilities "por precaução".

Skill(skill: "x-internal-select-context-packs", args: "--phase plan --capabilities <architecture-scoped-capabilities>")
Skill(skill: "x-internal-select-knowledge",     args: "--kind technical --phase plan --capabilities <architecture-scoped-capabilities>")

Leia os assets required e os recommended relevantes aos deltas da story (union dos dois seletores). Para Simplified, mantenha apenas Architecture + assets diretamente ligados às seções afetadas.

Conteúdo explícito de pattern (anti-alucinação): para cada componente/endpoint/query/integração nova ou alterada por esta story, inclua o trecho literal do pattern aplicável (ex.: parâmetros mínimos de connection pool, status codes HTTP obrigatórios, parâmetros de circuit breaker, spans/métricas obrigatórios). Formato:

> **Pattern aplicado** ([caminho/do/pattern.md](caminho/do/pattern.md)):
> ```
> <trecho literal copiado do arquivo de pattern>
> ```

Step 7 — Generate Architecture Plan (deltas da story)

Lance um único subagent general-purpose com model: "opus" (raciocínio arquitetural profundo justifica Opus). Gere apenas as seções de delta abaixo (as decisões macro são herdadas via referência).

Agent(
  subagent_type: "general-purpose",
  model: "opus",
  description: "Gera o plano de arquitetura (deltas) da story",
  prompt: "<ver blockquote abaixo>"
)

Você é um Senior Architect gerando o plano de arquitetura por story para {{PROJECT_NAME}}.

Step 1 — Template: Leia src/templates/_TEMPLATE-ARCHITECTURE-PLAN.md. Se ausente, use a estrutura inline da skill.

Step 2 — Story: Leia o arquivo da story. Extraia escopo, acceptance criteria, integrações, NFRs específicos, constraints.

Step 3 — Decision tree: Determine Full/Simplified/Skip. Em Skip, reporte e pare.

Step 4 — HERANÇA (obrigatório): Leia docs/architecture/architecture-decisions-backend.md integralmente e os patterns listados em "Patterns e Knowledge Obrigatórios". Não re-decida stack/versões/NFR baseline/observabilidade/resiliência — referencie o arquivo de decisões. Cite o caminho explicitamente no preâmbulo da seção "Decisões Herdadas".

Step 5 — Conteúdo explícito de pattern (anti-alucinação): para cada componente/endpoint/integração NOVO ou ALTERADO por esta story, inclua o trecho literal do pattern aplicável (não apenas referência genérica).

Step 6 — Gere SOMENTE as seções de delta da story:

1. Executive Summary — um parágrafo do que a story muda arquiteturalmente.
2. Decisões Herdadas — referência curta a architecture-decisions-backend.md (stack, versões, estilo, NFR baseline). NÃO copiar tabelas inteiras; apontar o caminho e listar só o que é relevante à story.
3. Component Diagram — Mermaid graph TD da fatia de componentes tocada pela story.
4. Sequence Diagrams — Mermaid sequenceDiagram dos fluxos da story (happy path + erro principal). Este é o conteúdo genuinamente específico da story.
5. External Connections — tabela System | Protocol | Purpose | SLO, apenas conexões novas/alteradas.
6. Architecture Decisions (mini-ADRs) — apenas decisões específicas desta story (não repetir as macro).
7. Data Model — erDiagram ou tabela, apenas entidades novas/alteradas (skip se sem mudança de dados).
8. Impact Analysis — serviços afetados, plano de migração, estratégia de rollback, riscos.
9. Deltas de NFR/Observabilidade/Resiliência — apenas o que esta story acrescenta ao baseline herdado (skip se nenhum).

Step 7 — Origin marker + salvar (obrigatório): Prepend do frontmatter YAML no topo:

---
generated-by: x-internal-plan-arch-story@$(git rev-parse HEAD 2>/dev/null || echo "unknown")
generated-at: $(date -u +%Y-%m-%dT%H:%M:%SZ)
story-id: ${STORY_ID}
---

Em seguida, escreva o documento. Output path:

.aikittools/features/feature-XXXX/plans/arch-story-XXXX-YYYY.md

Step 8 — Validar: parse das seções de delta; conditional sections (Data Model, External Connections, Deltas de NFR) marcadas N/A - não aplicável a esta story quando vazias; log Architecture plan: X/Y seções de delta presentes.

Convenções: diagramas em Mermaid; mini-ADRs no formato inline (Context/Decision/Rationale/Consequences/Story Reference); tabelas em GitHub-flavored Markdown; alvos de NFR mensuráveis.

Step 8 — Validate Sections Post-Generation

1. Parse de headings H2 (## Section Name).
2. Para cada seção de delta mandatória ausente → WARNING com instrução de completar.
3. Para conditional sections (Data Model, External Connections, Deltas de NFR): ausência é OK quando não aplicável (marcar N/A).
4. Gate de herança: SE HAS_ARCH_DECISIONS=true E a seção "Decisões Herdadas" estiver ausente ou sem referência ao arquivo → WARNING: ARCH_INHERITANCE_NOT_REFERENCED.
5. Log: "Architecture plan: X/Y seções de delta presentes".

Output Structure (seções de delta)

| # | Seção | Mandatória | Conditional | |---|---------|-----------|-------------| | 1 | Header + origin marker | Sim | -- | | 2 | Executive Summary | Sim | -- | | 3 | Decisões Herdadas (ref. a architecture-decisions-backend.md) | Sim | quando HAS_ARCH_DECISIONS=true | | 4 | Component Diagram (fatia da story) | Sim | -- | | 5 | Sequence Diagrams (fluxos da story) | Sim | -- | | 6 | External Connections | Sim | apenas conexões novas/alteradas | | 7 | Architecture Decisions (mini-ADRs específicos) | Sim | -- | | 8 | Data Model | Condicional | database != none e há mudança de dados | | 9 | Impact Analysis | Sim | -- | | 10 | Deltas de NFR/Observabilidade/Resiliência | Condicional | quando a story acrescenta ao baseline |

Não duplicar: Technology Stack, Technology Versions, Technology Decisions completas, NFR baseline, estratégias macro de observabilidade/resiliência não são regeradas aqui — são herdadas de architecture-decisions-backend.md e referenciadas na seção "Decisões Herdadas".

Output Path

.aikittools/features/feature-XXXX/plans/arch-story-XXXX-YYYY.md

Origin Marker (mandatório)

Todo plano gerado DEVE começar com:

---
generated-by: x-internal-plan-arch-story@<40-char-git-sha>
generated-at: <ISO-8601-UTC>
story-id: <story-id>
---

• SHA: git rev-parse HEAD 2>/dev/null || echo "unknown"
• Timestamp: date -u +%Y-%m-%dT%H:%M:%SZ

Obrigatório pela validação de integridade de execução (Rule 24). Artefatos sem este bloco falham no audit de CI com EIE_EVIDENCE_MISSING.

Mini-ADR Format

### ADR-NNN: {Decision Title}

**Status:** Proposed | Accepted | Deprecated | Superseded

**Context:** {força que motiva a decisão — 2-3 frases}

**Decision:** {a mudança proposta/adotada — 1-2 frases}

**Rationale:** {por que esta opção sobre as alternativas; trade-offs}

**Consequences:**
- Positive: {benefícios}
- Negative: {trade-offs ou riscos}

**Story Reference:** {STORY-ID}

Regras: numerar sequencialmente no documento; cada ADR referencia a story de origem; registrar apenas decisões específicas da story (decisões macro ficam no nível feature).

Exit Codes

| Code | Name | Condition | | :--- | :--- | :--- | | 0 | SUCCESS | Plano gerado, reusado (idempotência) ou Skip | | 1 | STORY_NOT_FOUND | Arquivo da story não encontrado | | 2 | EXECUTION_ERROR | Falha de geração (subagent ou escrita) |

Error Handling

| Cenário | Ação | |----------|--------| | Story file not found | Abortar com Story file not found: {path} (exit 1) | | Template not found | WARNING, fallback para estrutura inline | | architecture-decisions-backend.md ausente | INFO; gerar plano sem herança (degradado) e sugerir /x-plan-architecture | | Knowledge/pattern não encontrado | WARNING, continuar com os disponíveis | | Subagent falha | Abortar com detalhes (exit 2) | | Seção de delta mandatória ausente | WARNING com instrução de completar |

Planning Status Propagation (Rule 22)

V2-gated: só executa quando SchemaVersionResolver.resolve(.aikittools/features/feature-XXXX/execution-state.json) == V2. Features v1: skip silencioso (Rule 19).

Após escrever arch-story-XXXX-YYYY.md, esta skill verifica o status da story. O plano de arquitetura não dirige a transição Pendente → Planejada por si só — isso pertence a x-plan-story (invariante de single-writer da Rule 22). Se a story ainda estiver Pendente quando o plano for gerado isoladamente, transicionar para Planejada aqui (idempotente se já Planejada).

Passos (antes do commit final):

1. Detectar v2 via SchemaVersionResolver no execution-state.json do feature. Se v1: skip.

2. Ler status atual:

   CURRENT=$(sed -n 's/^\*\*Status:\*\* *//p' .aikittools/features/feature-XXXX/story-XXXX-YYYY.md | head -1)
   

   Resultado vazio → linha **Status:** ausente → abortar (invariante de source-of-truth, RULE-046-01).

3. Se CURRENT == "Pendente", escrever Planejada (reescreve a única linha de cabeçalho **Status:**):

   perl -i -pe 's/^\*\*Status:\*\* .*/\*\*Status:\*\* Planejada/ if /^\*\*Status:\*\*/' .aikittools/features/feature-XXXX/story-XXXX-YYYY.md
   

   Se já Planejada: no-op idempotente.

4. Stage e commit via x-commit-changes:

   git add .aikittools/features/feature-XXXX/story-XXXX-YYYY.md .aikittools/features/feature-XXXX/plans/arch-story-XXXX-YYYY.md
   

   Então:

   Skill(skill: "x-commit-changes", args: "docs(story-XXXX-YYYY): add architecture plan + update status to Planejada")
   

Fail-loud: exit não-zero do CLI → abortar a skill (RULE-046-08).

Integration Notes

| Skill | Relationship | Context | |-------|-------------|---------| | x-plan-architecture | herda de | Decisões macro (stack/versões/NFR/patterns) vêm de architecture-decisions-backend.md gerado por ela | | x-internal-build-story-plan | called by | Step 1A — produz arch-story-*.md consumido pelos Steps 1B-1F | | x-implement-story | called by | Phase 1 Step 1A — gera o plano quando ausente | | x-review-tech-lead | reads output of | Lê o arch-story-*.md | | x-generate-adr | reads output of | Extrai mini-ADRs inline do arch-story-*.md | | x-update-architecture | followed by | Atualiza a documentação de arquitetura após implementação |

References

• x-plan-architecture — skill canônica de arquitetura (níveis product/capability/feature) que produz as decisões herdadas aqui.
• PIPELINE-FLOWS.md — mapa do pipeline plan/implement/review.