lee-to/ai-factory/aif-fix

Fix - Bug Fix Workflow

Fix a specific bug or problem in the codebase. Supports two modes: immediate fix or plan-first approach. The default workflow is regression-first whenever a regression check is needed: reproduce the problem, confirm the reported behavior, implement the fix, then verify the same check passes.

Workflow

Canonical Regression-First Policy

A regression check is the smallest useful test, command, fixture, API call, browser scenario, script, or documented manual/runtime reproduction that proves the reported bug or validates the expected behavior.

When a bug needs regression coverage, every workflow path (fix-now, plan-first, and existing-plan execution) follows this policy:

1. Identify the minimal regression check that should reproduce the issue or encode the expected behavior.
2. Execute the check before implementation and confirm it fails or reproduces the reported problem.
3. Implement the smallest fix addressing the root cause.
4. Re-run the exact same check and confirm it passes.
5. Only after that, run related existing checks when practical and suggest broader coverage if useful.

Fallback behavior:

• If no automated/executable check is available, document the narrowest manual/runtime reproduction and why no executable check exists. Treat that documented reproduction as the regression check for Step 4 when it can be rerun.
• If no useful regression check exists at all, record the reason before implementation. In HANDOFF_MODE=1, continue only when investigation found a plausible root cause that can be fixed safely; otherwise report the task as blocked/unreproducible and stop without changing implementation code. In manual mode, ask whether to proceed with the likely fix, adjust reproduction, or investigate further.
• If the pre-fix regression check passes unexpectedly, treat it as a reproduction mismatch: record the command/check, inputs, environment assumptions, and observed result. Then use the same HANDOFF_MODE=1 or manual-mode fallback above.

Do not duplicate or weaken this policy in later workflow sections. Later steps should reference this section and add only local execution details.

Step 0 (pre): Detect Handoff Mode

Determine Handoff mode, task ID, and skip-review flag. If the caller passed HANDOFF_MODE, HANDOFF_TASK_ID, and HANDOFF_SKIP_REVIEW as explicit text in the prompt, use those values. Otherwise, use the Bash tool:

Bash: printenv HANDOFF_MODE || true
Bash: printenv HANDOFF_TASK_ID || true
Bash: printenv HANDOFF_SKIP_REVIEW || true

Then check `HANDOFF_MODE`:

When HANDOFF_MODE is 1 (autonomous Handoff agent)

The Handoff coordinator already manages status transitions and DB writes directly. Do NOT call MCP tools. Instead:

• No interactive questions: Do not use AskUserQuestion. If $ARGUMENTS contains --plan-first, use "Plan first" mode. Otherwise default to "Fix now" mode. When a regression check is needed for the bug, include regression-first handling and logging.
• Plan annotation (MANDATORY): If HANDOFF_TASK_ID is non-empty, you MUST insert <!-- handoff:task:<HANDOFF_TASK_ID> --> as the very first line of the fix plan file, before the title. Omitting this annotation when HANDOFF_TASK_ID is set is a bug — verify before completing. This applies to both Step 1.1 (creating new plan) and any plan rewrite.

When HANDOFF_MODE is NOT 1 (manual Claude Code session)

Handoff sync is handled inline — see Step 0.1 (after reading the fix plan file) for the task ID extraction and MCP sync trigger. The sync points are:

• Plan first (Step 1.1): "planning" → "plan_ready" (after save)
• Fix now (Step 2→5): "implementing" (Step 2 entry) → "done" if HANDOFF_SKIP_REVIEW=1, else "review" (Step 5)
• Execute existing plan (Step 0.1→5): "implementing" (Step 0.1) → "done" if HANDOFF_SKIP_REVIEW=1, else "review" (Step 5)

CRITICAL: Always pass paused: true with every handoff_sync_status call except done.

When creating a new FIX_PLAN.md: if there is no existing annotation and no Handoff context, do not add the annotation.

Step 0: Load Config and Resolve Paths

FIRST: Read .ai-factory/config.yaml if it exists to resolve:

• Paths: paths.description, paths.architecture, paths.rules_file, paths.rules, paths.research, paths.fix_plan, and paths.patches; derive research_bundles_dir = <parent directory of paths.research>/research/
• Language: language.ui for prompts and summaries, language.artifacts for FIX_PLAN.md and patch artifacts, and language.technical_terms for human-readable technical terminology in artifacts
• Rules: rules.base plus any named rules.<area> entries

If config.yaml doesn't exist, use defaults:

• DESCRIPTION.md: .ai-factory/DESCRIPTION.md
• ARCHITECTURE.md: .ai-factory/ARCHITECTURE.md
• RULES.md: .ai-factory/RULES.md
• rules/: .ai-factory/rules/
• RESEARCH.md: .ai-factory/RESEARCH.md
• FIX_PLAN.md: .ai-factory/FIX_PLAN.md
• patches/: .ai-factory/patches/
• ui_language: en
• artifact_language: en
• technical_terms_policy: keep

Resolved language values:

• ui_language = language.ui || "en"
• artifact_language = language.artifacts || language.ui || "en"
• technical_terms_policy = language.technical_terms || "keep"

If technical_terms_policy is not one of keep, translate, or mixed, treat it as keep. Legacy values such as english also behave like keep.

All AskUserQuestion prompts, progress updates, fix summaries, test prompts, and next-step guidance MUST be written in ui_language.

Generated FIX_PLAN.md and self-improvement patch files under paths.patches MUST be written in artifact_language.

Templates and examples define structure, not fixed English output. If artifact_language is not en, translate human-readable headings, labels, analysis text, fix checklist entries, risks, prevention notes, and patch prose before saving. Preserve Handoff annotations, markdown structure, checkbox syntax, paths, commands, config keys, code identifiers, package names, API names, raw error messages, code snippets, log prefixes such as [FIX], and patch tags unchanged. Keep ## Research Context, Source:, Active Summary, Updated:, and SHA256: exact because downstream research drift checks parse them as compatibility tokens. Apply technical_terms_policy to other human-readable terminology.

Step 0.1: Check for Existing Fix Plan

BEFORE anything else after config resolution, check the resolved fix plan path (default: .ai-factory/FIX_PLAN.md).

If the file EXISTS:

• Read the resolved fix plan file
• If the fix plan contains ## Research Context, treat its embedded copy as the committed requirements snapshot. Parse the first Source: / Reference: line with canonical ^(?:Source|Reference):\s+\x60([^\x60]+)\x60\s+\( syntax; for older bare-path lines, fall back to ^(?:Source|Reference):\s+(.+?)\s+\(. Fall back to configured paths.research only when neither form identifies a usable path.
• If the parsed source is inside research_bundles_dir, require its sibling INDEX.md to contain <!-- aif:research-mode:ultra --> exactly once and link that RESEARCH.md from ## Artifact Index; otherwise emit WARN [research-drift]. Valid sibling C4/ADR/dependency artifacts are rationale only.
• When SHA256: is present, extract the current source text strictly between <!-- aif:active-summary:start --> and <!-- aif:active-summary:end -->, remove HTML comment blocks, preserve line order and leading whitespace, trim trailing spaces from every line, use LF endings, and end with one newline. Hash through stdin with shasum -a 256 or sha256sum; the digest is authoritative. Use Updated: only as a legacy fallback when SHA256: is absent. A missing/invalid source or revision mismatch emits WARN [research-drift]; execute against the embedded Research Context unless the user explicitly requests a rebase.
• Immediately check the first line for `<!-- handoff:task:<uuid> -->`:
• If found AND HANDOFF_MODE is NOT 1 (manual session): extract the task ID. Call handoff_sync_status with { taskId: <extracted-id>, newStatus: "implementing", sourceTimestamp: "<current UTC time in ISO 8601 format>", direction: "aif_to_handoff", paused: true }. (Status is "implementing" because we are executing an existing plan, not creating one.)
• If found AND HANDOFF_MODE is 1: the Handoff coordinator handles sync — do nothing.
• If NOT found: no linked Handoff task — skip all MCP sync for the rest of this session.
• Inform the user: "Found existing fix plan. Executing fix based on the plan."
• Skip Step 1 (problem intake/mode choice), but still run Step 0.2 to load context
• Then continue to Step 2: Investigate the Codebase, using the plan as your guide
• Apply the Canonical Regression-First Policy before changing implementation code when a regression check is needed for the bug, even if the existing plan did not include that policy
• Follow the plan sequentially, but preserve the canonical order: confirm the problem first, implement the fix, then rerun the same regression check
• After the fix is fully applied and verified in Step 4, delete the resolved fix plan file only when it is the default fix plan path .ai-factory/FIX_PLAN.md:

``bash rm .ai-factory/FIX_PLAN.md ``

• If the fix plan came from a custom paths.fix_plan value, an explicitly supplied custom plan path, or any non-default fix plan location, do not delete it. Leave it in place and mention in the final summary that the custom fix plan was preserved.
• Continue to Step 5 (Additional Test Coverage) and Step 6 (Patch)

If the file DOES NOT exist AND `$ARGUMENTS` is empty:

• Tell the user: "No fix plan found and no problem description provided. Please either provide a bug description (/aif-fix <description>) or create a fix plan first."
• STOP.

If the file DOES NOT exist AND `$ARGUMENTS` is provided:

• Continue to Step 0.2 below.

Step 0.2: Load Project Context & Past Experience

THEN: Read .ai-factory/DESCRIPTION.md (use path from config) if it exists to understand:

• Tech stack (language, framework, database)
• Project architecture
• Coding conventions

Also read `.ai-factory/ARCHITECTURE.md` (use path from config), the resolved RULES.md path, and the configured rules hierarchy when present to avoid fixes that violate project structure or local conventions.

Read `.ai-factory/skill-context/aif-fix/SKILL.md` — MANDATORY if the file exists.

This file contains project-specific rules accumulated by /aif-evolve from patches, codebase conventions, and tech-stack analysis. These rules are tailored to the current project.

How to apply skill-context rules:

• Treat them as project-level overrides for this skill's general instructions
• When a skill-context rule conflicts with a general rule written in this SKILL.md,

the skill-context rule wins (more specific context takes priority — same principle as nested CLAUDE.md files)

• When there is no conflict, apply both: general rules from SKILL.md + project rules from skill-context
• Do NOT ignore skill-context rules even if they seem to contradict this skill's defaults —

they exist because the project's experience proved the default insufficient

• CRITICAL: skill-context rules apply to ALL outputs of this skill — including the FIX_PLAN.md

template and patch files. The FIX_PLAN.md template in Step 1.1 is a base structure. If a skill-context rule says "steps MUST include X" or "plan MUST have section Y" — you MUST augment the template accordingly. Generating a FIX_PLAN.md or patch that violates skill-context rules is a bug.

Enforcement: After generating any output artifact, verify it against all skill-context rules. If any rule is violated — fix the output before presenting it to the user.