debug-issue

name	debug-issue
description	Systematic debugging workflow. Analyzes error context, maps relevant code, forms and tests hypotheses, then implements and verifies a fix with team lead oversight. Use when investigating bugs or unexpected behavior.

Debug Issue Workflow

1. Gather Context

Understand the bug by collecting information:

• Error messages, stack traces, or unexpected behavior descriptions
• Steps to reproduce
• Which parts of the codebase are likely involved

2. Analyze

Use the team tool to run the architect agent for analysis:

team run architect "Analyze this bug: <description>. Find the relevant code, trace the execution path, and identify likely root causes."

3. Create a Todo with Fix Plan

Save the analysis as a todo with a full plan document:

todo create title="Fix: <bug description>" description="<root cause summary>" plan="<full plan with Context, Root Cause, Changes (specific files/lines/code), Verification>"

4. Plan Review

Run the team-lead to review the fix plan before implementation:

team run team-lead "Review this fix plan for: <bug description>. The plan is:

<architect's plan>

Evaluate completeness of root cause analysis, feasibility of fix, and risk of regressions. Output your verdict as APPROVED or REVISE."

• If APPROVED, proceed to step 5.
• If REVISE, pass feedback to the architect for one revision, update the todo plan, and re-review. Max 1 revision round.

5. Implement Fix

Run the appropriate developer agent, referencing the plan:

team run dev-backend "Fix the bug per the plan: <specific change section>"

6. Verify

Run QA to verify the fix:

team run qa "Verify the fix for: <bug description>. Run relevant tests and confirm the bug is resolved without regressions."

7. Completion Validation

Run the team-lead to validate the fix matches the plan:

team run team-lead "Validate this bug fix against the plan. The plan was:

<plan from todo>

QA verification result:

<QA output>

Check that the root cause was addressed and QA issues were resolved. Run `git diff` to inspect the changes. Output your verdict as APPROVED or NEEDS WORK."

• If APPROVED, proceed to step 8.
• If NEEDS WORK, pass gaps to the developer, re-run QA, re-validate. Max 1 rework round.

8. Finalize

Update the todo status:

todo update id="<id>" status="done"