bugfix-comment-context

Bugfix Comment Context

Purpose

Use this skill to leave a compact maintenance note near non-obvious bugfix code. The note should explain the real-world problem that triggered the change, not just restate what the code does.

Workflow

1. Identify the smallest code location future maintainers are likely to question or delete: a guard clause, fallback, retry, compatibility branch, lifecycle ordering check, vendor workaround, or defensive exception.
2. Capture the original user-facing symptom in plain language. Include the actor, state, trigger, and observed result when known.
3. Capture the evidence-backed cause or strongest diagnosis. Mention logs, crash type, race, protocol mismatch, lifecycle timing, vendor behavior, or data shape only if actually confirmed.
4. Explain why the code returns, retries, waits, no-ops, falls back, or throws. Make clear whether the behavior is a real failure, a deferred retry, or a deliberate compatibility boundary.
5. Add the comment immediately above the relevant code, or as a function/class KDoc when the whole helper exists only for this fix.
6. Re-run the narrowest relevant compile/test command when comments are in source files, especially in Kotlin/Java where comment encoding or formatting can still break builds.

Comment Content Checklist

Include only high-signal items that future readers need:

• Original symptom: what the user saw, such as "background receiver disconnects and app restarts".
• Trigger conditions: platform, lifecycle state, device/vendor, input shape, timing, or protocol step.
• Confirmed evidence: log tag, exception class, crash signal, status code, stack frame, or observed state.
• Fix intent: why this branch exists and why a simpler-looking path is unsafe.
• Retry/fallback semantics: whether returning false, skipping work, or no-op means "try later" rather than "give up".
• Boundaries: note uncertainty or device-specific scope when the root cause is inferred.

Style Rules

• Write comments in the repository's existing language; for Chinese projects, use concise Chinese.
• Do not narrate obvious code mechanics, such as "checks if x is null".
• Do not exaggerate certainty. Use "日志确认", "这里先挡住", or "疑似" according to evidence strength.
• Keep each comment close to the code it protects. Prefer one focused paragraph or 3-8 short comment lines.
• Preserve existing business comments; extend them instead of replacing useful context.
• Avoid TODO-style wording unless follow-up work is actually required.