edercnj/x-refine-story

Skill: Refine Story — TECHNICAL refinement (slim — ADR-0012)

Posição no pipeline: este é o refinamento técnico multi-persona, executado por história, após o desenho de arquitetura da feature (x-plan-architecture). É distinto do refinamento de negócio (x-refine-business), que ocorre antes da arquitetura. Orquestrado pelo Stage 7 de x-create-feature, mas também invocável diretamente por história.

Triggers

/x-refine-story story-XXXX-YYYY                        — full 4-phase technical refinement (interactive)
/x-refine-story story-XXXX-YYYY --non-interactive       — phases A+D only (no operator questions)
/x-refine-story story-XXXX-YYYY --feature-id 0069       — explicit feature ID (architecture gate source)

Parameters

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | STORY-ID | positional | (required) | story-XXXX-YYYY format | | --feature-id | String | auto-derived from STORY-ID prefix | 4-digit feature ID (source of the architecture gate / feature-state.json) | | --feature-id | String | alias (compat Fase 1) | 4-digit container ID; durante a Fase 1 a feature é o container físico | | --non-interactive | boolean | false | Skip Phase B+C (no questions); verdict based on Phases A+D only |

Output Contract

| Field | Type | Description | |-------|------|-------------| | storyId | String | Input story ID | | featureId | String | Resolved feature ID | | verdict | Enum | approved \| rejected \| tbd | | verdictHash | String | SHA-256 of verdict JSON (for CI drift detection) | | blockers | List<String> | NO-GO dimensions (empty if approved) | | refinedAt | ISO-8601 | Timestamp of final verdict | | artifactPath | String | Path to story markdown ## Refinement Verdict section |

Error Codes

| Exit | Code | Condition | |------|------|-----------| | 1 | STORY_NOT_FOUND | Story markdown not found at expected path | | 2 | FEATURE_STATE_MISSING | execution-state.json not found for feature | | 3 | PHASE_A_EMPTY | All personas returned empty gap-reports | | 4 | VERDICT_WRITE_FAILED | x-internal-update-status returned non-zero | | 5 | ARCHITECTURE_REQUIRED | Feature architecture not done — feature-state.json stages.planArch.status != DONE AND no tech-context.config.json/architecture-decisions-backend.md present (GATE 2) |

CRITICAL EXECUTION RULE

4 phases (A–D). ALL phases through Phase D are mandatory unless --non-interactive skips Phase B+C. Print >>> Phase X completed. Proceeding to Phase Y... between phases. >>> Phase D completed. Refinement verdict written. at end.

Workflow Overview

Phase A: SPECIALIST ANALYSIS  -> Resolve story path; launch 5 core + capability-aware
                                 contextual persona agents in parallel:
                                 PO, TechLead, Architect, Security, QA
                                 + (Database, API, Event, Observability,
                                 Integration-Resilience, Performance, DevOps, SRE) when
                                 the capability profile requires each domain.
                                 Each returns JSON gap-report (questions vs silent NO-GOs).
Phase B: CONSOLIDATE + Q&A    -> Dedup, group by 6 dimension categories; sequential SIP
                                 interview — one AskUserQuestion per gap, one at a time,
                                 with field type (boolean/enum/string) and recommended default;
                                 codebase exploration replaces asking when the answer is
                                 derivable from the repo. SKIPPED when --non-interactive.
Phase C: SPECIALIST REFINEMENT-> Re-launch persona agents with operator answers;
                                 collect proposedSections. SKIPPED when --non-interactive.
Phase D: ARCHITECT CONSOLIDATE -> Opus-tier architect agent merges sections, evaluates
                                  NO-GOs, produces final Refinement Verdict JSON.
                                  Dual-write: execution-state.json + story markdown.

Phases A–D

The detailed inline protocol for each phase (full persona Agent() prompts with dimension-specific NO-GO rules, telemetry sub-markers per persona, Phase B question grouping, Phase D consolidator algorithm with section merge targets and the verdict format) lives in references/full-protocol.md:

• Phase A — Parallel Specialist Analysis (§A): ARCHITECTURE GUARD (pre-check, GATE 2): Before launching persona agents, resolve the feature feature-state.json (from --feature-id/STORY-ID prefix → .aikittools/features/feature-XXXX*/feature-state.json). Check stages.planArch.status == "DONE"; if feature-state.json is absent (legacy backlog), fall back to verifying that the architecture artifacts exist (docs/architecture/architecture-decisions-backend.md and/or a feature tech-context.config.json). If neither condition holds → abort immediately with exit code 5 (ARCHITECTURE_REQUIRED) and message: "Technical story refinement blocked: feature <FEATURE_ID> architecture not done. Run /x-plan-architecture --feature-id <FEATURE_ID> first.". The technical refinement MUST consume architecture decisions, so it cannot precede them. After guard passes: probe the story markdown glob (→ STORY_NOT_FOUND on miss); read dimensions KP; resolve active personas via x-internal-evaluate-tech-context + x-internal-select-context-packs; emit ALL active persona Agent() calls as SIBLING tool calls in ONE assistant message (5 core always active + contextual specialists by capability); split returns into questions vs noGos (NO-GOs silent — never surface as questions, per D5); pre/post phase gates via x-internal-verify-phase-gates.
• Phase B — Consolidate & Operator Q&A (§B): SKIP when --non-interactive (set answers = {}). Otherwise: dedup by semantic similarity, group by 6 categories (Persona & Valor, Critérios de Aceite, Contratos & Interfaces, Métricas, Alternativas, Riscos), discard empties. Apply the Sequential Interview Protocol (SIP) from knowledge/shared/interview-protocol/sequential-interview-protocol.md: for each question in dependency-resolved order — (1) check if codebase exploration can answer it; (2) classify field type (boolean/enum/string); (3) call one AskUserQuestion with recommended default as first choice; (4) unlock dependent branches after each answer. Parse all answers into {Q<dim>: answer} map.
• Phase C — Parallel Specialist Refinement (§C): SKIP when --non-interactive (set proposedSections = {}). Otherwise: re-launch all active personas from Phase A in parallel (SIBLING calls) with each persona's own answers; collect proposedSections per dimension; merge into single map. Pre/post phase gates.
• Phase D — Architect Consolidation + Dual-Write (§D): opus-tier architect agent merges sections, evaluates NO-GOs vs operator answers, produces final Refinement Verdict JSON conforming to 7-dimension schema (value/persona/ac/contracts/metrics/alternatives/risks). Compute verdictHash (sha256sum). Dual-write: (1) x-internal-update-status INLINE-SKILL writes verdict to execution-state.json → VERDICT_WRITE_FAILED on non-zero; (2) Edit tool replaces/appends ## Refinement Verdict block in story markdown with verdictHash populated. Final phase gate with --expected-artifacts.

Output Summary

Print a concise summary:

x-refine-story completed for {STORY_ID}
  Verdict: <approved|rejected|tbd>
  Blockers: <none | list>
  Verdict hash: <hash>
  State file: .aikittools/features/feature-XXXX/execution-state.json (field: refinementVerdict)
  Story markdown: {storyPath} (section: ## Refinement Verdict)

Knowledge Pack References

Read src/knowledge/shared/refinement-decomposition/dimensions/knowledge.md (§Story Dimensions) — persona-to-dimension mapping and NO-GO rules. Read src/knowledge/shared/architecture-decisions/refinement-gate/knowledge.md for the gate contract and CI drift detection.

Integration Notes

• Consumed by: x-implement-story (Phase 0: checks refinementVerdict.status == "approved" AND scope == "story" via enforce-refinement-gate.sh hook — GATE 3).
• Prerequisite (GATE 2): Feature architecture must be done — feature-state.json stages.planArch.status == "DONE" (or architecture artifacts present for legacy backlogs). If not, this skill aborts with ARCHITECTURE_REQUIRED (exit 5). Run /x-plan-architecture --feature-id <FEATURE_ID> to unblock. The business refinement (x-refine-business) must also already be approved for this story (enforced upstream by x-create-feature Stage 4).
• Preceded by: x-refine-business --story (business verdict) then x-plan-architecture (feature architecture). Orchestrated per-story by x-create-feature Stage 7.
• Parallel with: x-refine-feature (distinct write paths; shared dimensions.md KP is read-only).
• Depends on: x-internal-update-status (INLINE-SKILL, Rule 13 Pattern 1), knowledge/shared/refinement-decomposition/dimensions/knowledge.md (KP, story-0069-0001).
• Verdict drift detection: verdictHash in state file vs verdictHash in story markdown is compared by audit-refinement-gate.sh (story-0069-0006). Drift fails CI with REFINEMENT_VERDICT_DRIFT.
• Capability-aware routing: Active personas are resolved from the tech context (x-internal-evaluate-tech-context) and selected context packs (x-internal-select-context-packs) before Phase A dispatch.
• Re-run idempotency: Running x-refine-story again on an approved story replaces the verdict. This is intentional — re-refinement after story changes should update the verdict.
• Scope discriminator: This skill always writes scope: "story". The gate enforce-refinement-gate.sh checks both status == "approved" AND scope == "story" to unblock x-implement-story. Feature-level scope: "feature" verdicts do NOT unblock story-level gates.

Full Protocol

Minimum viable contract above. Detailed phase-by-phase workflow (full 7 persona Agent() prompts with dimension-specific NO-GO rules, telemetry sub-markers per persona, Phase B grouping categories table + dedup heuristic, Phase D architect consolidator prompt with section merge targets, verdict JSON schema + Refinement Verdict markdown format) lives in references/full-protocol.md per ADR-0012 (skill body slim-by-default).

Decision Record

ADR-0022 — Refinement Gate Convention: Mandates multi-persona dispatcher + PreToolUse hook as the blocking refinement gate before implementation.