fix

name	fix
description	Diagnose a bug, update its behavioral spec, create reviewable fix plan and task files, then hand off for explicit implementation with TDD.

Fix

Use the same durable, reviewable workflow as feature work. Diagnose first, then produce the spec amendment, fix plan, and task files before changing production code. The user reviews those artifacts, switches the main session if desired, and sends a later explicit implementation request. Native subagents still require explicit authorization.

Core Flow

Evidence -> Root cause -> Spec amendment -> Fix plan + tasks -> Design-package handoff -> Explicit implementation request -> TDD implementation -> PR AI review

Do not patch production code before the planning checkpoint unless the user explicitly opts out of the workflow.

Phase 0: Evidence And Root Cause

When a bug originates from an issue tracker, read the canonical issue and every image attachment before hypothesizing. Reproduce with existing tests, a read-only trace, or a minimal throwaway repro. Do not add production code during this phase.

State the root cause before planning:

• what is actually wrong, not only the symptom;
• why it happens and under which conditions;
• the smallest reliable reproduction; and
• the intended regression-test level and path.

If the problem cannot be reproduced or the cause remains unclear, stop and ask the user rather than guessing at a fix.

Phase 1: Fix Specification

Before implementation, find the affected durable spec under docs/specs/<slug>/spec.md and amend its behavior or GIVEN/WHEN/THEN scenario to cover the regression. If no relevant spec exists, create a concise repair spec at docs/specs/<fix-slug>/spec.md that states the broken behavior, desired behavior, regression scenario, out-of-scope work, and any relevant contract or persistence constraint.

This spec is the reviewable expected behavior; it is not an incident report.

Phase 2: Fix Plan And Task Files

Create docs/plans/<fix-slug>/plan.md and sibling docs/plans/<fix-slug>/task-<NN>-<short-slug>.md files before implementation. Follow the /plan structure, with these fix-specific requirements:

• Link the amended repair spec and state the confirmed root cause.
• Include the regression test that must fail before the code change and pass afterward.
• Name exact files, dependencies, acceptance criteria, and targeted commands.
• Use dependency waves and mark parallel-safe only for disjoint tasks with no shared schema, migration, generated contract, lockfile, or package config.
• Keep parallelism: sequential by default in each task; waves are a human decision aid, not authorization to delegate.

Phase 3: Design-Package Handoff

Before changing production or permanent test code, present:

• root-cause summary and reproduction evidence;
• amended/new spec path;
• fix plan and task-file paths;
• task waves, parallel candidates, and exact validation commands; and
• risks and out-of-scope work.

End the turn after this handoff. Do not call ask_user_question_kandev (or an equivalent approval prompt) to ask the user to approve the package or switch models. The user reviews the files, switches the main session if desired, and sends a later explicit implementation request. The files may remain draft/pending; do not wait for a separate approval marker. Do not infer subagent authorization from the plan.

Phase 4: Implement With TDD After Handoff

After the user explicitly asks to implement, execute the tasks sequentially by default:

1. Mark the task in_progress.
2. Write and run the regression test; confirm it fails for the expected reason.
3. Implement the minimal fix.
4. Run the task's exact targeted unit, integration, or E2E command.
5. Mark the task done and update plan.md status in the primary session.

For persisted defaults or coupled settings, audit every write/reset path for explicit empty or null values. Add the smallest invalid-pair regression, including fixture coverage, and verify normalized read-back plus existing validation.

When the user explicitly authorizes subagents, follow /planner-orchestration: native delegation only, current user-selected model, fork_turns: "none", compact task-file handoffs, no recursive spawning, and runtime usage-metadata confirmation. Only launch tasks marked parallel-safe.

Phase 5: PR Review

After all task checks pass, commit, push, and open the PR. Do not run automatic local simplify, QA, code/security review, or broad verification. The two configured PR AI reviewers are the semantic-review gate. Use /pr-fixup only for CI failures or actionable reviewer findings, rerunning only the affected task check after remediation.

Stop Conditions

Stop and ask the user when the root cause is uncertain, the repair changes an architecture/public-contract/persistence/security boundary, the spec and code disagree, or the same targeted check fails three times.

Final Report

Report the root cause, spec/plan/task paths, design-package handoff, subagents explicitly authorized (if any), changed files, tests run, and current PR-review status.