analyse-bug

Type	Skill
Plugin	awl-general · v0.0.51
Invoke	/awl-general:analyse-bug
Source	plugins/awl-general/skills/analyse-bug/SKILL.md

When Claude uses it

Analyses a reported bug systematically — reproduces, isolates root cause, and outputs a structured diagnosis. Use when user says ‘bug’, ‘broken’, ‘not working’, ‘regression’, ‘unexpected behavior’, ‘analyse bug’, ‘debug this’, ‘why does this fail’. Not for feature requests or performance optimization.

Definition

Systematically analyse a reported bug. Produce a concise, structured diagnosis.

Input

The user describes a bug — error message, unexpected behavior, failing test, or stack trace.

Workflow

Step 1: Capture Symptoms

Extract from user input:

• What happens vs what should happen
• Error messages, stack traces, logs
• Steps to reproduce (if provided)
• When it started / what changed recently

If critical info is missing, ask focused questions before proceeding.

Step 2: Locate the Code

Use Grep/Glob to find:

• Files referenced in errors or stack traces
• The function/method where the bug manifests
• Recent changes: git log --oneline -20 and git diff HEAD~5 --name-only to spot recent modifications

Step 3: Trace Root Cause

Read the relevant code paths. Work backwards from the symptom:

1. Where does the error/wrong value originate?
2. What assumption is violated?
3. Is this a regression (worked before) or latent bug?

Use git log -p --follow <file> on suspicious files to find the commit that introduced the issue.

Step 4: Verify Hypothesis

Before reporting, verify your hypothesis:

• Check if the suspected cause actually explains ALL symptoms
• Look for related tests that should have caught this
• Check if the bug exists in other similar code paths

Output Format

Present findings in this exact format:

## Bug Analysis

**Symptom**: [one-line description of what's wrong]

**Root Cause**: [one-line explanation of why it happens]

**Trace**:
  [file:line] → [file:line] → [file:line]
  [brief explanation of the chain]

**Introduced**: [commit hash + date, or "latent" if pre-existing]

**Fix**: [concise description of the fix, with specific file:line references]

**Risk**: [Low/Medium/High — what else could break]

**Related**: [other files/tests affected, or "none"]

Step 5: ClickUp Ticket

After presenting the analysis, ask the user:

Want me to create a ClickUp bug ticket for this?

If yes:

1. Check for saved list: Look in the project’s CLAUDE.md for a clickup-bug-list entry (e.g. clickup-bug-list: <list-id>).

2. If no saved list: Ask the user for the ClickUp list name or ID. After receiving it, offer to save it to the project’s CLAUDE.md under clickup-bug-list: <list-id> so future bugs auto-target the same list.

3. Create the ticket via ClickUp MCP using the Create Task tool:

   • Title: [BUG] <symptom one-liner>

   • Description (markdown):

     ## Symptom
     <symptom>
     
     ## Root Cause
     <root cause>
     
     ## Trace
     <file:line chain>
     
     ## Fix
     <suggested fix>
     
     ## Risk
     <risk level + context>

   • Priority: Map Risk → Priority (High=2, Medium=3, Low=4)

   • Tags: bug

4. Report the created task link back to the user.

Rules

• Do NOT fix the bug — only diagnose. The user decides when to fix.
• Keep output under 20 lines. Detailed traces go in a collapsed section if needed.
• If multiple possible causes exist, rank by likelihood.
• If you cannot determine root cause with confidence, say so and list what you’ve ruled out.