A bug report just landed in your Inbox. Here's how to turn it into a verified fix.
Step 1: Create a fix initiative
Press Mod+3 to open Plan. Click create and choose Fix. Give it a title that describes the symptom: "Login fails with expired tokens" not "Auth bug."
The fix workflow starts with triage — an investigation phase unique to bugs. The initiative moves to the triage state.
Step 2: Triage
kdev (the developer agent) investigates the bug. Its first job is reproduction — it writes a test case that demonstrates the bug.
Use kdev to reproduce this bug: users with expired tokens can still access protected routes.kdev returns with:
- The exact steps to reproduce
- The root cause (not just the symptom)
- Two options for fixing it
The two options are presented as a questionnaire:
- Short-term patch — what changes, how fast to ship, what risk class remains
- Long-term structural fix — broader changes, what class of recurrence it prevents
You pick the approach. If the bug is trivial, kdev may honestly recommend the patch alone. If it's a recurring class of bug, structural fix is the right call.
Step 3: Planning
With the approach chosen, klead breaks the fix into stories. Even a small fix gets at least one story with a regression-test acceptance criterion — the test that reproduced the bug must now pass.
ktest reviews the acceptance criteria for testability.
Step 4: Implementation
kdev implements the fix stories. It verifies the regression test passes and checks that the fix doesn't break unrelated areas.
Step 5: Review
kreviewer and ktest review the changes. kreviewer checks that the fix addresses the root cause, not just the symptom. ktest verifies the regression test fails on the old code and passes on the new code.
A faster path for small bugs
If the bug is trivial and you trust the agent, you can skip the formal workflow. In Work (Mod+2), just ask:
Use kdev to fix the login timeout bug and add a regression test.kdev will reproduce, fix, test, and report back. You review the diff in Review (Mod+6) and accept or reject.
The formal workflow exists for bugs that need tracking, coordination, or review. Use it when the bug is complex, affects multiple areas, or needs team visibility.
Next step
Read Review changes to learn how to examine and accept agent-made changes.