Carlos Florêncio
118 lines
4.8 KiB
Markdown
118 lines
4.8 KiB
Markdown
---
|
|
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
|
|
|
|
```text
|
|
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.
|
|
|
|
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.
|