edercnj/x-fix-bug

Context Management

Record only compact envelopes from x-implement-task (status/taskId/commitSha/coverage*) — no full TDD logs. Read story file once in Phase 0.B2 via x-internal-load-story-context. Use x-internal-select-context-packs as the canonical source for implementation packs. Delegate every state mutation to x-internal-update-status.

Context-budget: high — Phase 3 (inside x-internal-implement-story) requires 13+ sequential skill calls. Emit only compact envelopes and drop intermediate TDD logs from context immediately after commit to prevent overflow.

Skill: Bug Story Implementation (Thin Orchestrator — ADR-0012)

Orchestrate a bug story end-to-end via delegation. Handles bug-specific pre-checks (BUG_GATE, ordering enforcement, context loading) then delegates Phases 0.3→3 to the shared engine x-internal-implement-story. Zero direct git/gh/mvn calls.

This skill handles bug stories ONLY. For feature stories, use /x-implement-story.

Triggers

• /x-fix-bug --bug-id bug-000042 --story story-01-regression-test — fix regression-test story
• /x-fix-bug --bug-id bug-000042 --story story-02-fix — fix the main fix story (requires story-01 Concluída)
• /x-fix-bug --bug-id bug-000042 --story story-01-regression-test --resume — resume from execution-state.json
• /x-fix-bug --bug-id bug-000042 --story story-02-fix --worktree — standalone worktree mode
• /x-fix-bug --bug-id bug-000042 --story story-01-regression-test --interactive — opt-in gate menus

Review Policy — MANDATORY — NON-NEGOTIABLE: Specialist (x-review-specialist) + Tech-Lead (x-review-pr) reviews in Phase 3 MUST execute unless --skip-verification / --skip-review; silent omission is a PROTOCOL_VIOLATION.

Parameters

| Flag | Type | Default | Description | |------|------|---------|-------------| | --bug-id | String | — | Required. Pattern bug-NNNNNN. Identifies parent bug directory. | | --story | String | — | Required. Story slug (e.g., story-01-regression-test, story-02-fix). Resolved to .aikittools/bugs/<bug-id>/<story>.md. | | --target-branch | String | develop | Base branch for task + story PRs. Propagated to x-implement-task + x-create-pr. | | --auto-merge | Enum | none | merge\|squash\|rebase\|none. Propagated to x-create-pr. Requires --target-branch when not none. | | --auto-approve-pr | Boolean | false | Parent-branch mode (RULE-004): task PRs target feat/story-.... | | --task | String | — | Execute only a specific TASK-NNN. | | --resume | Boolean | false | Delegates resume-point detection to the engine x-internal-implement-story (Phase 0.4 resume procedure). | | --skip-verification | Boolean | false | Recovery-only. Skips Phase 3 of engine; flagged outside ## Recovery blocks. | | --skip-smoke, --skip-review | Boolean | false | Bypass smoke gate / specialist + TL reviews. | | --worktree | Boolean | false | Standalone worktree mode (ADR-0004 Mode 2). | | --interactive | Boolean | false | Opt-in to 3-option gate menus (PROCEED/FIX-PR/ABORT). Default: non-interactive (Rule 20). | | --no-auto-remediation, --no-ci-watch | Boolean | false | Skip automatic PR remediation / Rule 21 CI-watch. |

Output Contract

| Field | Type | Description | |-------|------|-------------| | storyId, bugId | String | Story slug + parent bug ID | | status | Enum | SUCCESS \| FAILED \| PARTIAL | | targetBranch, autoMergeStrategy | String, Enum | Resolved base branch + merge strategy | | tasksExecuted | List<{id, status, commitSha, prNumber}> | One entry per task dispatched | | prNumber / prUrl | Integer|null / String|null | Story-level PR; null without --auto-approve-pr | | verifyPassed | Boolean | Phase 3 verify-gate passed | | reportPath | String | Final report from the engine x-internal-implement-story (Phase 3.3 story-report procedure) | | coverageLine / coverageBranch | Number|null | Filtered coverage | | commitSha | String|null | SHA of the last task commit; null when no task completed | | errorClass | Enum|null | TRANSIENT \| CONTEXT \| PERMANENT \| null — populated on status=FAILED | | retryable | Boolean|null | true when errorClass ∈ {TRANSIENT, CONTEXT}; false on PERMANENT; null on SUCCESS | | summary | String|null | Short human-readable failure cause; null on SUCCESS | | contextPressureDetected | Boolean | true when context-window pressure was observed |

Error Codes

| Exit | Code | Condition | |------|------|-----------| | 1 | ARGS_INVALID | Missing --bug-id or --story; or story file not found | | 2 | STORY_NOT_LOADABLE | x-internal-load-story-context non-zero | | 3 | PLAN_FAILED | x-internal-build-story-plan non-zero (via x-internal-implement-story) | | 4 | TASK_FAILED | One or more tasks returned FAILED (via x-internal-implement-story) | | 5 | VERIFY_FAILED | Story Verification Procedure passed=false (Phase 3.1 inline em x-internal-implement-story) | | 6 | PR_CREATE_FAILED | x-create-pr non-zero on story-level PR (via x-internal-implement-story) | | 7 | PLAN_ARTIFACTS_MISSING | Required planning artifacts absent or invalid (via x-internal-implement-story) | | 10 | BUG_NOT_REFINED | Parent bug.md has Refinement Verdict status != "approved" (Phase 0.0 BUG_GATE) | | 11 | STORY_NOT_REFINED | A sibling story has Refinement Verdict status != "approved" (Phase 0.0 BUG_GATE) | | 12 | ORDERING_VIOLATION | story-02-fix requested before story-01-regression-test is Concluída (Phase 0.B1) |

Workflow Overview

Phase 0.0  : BUG_GATE (mandatory)     (Parent bug + all sibling stories must have approved Refinement Verdict)
Phase 0.B1 : Ordering enforcement      (story-02-fix blocked until story-01-regression-test = Concluída)
Phase 0.B2 : Load bug story context    (resolve path, load story, init execution-state.json if absent)
Phase 0.B3 : Context pack selection    (x-internal-select-context-packs)
[DELEGATE]  → x-internal-implement-story (Phases 0.3 → 3 — shared engine, --story-mode bug)

CRITICAL EXECUTION RULE

4 steps (BUG_GATE → Ordering → Load → DELEGATE). All 4 are mandatory. NEVER skip Phase 0.0 BUG_GATE outside hotfix/ branches.*

Phase 0.0 — BUG_GATE (Mandatory)

Exception: hotfix/* branches are exempt (Rule 27 Exception 2). Check with git branch --show-current | grep -q '^hotfix/' before running the gate.

Open a phase tracker:

TaskCreate(subject: "{BUG_ID}/{STORY} › Phase 0.0 - BUG_GATE", activeForm: "Verifying bug and story refinement verdicts")

Step 1 — Verify parent bug refinement:

BUG_FILE=".aikittools/bugs/<bug-id>/bug.md"
BUG_VERDICT=$(awk '/## Refinement Verdict/{f=1} f && /status:/{print $2; exit}' "$BUG_FILE")

if [[ "$BUG_VERDICT" != "approved" ]]; then
  echo "ABORT [BUG_NOT_REFINED]: Bug <bug-id> has Refinement Verdict status=${BUG_VERDICT}."
  echo "  Run /x-refine-bug <bug-id> to obtain an approved verdict before implementing."
  exit 10
fi

Step 2 — Verify all sibling story refinements:

for SIBLING in ".aikittools/bugs/<bug-id>/story-"[0-9][0-9]-*.md; do
  [[ -f "$SIBLING" ]] || continue
  SIBLING_NAME=$(basename "$SIBLING" .md)
  SIBLING_VERDICT=$(awk '/## Refinement Verdict/{f=1} f && /status:/{print $2; exit}' "$SIBLING")

  if [[ "$SIBLING_VERDICT" != "approved" ]]; then
    echo "ABORT [STORY_NOT_REFINED]: ${SIBLING_NAME} has Refinement Verdict status=${SIBLING_VERDICT}."
    echo "  Run /x-refine-bug <bug-id> to approve all stories before implementing."
    exit 11
  fi
done

TaskUpdate(id: bugGateTaskId, status: "completed")

Phase 0.0 completed. Proceeding to Phase 0.B1 (Ordering)...

Phase 0.B1 — Ordering Enforcement (Conditional)

Applies only to story-02-fix (and any subsequent fix stories). Regression-test stories (story-01-*) are always allowed.

Check that the preceding story is Concluída before allowing implementation:

STORY_NUM=$(echo "<story-slug>" | grep -oE '^story-[0-9]+' | grep -oE '[0-9]+')

if [[ "$STORY_NUM" -gt "01" ]]; then
  PREV_NUM=$(printf "%02d" $((10#$STORY_NUM - 1)))
  PREV_FILE=".aikittools/bugs/<bug-id>/story-${PREV_NUM}-*.md"
  PREV_STATUS=$(grep '^\*\*Status:\*\*' $PREV_FILE | awk '{print $2}')

  if [[ "$PREV_STATUS" != "Concluída" ]]; then
    echo "ABORT [ORDERING_VIOLATION]: story-${PREV_NUM}-* must be Concluída before implementing story-${STORY_NUM}-*."
    echo "  Current status: ${PREV_STATUS}"
    echo "  Run /x-fix-bug --bug-id <bug-id> --story story-${PREV_NUM}-* first."
    exit 12
  fi
fi

If story number is 01 → skip this phase entirely.

Phase 0.B1 completed. Proceeding to Phase 0.B2 (Load context)...

Phase 0.B2 — Load Bug Story Context

Open phase tracker:

TaskCreate(subject: "{BUG_ID}/{STORY} › Phase 0.B2 - Load", activeForm: "Loading bug story context")

Resolve full story path:

CONTEXT_PATH=".aikittools/bugs/<bug-id>/"
STORY_FILE="${CONTEXT_PATH}<story-slug>.md"

Verify file exists; exit ARGS_INVALID (1) if absent.

Load story context:

Skill(skill: "x-internal-load-story-context",
      args: "--story-id <story-slug> --context-path .aikittools/bugs/<bug-id>/")

Envelope: {storyPath, tasksCount, scope, planningMode, predecessorsComplete, artifactFreshness[]}. Non-zero → STORY_NOT_LOADABLE.

Initialize execution-state.json if absent:

STATE_FILE="${CONTEXT_PATH}execution-state.json"
if [[ ! -f "$STATE_FILE" ]]; then
  Skill(skill: "x-internal-update-status",
        args: "--file ${STATE_FILE} --type story --id <story-slug> --field status --value PENDING --initialize")
fi

Persist interactiveMode:

Skill(skill: "x-internal-update-status",
      args: "--file .aikittools/bugs/<bug-id>/execution-state.json --type story --id <story-slug> --field interactiveMode --value <interactive|non-interactive>")

TaskUpdate(id: loadTaskId, status: "completed")

Phase 0.B2 completed. Proceeding to Phase 0.B3 (Context packs)...

Phase 0.B3 — Context Pack Selection

Derive implementationCapabilities from the bug story evidence (impacted layers, interfaces, active quality/security constraints). Bug stories always include testing capability; story-02-fix always includes debugging capability.

Skill(skill: "x-internal-select-context-packs",
      args: "--phase implement --capabilities <implementationCapabilities>")

Treat selector output as the primary source of implementation packs. Persist implementationCapabilities in orchestrator memory.

Phase 0.B3 completed. Delegating to x-internal-implement-story (Phases 0.3 → 3)...

Delegation — x-internal-implement-story (Phases 0.3 → 3)

Delegate all remaining phases to the shared implementation engine with --story-mode bug:

Skill(skill: "x-internal-implement-story", args:
  "--story-id <story-slug>
   --context-path .aikittools/bugs/<bug-id>/
   --story-mode bug
   --target-branch <targetBranch>
   --auto-merge <autoMerge>
   --scope <scope>
   --planning-mode <planningMode>
   [--auto-approve-pr]
   [--task <TASK-ID>]
   [--resume]
   [--skip-verification]
   [--skip-smoke]
   [--skip-review]
   [--worktree]
   [--interactive]
   [--no-auto-remediation]
   [--no-ci-watch]")

Consume the x-internal-implement-story output envelope and re-emit it as the x-fix-bug output. Add bugId field from --bug-id arg.

x-internal-implement-story completed. Bug story lifecycle complete.

Error Envelope

| Scenario | Action | |----------|--------| | Missing --bug-id or --story | Exit ARGS_INVALID (1) | | Story file not found | Exit ARGS_INVALID (1) | | Parent bug not refined | Exit BUG_NOT_REFINED (10) | | Sibling story not refined | Exit STORY_NOT_REFINED (11) | | Story-02-fix before story-01 done | Exit ORDERING_VIOLATION (12) | | x-internal-load-story-context fails | Exit STORY_NOT_LOADABLE (2) | | Planning fails (via engine) | Exit PLAN_FAILED (3) | | Task fails (via engine) | Exit TASK_FAILED (4) | | Verify fails (via engine) | Exit VERIFY_FAILED (5) | | PR creation fails (via engine) | Exit PR_CREATE_FAILED (6) | | Planning artifacts missing (via engine) | Exit PLAN_ARTIFACTS_MISSING (7) | | Sub-skill transient error | Retry once with 2s backoff; persistent → propagate |

Recovery

Same flags as x-implement-story. CLAUDE_RECOVERY_MODE=1 is the ONLY accepted bypass variable.

| Flag | Skips | | :--- | :--- | | --skip-verification | Phase 3 (Story Verification Procedure inline em x-internal-implement-story) | | --skip-review | Step 3.2 (x-review-specialist + x-review-pr) | | --skip-quality | Step 3.Q quality gates — Recovery or hotfix/ only* | | --skip-doc | Step 3.0 documentation gates — Recovery or hotfix/ only* | | --skip-smoke | Smoke gate inside verify | | --no-ci-watch | CI-watch step in Phase 2 |

Exception for hotfix/ branches (Rule 27 Exception 2):* Phase 0.0 BUG_GATE, Phase 0.B1 ordering enforcement, and recovery flags are all relaxed on hotfix/* branches.

Knowledge Pack References

Read src/patterns/asset-usage-matrix.csv Read src/skills/x-internal-select-context-packs/SKILL.md Read src/knowledge/shared/governance-baselines/bug-lifecycle/knowledge.md Read src/knowledge/shared/architecture-decisions/task-hierarchy/knowledge.md

Integration Notes

x-internal-load-story-context (0.B2), engine resume procedure (via engine Phase 0.4 cond.), x-internal-build-story-plan (via engine 1), x-implement-task (via engine 2 per-task), x-create-pr (via engine 2 per-task+story), x-watch-pr-ci (via engine 2 CI loop), x-fix-pr (via engine 2 CI remediation + 3.2 review remediation), x-evaluate-parallelism (via engine 1), x-review-specialist/x-review-pr (via engine 3.2), Story Verification Procedure (via engine 3.1 inline), x-internal-write-report (via engine 3.3 story-report procedure render), x-internal-update-status (all phases), x-manage-worktrees (via engine 0.3+3.5), x-internal-select-context-packs (0.B3), x-refine-bug (prerequisite — not called by this skill).

Decision Record

bug-lifecycle.md: Defines the full bug lifecycle, including refinement gates, story ordering, and skill responsibilities.

Optional: Version Bump After Fix

After a successful bug fix (when status=SUCCESS), you may optionally bump the application version following Semantic Versioning. Bug fixes typically correspond to a patch increment:

Skill(skill: "x-increment-version", args: "--type patch")

This step is NOT mandatory — invoke it only when the project has explicit version management. See /x-increment-version for stack detection (Java/pom.xml, Node.js/package.json, Python/pyproject.toml) and commit conventions (chore(version): bump to X.Y.Z).