| name | comment-bug |
| description | Fix a bug end-to-end through a live Comment.io worklog comm — reproduce, write a regression test that fails first, fix, verify on the preview, and drive to a merge-ready PR, with the repro, root cause, and verification recorded as the decision history. Invoke explicitly as `$comment-bug` / `/comment-bug`, or when a task is a defect, regression, broken workflow, or user-visible failure to be reproduced and fixed with a watchable, steerable record. Replaces the retired bug skill. Works identically under Codex and Claude Code. |
comment-bug — bug fix through a comm
Same worklog-driven spine as comment-feature, shaped for a defect. The worklog records the repro, the root cause, the fix, and the verification evidence as durable content. Composes worklog, steer, review-loop, and ship — all sibling skills in this bundle. (A bug fix is usually linear, so it doesn't delegate to drive-plan; reach for drive-plan only if the fix is genuinely multi-phase.)
A comment-prototype can promote INTO comment-bug (reusing its worklog/branch), which then adds the failing regression test a prototype skips. Reachable via the comment-dev front-door router.
Project Root. Direct comment-bug uses its worklog as the Project Root. If the human or caller supplies an existing Project Root URL, preserve it and make the bug worklog a child with Project Root: URL near the top. Do not create a second root.
Identity. Bug-fix comm activity follows the worklog route-and-identity rule. Reuse the identity carried by the working Comment.io tool/browser/connector route or a supplied Project Root token. Invoke comment-identity only immediately before an uncredentialed direct-REST write, then reuse that Ephemeral handle for later direct-REST worklog activity. Do not create bug worklogs as an ambient registered handle or any Botlets bot profile.
Before using a composed skill, read its full SKILL.md — naming it here does not auto-load its contract (the ship review/PR gate, worklog update rules), which you must follow.
Preconditions
- Task worktree on a
bug/... branch off fresh origin/main (never on main).
Workflow
- Open or inherit the Project Root. If no Project Root URL was supplied, open the worklog (
worklog) with the bug-shaped body and treat it as the Project Root; update its own Project Root: URL line after creation. If a Project Root URL was supplied, open the bug worklog as a child with that Project Root: URL near the top and link it from the root. Promotion from comment-prototype: if you were handed a prototype's human-openable worklog URL (share_url for direct REST) and branch, reuse that worklog as the Project Root — upgrade its light note in place to the bug-shaped body (don't open a second) — and continue on its branch. Record the symptom and exact reproduction steps first.
- Reproduce the failure deterministically. If you cannot reproduce, say so in the worklog and
steer to the reporter for details — do not guess a fix.
- Write a regression test that FAILS on the current code — this proves you've captured the bug. Record the failing output as a comment.
- Diagnose the root cause; record it in the body with the evidence (logs, traces, the offending code path).
- Steer checkpoint — before committing to a non-obvious fix strategy, run
steer: check for human comments, and escalate the chosen approach if it's risky or ambiguous.
- Fix minimally and at the right layer. The regression test must now pass.
Use focused checks while the fix and review converge;
ship runs the complete
affected lane on the final committed candidate.
- Review the fix by explicitly invoking
$review-loop (it runs only on explicit request — this step is that request; rounds as comments); fix real findings; re-run until clean. Do this before the real-scenario verification so the evidence reflects the final code.
- Verify the real scenario — on the final post-review-loop code, confirm the original symptom is gone, on the branch preview where applicable (the repo's convention for a per-worktree staging deploy, e.g.
https://<worktree>.toofs.us here — see the guide; skip if unavailable in your runtime). Capture evidence (screenshot/log) as a comment.
- Ship with
ship (pass it the human-openable worklog URL and Project Root URL when distinct).
Definition of done
- Regression test fails pre-fix, passes post-fix (both recorded).
- The original user-visible symptom is verified gone, not just the test green.
- Worklog body carries repro → root cause → fix; comments carry the failing/passing evidence and review-loop rounds.
Content vs comments
Repro, root cause, fix, verification conclusion → worklog body. Failing/passing test output, screenshots, review-loop rounds, steering → comments. Keep the Project Root scannable: no bulky evidence or review transcripts in the root body.
Repo config
This skill is repo-agnostic — run this repo's commands, not hardcoded ones. Read AGENTS.md (else CLAUDE.md) and its linked docs/TESTING.md for focused iteration checks and final candidate certification, plus the guide's PR/branch/merge and deploy/preview norms. If docs/TESTING.md is absent, infer suitable lanes from package.json / Makefile / CI and offer comment-init to scaffold the config.
Comment.io API
Use the current worklog/Project Root and its working Comment.io route first. Resolve and freeze $BASE for the whole workflow in this order: the supplied comm's validated final Comment.io origin after any shortlink redirect; the active Comment.io tool/account base URL; an explicitly selected profile's base_url; only when no target context exists, https://comment.io. A shortlink origin is never $BASE; do not switch a staging/custom workflow to production. For direct REST, consult $BASE/llms/reference.txt only when exact API or recovery detail is needed. Fetch $BASE/llms.txt only when no current route works or another focused guide is needed. Invoke comment-identity only before an uncredentialed direct-REST write; never replace a supplied token or tool/browser/connector identity. Don't restate the live contracts here.
Content vs comments (team convention). The answer → document body; how you got there (review-loop rounds, steering, escalations) → comments, as lists / short lines.
Template
Worklog bug variant body:
Project Root: URL
## Repro
<symptom + exact steps>
## Root cause
<the real cause + evidence/code path>
## Fix
<what changed and why this layer>. Regression test: <name> (fails pre-fix).
## Verification
<original symptom reproduced gone — evidence in comments>
Follow the skeleton above; keep repro/root cause/fix/verification in the body and evidence in comments.
