Fix - Bug Fix Workflow

Runtime-aware questions

Apply this contract whenever the workflow asks the user to decide:

• AskUserQuestion and Questions below describe the intended interaction, not a required tool name. Use only a question tool actually exposed and permitted in the current session/mode, with its advertised schema. Do not guess aliases, probe unavailable tools, or assume questionnaire exists. A frontmatter entry alone does not make a tool available.
• Ask one focused question at a time with clearly labelled options. Batch independent questions only if the actual tool schema supports it; respect its field names, limits, and selection semantics. For open-ended input, use native free-text support or plain text if the schema cannot represent the question. Use the resolved UI language.
• If no usable question tool exists (or it reports unavailable in this mode), ask the same question in plain text with numbered options and allow a free-text answer. Pause work that depends on that answer; independent read-only investigation may continue. Missing UI does not make the session autonomous.
• An empty/cancelled response, a preselected option, or elapsed time is not an answer or approval. Reuse an answer already given in the session instead of asking again.
• In a subagent/background run or explicit non-interactive mode (including HANDOFF_MODE=1), do not prompt the user directly. Use declared defaults only for optional preferences within the authorized scope and report assumptions. If a required decision, approval, or material scope/behavior choice remains unresolved, stop dependent work and return the missing decision and options to the parent/caller using its existing blocked/failure contract. Never invent consent or select a new scope to avoid blocking.

This delivery policy applies to this skill and its linked references. Preserve workflow-specific question scope, required confirmations, approval boundaries, and blocked-result rules.

Shell commands are not pre-approved by this skill. Use an exposed execution tool under the runtime's existing permissions for the authorized command and CWD. Reuse applicable authorization; request native approval only when required. Unavailable or denied commands remain blockers/not_run in delegated runs too. Never broaden permissions, use another path to bypass a denial, or report an unexecuted check as passed.

Shared project skill-context

Before mode routing or work, read existing files relative to the current project root in this order (reuse them if already loaded):

1. .ai-factory/skill-context/global-skill-context.md — all bundled skills.
2. .ai-factory/skill-context/build-skill-context.md — only fix, implement, plan, verify, improve.
3. .ai-factory/skill-context/aif-fix/SKILL.md — this skill.

Missing files are skipped; an existing unreadable file stops dependent work with its path. Precedence: individual > build (when applicable) > global > skill defaults; retain non-conflicting instructions and check all outputs against the effective rules. These layers customize workflow; they do not replace the project's rules/architecture hierarchy or relax explicit requirements, ownership, scope, safety/privacy, validation, or approval boundaries. Report conflicts with those boundaries instead of overriding them. global is a project-local layer, not home-directory configuration. Custom/extension skills do not automatically use it.

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.

Selective reference loading

Resolve reference paths beside this installed entrypoint, including flat workflows. Read a reference in full only when its stated condition applies, before the dependent step; do not preload all references. If a selected reference is missing or unreadable, STOP before that step and report its path. The entrypoint dispatch and hard boundaries apply to every reference. Project skill-context overrides and managed extension injections retain their existing precedence. Keep managed aif-ext blocks in the entrypoint; never move them into references.

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. Honor the mode resolved in Step 0; only ask falls back to "Fix now" in autonomous Handoff. 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
• Fix defaults: workflow.fix_mode (ask, now, plan; default ask) and workflow.fix_patch (YAML boolean; default true). Invalid values/types emit WARN [config] and fall back independently to those defaults; quoted booleans are invalid. Preserve false, never resolve the patch policy with value || true.

Parse standalone control flags from $ARGUMENTS: --fix-now selects now, --plan-first selects plan, --patch enables patch creation, and --no-patch disables it. For each setting, the last explicit flag wins over config. Remove only these control tokens from the problem description; preserve other wording, paths, quoted/code text, and flag-like substrings. Flags alone are not a problem description. Resolve mode and patch policy once for this invocation; do not persist overrides to config or the fix plan. An existing fix plan still takes priority over mode selection.

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:

  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), then apply the learning patch policy below.

If the file DOES NOT exist AND the problem description is empty after removing control flags:

• 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 a problem description remains:

• 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.

Apply the shared precedence and boundaries above to every output. FIX_PLAN.md and patch templates are base structures: augment them with applicable skill-context requirements. Verify every generated artifact against those rules and correct violations before presenting it.

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

• If .ai-factory/skill-context/aif-fix/SKILL.md is absent and the resolved patches dir exists (even when global/build context 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 the individual 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 the problem description after removing control flags, 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, use the resolved mode: now selects "Fix now" and plan selects "Plan first" without a mode question. Only ask prompts below; in autonomous Handoff it selects "Fix now" without prompting. Missing or invalid config retains this legacy ask behavior. This skips only the optional mode question, never required clarification or approval.

For interactive ask, use AskUserQuestion: "How would you like to proceed with the fix?"

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

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

Plan-first route

Only when plan-first is selected, read fix-plan creation, investigate enough to define the fix, preserve Research Context revisions and the first-line Handoff annotation, save the configured fix plan, synchronize manual Handoff to plan_ready when linked, then STOP. Do not apply the fix in this route.

Investigation

Before investigating in any fix-now, plan-first, or existing-plan route, read investigation and manual Handoff start. Its manual implementing sync applies only to fix-now execution, not plan-first. Identify the root cause, affected callers, side effects, and related patterns. Use the defined direct fallback when delegation is unavailable.

Step 2.5: Capture a Regression Check

Apply the Canonical Regression-First Policy before changing implementation code. Prefer a regression check for behavior bugs, parsing/validation bugs, API/data bugs, crashes, and regressions. If the change is a non-bug cleanup, purely static correction, or investigation-only request, record why the policy does not apply and continue with the normal fix workflow.

Anti-gaming rule: Do not tailor the test to the implementation you plan to write. The test must describe the externally expected behavior or the reported failure condition. If the test passes before any fix, either the reproduction is wrong, the bug is stale, or the environment differs; handle that mismatch through the fallback behavior in the Canonical Regression-First Policy before changing implementation code.

Record the selected regression check, pre-fix result, and any fallback decision in your working notes so Step 4 can rerun or revisit the same check after the fix.

Apply the fix

After the Canonical Regression-First Policy permits implementation, read fix implementation and logging. Apply the smallest root-cause fix with configurable [FIX] or [FIX:<issue-id>] logging; do not add unrelated features or refactoring.

Step 4: Verify the Fix

• Check the code compiles/runs
• If Step 2.5 created, identified, or documented a regression check, rerun or revisit the same check and confirm the fixed behavior
• Verify the logic is correct
• Ensure no regressions introduced
• When practical, run the closest existing related test suite after the regression check passes

Coverage and completion

After verification, read completion, manual Handoff final sync, and extra coverage. Always suggest additional coverage beyond the regression check and respect the user's choice. Autonomous Handoff never calls MCP; manual linked tasks use done only with HANDOFF_SKIP_REVIEW=1, otherwise review, with the existing paused contract. Render the result in ui_language and continue to the learning patch policy below.

Logging contract

Read logging patterns before editing fix code. Every fix logs inputs, success, and errors with configurable [FIX]/[FIX:<issue-id>] logging; context-gate outputs use WARN/ERROR without changing other skills' policies.

Worked examples

Read fix examples only when a worked example is needed. They never override the Canonical Regression-First Policy.

Important Rules

1. Check the fix plan first - Always check the resolved fix plan path before anything else
2. Plan mode = plan only - When user chooses "Plan first", create the plan and STOP. Do NOT fix.
3. Execute mode = follow the plan - When the resolved fix plan exists, follow it step by step. Delete it after verified execution only if it is the default .ai-factory/FIX_PLAN.md; preserve custom/non-default fix plan files.
4. NO reports - Don't create summary documents (patches are learning artifacts, not reports)
5. ALWAYS log - Every fix must have logging for feedback
6. Regression-first when checks are needed - When a bug needs regression coverage, follow the Canonical Regression-First Policy before changing implementation code, confirm the problem when reproducible, then verify the same regression check after the fix
7. Do not fit tests to implementation - Regression tests encode the reported/expected behavior, not the internal implementation shape
8. ALWAYS suggest additional tests - Help prevent nearby regressions beyond the required regression check
9. Root cause - Fix the actual problem, not symptoms
10. Minimal changes - Don't refactor unrelated code
11. One fix at a time - Don't scope creep
12. Clean up - Delete only the default fix plan after verified execution; preserve custom/non-default fix plan files
13. Ownership boundary - /aif-fix owns paths.fix_plan and paths.patches; treat .ai-factory/DESCRIPTION.md, roadmap, rules, and architecture context artifacts as read-only unless the user explicitly requests otherwise
14. Logging scope - Keep [FIX] logging requirements for fixes; context-gate outputs in this command should use WARN/ERROR and must not change global logging policy in other skills

Result format

Before displaying the fix summary, read result template. Report the cause, fix, files, logging, and actual regression check/result or its explicit absence; do not create a report file.

Learning patch policy

After a completed fix (including existing-plan execution), only when the resolved patch policy is enabled, read self-improvement patch creation and write the timestamped learning artifact under configured paths.patches in artifact_language. Include problem, root cause, solution, prevention, and tags. When disabled, skip that reference and all patch writes/directory creation; state in ui_language that learning patch creation was skipped by policy. Existing patches and their optional read-only fallback remain unchanged. Plan-first runs stop before execution and never create a completed-fix patch; resolve the policy anew when executing the plan later. Failed/blocked fixes do not produce completed-fix patches. Patch settings never skip regression verification, logging, extra coverage suggestions, Handoff sync, or default-plan cleanup.

Context Cleanup

Suggest the user to free up context space if needed: /clear (full reset) or /compact (compress history).

DO NOT:

• ❌ Apply a fix when user chose "Plan first" - only create the fix plan and stop
• ❌ Skip the fix-plan check at the start
• ❌ Leave the default .ai-factory/FIX_PLAN.md after successful fix execution
• ❌ Delete custom/non-default fix plan files after execution
• ❌ Generate reports or summaries (patches are NOT reports — they are learning artifacts)
• ❌ Refactor unrelated code
• ❌ Add features while fixing
• ❌ Skip logging
• ❌ Skip test suggestion
• ❌ Skip patch creation when the resolved patch policy is enabled