Skip to main content

identify-bug

Identify and document a bug so the person (or agent) who fixes it has everything they need. Goal: understand + document the problem; do NOT implement the fix unless explicitly asked. Ported from cursor-rules; used by qa-engineer.

When to use​

  • "identify the bug", "analyze this issue", "understand why X is wrong", "document the bug for someone to fix".
  • The user provides any combination of: a description, logs, attachments, screenshots, JAM links, a ClickUp task id/link. No single source is required.

1. Gather inputs (use what's provided)​

  • Description — summary, expected vs actual, repro steps.
  • Logs / stack traces / debug output.
  • Attachments — configs, payloads, JSON, snippets.
  • Screenshots — UI, API responses, DB records.
  • ClickUp task (optional) — fetch the task + its comments via the ClickUp MCP; comments often hold the buggy-vs-expected payloads/documents.
  • JAM links (optional) — session replays; analyze each and record per-link findings (what it shows, what to look for, when to open it, plus user actions / repro steps / console errors / network failures / UI elements / browser).
  • Production logs (optional) — when the bug is backend/prod, use the obs-logs skill (vendor-neutral) to search/analyze.

When critical inputs are missing (no repro, no error evidence), ask for a JAM link, ticket, logs, and/or screenshots before writing the report.

2. Extract the buggy data​

Identify what is wrong (wrong value, missing field, empty state) and what "good" looks like. For JSON/document samples, note which fields are wrong/missing.

3. Map to code + data (when applicable)​

Only when the bug involves data/state/contracts: find the relevant schemas/DTOs/services/config. Use failed network calls (from logs/JAM) to find the API endpoint; UI actions to find the component; recent commits to narrow the cause.

4. Trace the flow + compare​

  • Find where the buggy field is set; follow user action → loaded config → builder/processor → saved/returned data.
  • If a working path exists (another provider/feature that works), trace it too and compare — the single point of difference is the root cause.

5. Write the understanding doc​

A structured report for the fixer + QA:

## Bug: <short title>

**Summary:** <what's wrong, one or two lines>
**Expected vs actual:** <…>
**Repro steps:** <from description/JAM>
**Evidence:** <log excerpt / JAM findings per link / screenshot refs / payloads>
**Root cause (or best hypothesis):** <the differing point in the flow + file:line>
**Affected code/data:** <schemas/DTOs/services/endpoints/components>
**Suggested fix direction:** <where + what, NOT implemented>
**Verification:** <how QA confirms the fix — ties to qa-engineer>

If the root cause isn't certain, state the leading hypothesis + what evidence would confirm it. Do not implement the fix unless asked — hand it off.

Cross-references​

  • qa-engineer — owns testing; consumes the verification section + may turn it into a repro test.
  • obs-logs — for production/backend log evidence (vendor-neutral).
  • backend-developer / frontend-developer — the fixers the doc hands off to.
  • Source: cursor-rules bewith-identify-bug skill (ClickUp + JAM + logs inputs → structured bug doc). The cursor-specific jam-analyzer/mcp-preflight agents are replaced by direct MCP use + the platform agents.