edercnj/x-refine-feature

Skill: Refine Feature (slim — ADR-0012)

Purpose

Perform multi-persona strategic technical refinement on a Feature artifact. Ensures the feature specification is technically complete and coherent. This is the technical counterpart to x-refine-business (the PO-centric business refinement). In the feature-as-unit pipeline it is optional at the feature level — the primary technical refinement runs per story (x-refine-story, Stage 7 of x-create-feature) after architecture.

Phase E disabled (Fase 1): This skill no longer creates a feature container. Story/feature/map generation moved to x-create-feature Stage 3 (post business approval). See Phase E below.

Triggers

/x-refine-feature docs/specs/SPEC-my-feature-v1.md    — full 4-phase refinement (interactive)
/x-refine-feature feature-0003                          — resolve feature by ID (under .aikittools/**)
/x-refine-feature <feature-file> --non-interactive      — phases A+D only (no operator questions)
/x-refine-feature <feature-file> --dry-run              — run A-D without writing markdown or state

Parameters

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | FEATURE-FILE\|FEATURE-ID | positional | (required) | Feature markdown file path, or feature ID resolvable under .aikittools/** or docs/specs/** | | --feature-id | String | auto (next available) | 4-digit feature ID to assign to the generated container in Phase E | | --capability-file | Path | — | Capability artifact to enrich inherited RNFs in Phase E | | --product-file | Path | — | Product artifact to extend inherited RNFs in Phase E | | --non-interactive | boolean | false | Skip Phase B+C (no operator questions); verdict based on Phases A+D only | | --dry-run | boolean | false | Execute Phases A–D without writing markdown, state, or triggering Phase E |

Output Contract

| Field | Type | Description | |-------|------|-------------| | featureId | String | Resolved feature ID or file path | | 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 feature markdown ## Refinement Verdict section | | featureCreated | String | null | Feature container path created in Phase E (null when verdict != approved or --dry-run) |

Error Codes

| Exit | Code | Condition | |------|------|-----------| | 1 | FEATURE_NOT_FOUND | Feature markdown not found at expected path | | 2 | FEATURE_STATE_MISSING | execution-state.json not found for feature (create if absent) | | 3 | PHASE_A_EMPTY | All personas returned empty gap-reports | | 4 | VERDICT_WRITE_FAILED | x-internal-update-status returned non-zero | | — | ~~FEATURE_CREATE_FAILED~~ | Removed — Phase E (feature creation) is disabled; story/feature creation owned by x-create-feature Stage 3 |

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: STRATEGIC ANALYSIS   -> Resolve feature path/state; launch 5 parallel persona agents
                                  (PO, TechLead, Architect, Security, QA).
                                  Each returns JSON gap-report (questions vs silent NO-GOs).
Phase B: CONSOLIDATE + Q&A    -> Dedup, group by category (Escopo/Personas/Valor/Alternativas/
                                  RNFs/Riscos); 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: STRATEGIC REFINEMENT -> Re-launch persona agents with operator answers; collect
                                  proposedSections per persona. 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 + feature markdown.

Phases A–D

The detailed inline protocol for each phase lives in references/full-protocol.md:

• Phase A — Parallel Strategic Analysis (§A): resolve feature path via glob docs/specs/**/*<FEATURE-ID>*.md OR .aikittools/features/**/*.md (→ FEATURE_NOT_FOUND on miss); probe or create execution-state.json; read feature dimensions KP; emit ALL 5 persona Agent() calls as SIBLING tool calls in ONE assistant message (PO, TechLead, Architect, Security, QA); split returns into questions vs noGos (NO-GOs silent — never surface as questions); 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 strategic categories (Escopo, Personas & Jornadas, Hipótese de Valor, Alternativas, RNFs, 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 Strategic Refinement (§C): SKIP when --non-interactive (set proposedSections = {}). Otherwise: re-launch persona agents 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 (scope/personas/value/alternatives/rnfs/risks/success-criteria). Compute verdictHash (sha256sum). Dual-write (skipped on --dry-run): (1) Write tool writes the refinement verdict to .aikittools/features/<FEATURE-SLUG>/execution-state.json (creating or updating; schema: {scope:"feature", featureId:"<FEATURE-SLUG>", refinementVerdict:{...}}) → VERDICT_WRITE_FAILED if write fails; (2) Edit tool replaces/appends ## Refinement Verdict block in feature markdown with verdictHash populated. Final phase gate with --expected-artifacts.

Phase E — Post-Approval Feature Creation (DISABLED — moved to x-create-feature)

feature-as-unit (Fase 1): Phase E is disabled. A criação de feature/histórias/mapa passou a ser responsabilidade do Stage 3 de x-create-feature (após o refinamento de negócio via x-refine-business), não mais um efeito colateral do refinamento. Manter a criação aqui duplicaria a geração de histórias. featureCreated no Output Contract é sempre null nesta skill agora.

When invoked standalone, this skill performs only Phases A–D (the multi-persona refinement and verdict write). It does not create a feature container or stories. Story creation is orchestrated centrally by x-create-feature.

Output Summary

Print a concise summary:

x-refine-feature completed for <FEATURE-FILE|FEATURE-ID>
  Verdict: <approved|rejected|tbd>
  Blockers: <none | list>
  Verdict hash: <hash>
  State file: <feature-execution-state-path> (field: refinementVerdict.scope=feature)
  Feature markdown: {featurePath} (section: ## Refinement Verdict)
  Next step: continue via /x-create-feature (Stage 3 creates stories after business approval)

Knowledge Pack References

Read src/knowledge/shared/refinement-decomposition/dimensions/knowledge.md (§Feature 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. Additionally, invoke Skill(skill: "x-internal-select-knowledge", args: "--kind domain --stage refine [--segment <seg>] [--product <prod>]") and read every required path — canonical dynamic source for refinement-stage domain knowledge.

Integration Notes

• Counterpart: x-refine-business (the PO-centric business refinement that runs before architecture). This skill is the technical refinement.
• Preceded by: x-create-feature (Mode A — the orchestrator drives ideation, business refinement, story creation, and architecture before any technical refinement).
• Phase E: disabled — no longer creates a feature container (story/feature creation owned by x-create-feature Stage 3).
• Parallel with: x-refine-story (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).
• Verdict drift detection: verdictHash in state file vs verdictHash in feature markdown is compared by audit-refinement-gate.sh. Drift fails CI with REFINEMENT_VERDICT_DRIFT.
• Re-run idempotency: Running x-refine-feature again on an approved feature replaces the verdict. Phase E is idempotent — if a container already exists for this feature, it is skipped (log WARNING).
• Scope discriminator: This skill always writes scope: "feature". Does NOT unblock story gates.

Full Protocol

Minimum viable contract above. Detailed phase-by-phase workflow (full 5 persona Agent() prompts with dimension-specific NO-GO rules, telemetry sub-markers per persona, Phase B dedup heuristic + question grouping table, 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. This skill extends the gate to the Feature layer, ensuring Feature → Stories flow is gated by approval.