aif-fix

Fix - Bug Fix Workflow

Fix a specific bug or problem in the codebase. Supports two modes: immediate fix or plan-first approach.

Workflow

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. Always include tests 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.fix_plan, and paths.patches
• Language: language.ui for prompts
• 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/
• FIX_PLAN.md: .ai-factory/FIX_PLAN.md
• patches/: .ai-factory/patches/
• Language: en (English)

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
• 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
• Follow each step of the plan sequentially
• After the fix is fully applied and verified, delete the resolved fix plan file:

  rm <resolved fix plan path>
  

• Continue to Step 4 (Verify), Step 5 (Test suggestion), 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.

Patch fallback (limited, only when skill-context is missing):

• If .ai-factory/skill-context/aif-fix/SKILL.md does not exist and the resolved patches dir exists:
  • Use Glob to find *.md files in <resolved patches dir>
  • Sort patch filenames ascending (lexical), then select the last 10 (or fewer if less exist)
  • Read those selected patch files only
  • Prioritize recurring Root Cause and Prevention patterns
• If skill-context exists, do not read all patches by default.
  • Optionally inspect a small, targeted subset of recent patches when tags/files clearly match the current bug.

Step 1: Understand the Problem & Choose Mode

From $ARGUMENTS, identify:

• Error message or unexpected behavior
• Where it occurs (file, function, endpoint)
• Steps to reproduce (if provided)

If unclear, ask:

To fix this effectively, I need more context:

1. What is the expected behavior?
2. What actually happens?
3. Can you share the error message/stack trace?
4. When did this start happening?

After understanding the problem, ask the user to choose a mode using AskUserQuestion:

Question: "How would you like to proceed with the fix?"

Options:

1. Fix now — Investigate and apply the fix immediately
2. Plan first — Create a fix plan for review, then fix later

Based on choice:

• "Plan first" → Proceed to Step 1.1: Create Fix Plan
• "Fix now" → Skip Step 1.1, proceed directly to Step 2: Investigate the Codebase

Step 1.1: Create Fix Plan

Handoff sync (manual mode only): If a Handoff task ID is known (from HANDOFF_TASK_ID or an existing annotation) AND HANDOFF_MODE is NOT 1, call handoff_sync_status with { taskId: <id>, newStatus: "planning", sourceTimestamp: "<current UTC time in ISO 8601 format>", direction: "aif_to_handoff", paused: true }.

Investigate the codebase enough to understand the problem and create a plan.

Use the same parallel exploration approach as Step 2 — launch Explore agents to investigate the problem area, related code, and past patterns simultaneously.

After agents return, synthesize findings to:

1. Identify the root cause (or most likely candidates)
2. Map affected files and functions
3. Assess impact scope

Then create the resolved fix plan file (default: .ai-factory/FIX_PLAN.md).

Before writing: If HANDOFF_MODE is 1 and HANDOFF_TASK_ID is non-empty, the very first line of the file MUST be <!-- handoff:task:<HANDOFF_TASK_ID> --> followed by a blank line, then the plan content below. If in manual mode and a task ID was extracted from an existing annotation, preserve it.

Structure:

# Fix Plan: [Brief title]

**Problem:** [What's broken — from user's description]
**Created:** YYYY-MM-DD HH:mm

## Analysis

What was found during investigation:

- Root cause (or suspected root cause)
- Affected files and functions
- Impact scope

## Fix Steps

Step-by-step plan for implementing the fix:

1. [ ] Step one — what to change and why
2. [ ] Step two — ...
3. [ ] Step three — ...

## Files to Modify

- `path/to/file.ts` — what changes are needed
- `path/to/another.ts` — what changes are needed

## Risks & Considerations

- Potential side effects
- Things to verify after the fix
- Edge cases to watch for

## Test Coverage

- What tests should be added
- What edge cases to cover

After creating the plan, output:

## Fix Plan Created ✅

Plan saved to the resolved fix plan path.

Review the plan and when you're ready to execute, run:

/aif-fix

Handoff sync (manual mode only): If a Handoff task ID is known AND HANDOFF_MODE is NOT 1, call handoff_push_plan with `{ taskId: <id>, planContent: <full fix plan

---

Content truncated.