kanban-bug

Kanban bug workflow — triage and document a defect with reproduction, expected/actual result, severity, root cause and regression coverage before handing off to kanban-plan. Use when a work item has k

SKILL.md

GitHub

Kanban Bug — Triage and fix a defect

Argument: <bug_name>.

A bug goes through the same state machine and approval gate as a feature, but Phase 1 must record enough to reproduce it and to stop it coming back.

1. Verify

kf status --change {bug_name}
kf show {bug_name}

Only use this skill when the metadata says kind: bug and the work item is in brainstorm. If the bug is already in planning, backlog, implementation, testing or review, resume the matching skill; do not recreate artifacts.

2. Triage contract

Read and fill phase-1-spec-requirement.md using the bug template (kf instruct spec-requirement --change {bug_name}):

  • Severity and the affected environments.

  • Reproduction steps that are deterministic enough to follow.

  • Actual result and expected result.

  • What the fix covers and what it does not, plus acceptance criteria for the behaviour a regression must protect.

  • Suspected root cause when there is evidence for one; when there is not, say it is undetermined.

  • Regression test strategy and acceptance criteria that can be checked.

  • The related feature when you can identify it, and the docs impact: which file needs changing and why, or that no docs change is needed.

  • Sibling entry points: list what else reaches the broken code. Review will ask which of them the fix covers, so naming them here is cheaper than discovering them later.

Do not guess a root cause to make the report look finished. If you cannot reproduce it, report the blocker plainly and never assume the bug is PASS.

Write the reproduction so someone else can run it and watch it fail. Review re-runs it rather than trusting the report, so steps that only work on your machine come back as a finding.

3. Human confirmation

Summarise the bug, its severity, the reproduction, the impact, the expected fix and the regression test for the user. Only once the user confirms do you set the frontmatter to status: confirmed and run:

kf stage {bug_name} planning

Then load kanban-plan on its bug branch. The bug report is the execution contract: do not create an implementation plan, a use-case index, narratives, a diagram, a test plan or a feature report. Planning still needs human approval, and the user still chooses start or backlog.

4. Handoff

Bug report confirmed. Load kanban-plan on the bug branch to approve the triage contract and ask start or backlog; keep the reproduction and the regression test inside the approved scope.

A FAIL or a REJECT, in testing or in review, sends the item back to implementation. REQUIREMENT_BUG still stops for the user to decide; do not use it in place of a bug report.