AI Debug

Figure out why an existing AI feature is broken.

Works with:

• Linear MCP - Pull issue/bug details
• Manual - Describe the symptoms

Entry Point

When this skill is invoked, start with:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 AI DEBUG
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

When AI fails, teams blame the model.
But 90% of failures are context failures.

What's going wrong?

  1. Provide a Linear issue ID
  2. Describe the symptoms

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Usage

/ai-debug                 # Describe symptoms manually
/ai-debug LIN-123         # Start from Linear bug/issue

What It Does

Works backwards from symptoms to root cause using the 4D audit:

Key insight: When AI fails, teams blame the model. But 90% of failures are context failures.

The 4D Audit

D1: Was the Job Defined?

• Can you articulate exactly what the model should produce?
• Is there a written spec for inputs, outputs, constraints?
• Do engineers and PMs agree on what "good" looks like?

D2: Is Context Right?

• What context is the model actually receiving?
• Walk through the 6 layers: Intent, User, Domain, Rules, Environment, Exposition
• Is context structured or dumped as raw text?
• Is there too much context (token bloat)?

D3: Is Context Fetched Reliably?

• How is each piece of context being fetched at runtime?
• What happens when a data source is unavailable?
• Is there visibility into what context is used per request?

D4: Are Failures Being Caught?

• Are there pre-checks before calling the model?
• Are there post-checks validating output?
• What's the fallback UX when things break?
• Is there a feedback loop capturing failures?

Output

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 CONTEXT AUDIT COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Feature: [Name]
Symptoms: [What was reported]

  D1 Demand:      [CLEAR / GAP / CRITICAL]
  D2 Data:        [CLEAR / GAP / CRITICAL]
  D3 Discovery:   [CLEAR / GAP / CRITICAL]
  D4 Defense:     [CLEAR / GAP / CRITICAL]

Primary Issue: [Root cause summary]

RECOMMENDED FIXES (prioritized):
1. [Highest impact fix]
2. [Second fix]
3. [Third fix]

Quick Win: [Smallest change that would help]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Workflow

1. Collect symptoms (what's going wrong)
2. Map symptoms to likely causes using the table above
3. Audit each D dimension with diagnostic questions
4. Identify root cause and prioritize fixes
5. Offer to add findings to Linear or export

Questions to ask at each step:

• "What specific behavior are you seeing?"
• "What should it be doing instead?"
• "When did this start happening?"
• "Does it happen every time or intermittently?"

Framework: 4D Context Canvas (Aakash Gupta & Miqdad Jaffer) Best for: Debugging hallucinations, inconsistency, performance issues in AI features