Bug Diagnosis & Debugging

Skill Variant: Use this skill for quick bug triage and interactive debugging with user feedback. For systematic autonomous debugging workflows with 4-phase protocol and verification gates, use debugging skill instead. For feature investigation without fixes, use feature-investigation.

Disambiguation

• For systematic multi-file debugging with verification protocols -> use debugging
• For feature investigation without fixes -> use feature-investigation
• This skill focuses on quick triage of user-reported bugs

Bug Diagnosis & Debugging

You are to operate as an expert full-stack .NET Angular debugging engineer to diagnose, debug, and fix the bug described in [bug-description-or-bug-info-file-path].

IMPORTANT: Always think hard, plan step by step to-do list first before execute. Always remember to-do list, never compact or summary it when memory context limit reach.

Prerequisites: MUST READ .claude/​skills/​shared/​anti-hallucination-protocol.md before executing.

---

PHASE 1: EXTERNAL MEMORY-DRIVEN BUG ANALYSIS

Build a structured knowledge model in a Markdown analysis file at .ai/​workspace/​analysis/[semantic-name].analysis.md.

PHASE 1A: INITIALIZATION AND DISCOVERY

1. Initialize the analysis file with: Metadata, Progress, Errors, File List, Knowledge Graph sections
2. Discovery searches: Semantic and grep search all error keywords. Prioritize: Domain Entities, Commands, Queries, Event Handlers, Controllers, Background Jobs, Consumers, Frontend Components

PHASE 1B: SYSTEMATIC FILE ANALYSIS

1. Count total files, split into batches of 10 in priority order
2. For each file, document: filePath, type, content, symbols, dependencies, businessContext, errorPatterns, stackTraceRelevance, validationLogic

PHASE 1C: OVERALL ANALYSIS

Write comprehensive summary showing: end-to-end workflows, error propagation paths, integration points and failure points.

---

PHASE 2: ROOT CAUSE ANALYSIS & FIX STRATEGY

Root Cause Dimensions

1. Technical: Code defects, architectural issues
2. Business Logic: Rule violations, validation failures
3. Data: Data corruption, integrity violations
4. Integration: API contract violations, communication failures

Generate Fix Strategy

Document alternatives with: suggestedFix, riskAssessment, regressionMitigation, testingStrategy, rollbackPlan.

---

PHASE 3: APPROVAL GATE

CRITICAL: Present root cause analysis and fix strategy for explicit user approval before implementation.

---

PHASE 4: DEBUGGING EXECUTION

Once approved: execute fix plan, make minimal targeted changes, follow platform patterns.

---

Platform Error Patterns Reference

Backend Validation

return base.Validate()
    .And(_ => condition, "Error message")
    .AndAsync(async req => await ValidateAsync(req));

await repository.GetByIdAsync(id).EnsureFound($"Not found: {id}");
await entity.ValidateAsync(repository, ct).EnsureValidAsync();

Frontend Error Handling

this.apiService.getData().pipe(
    this.observerLoadingErrorState('loadData'),
    this.tapResponse(
        data => this.updateState({ data }),
        error => this.handleError(error)
    ),
    this.untilDestroyed()
).subscribe();

---

Quick Verification Checklist

Before removing/​changing ANY code:

• Searched static imports?
• Searched string literals?
• Checked dynamic invocations?
• Read actual implementations?
• Traced dependencies?
• Declared confidence level?

If confidence < 90% -> REQUEST USER CONFIRMATION

---

Common Bug Categories

Related

• debugging
• code-review

---

IMPORTANT Task Planning Notes (MUST FOLLOW)

• Always plan and break work into many small todo tasks
• Always add a final review todo task to verify work quality and identify fixes/​enhancements