name: bug-diagnosis
version: 2.0.1
description: "[Fix & Debug] Quick triage skill for initial bug assessment and user-reported issues. Use for bug reports, error reports, quick diagnosis, initial triage, "what's causing", "why is this failing". For systematic multi-file debugging with verification protocols, use debug skill instead."
infer: true
allowed-tools: Read, Write, Edit, Bash, Grep, Glob, Task, WebFetch, WebSearch, TodoWrite
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 debug skill instead. For feature investigation without fixes, use investigate.
Summary
Goal: Quick triage and diagnosis of user-reported bugs with external memory-driven analysis and approval gate before fixing.
| Step |
Action |
Key Notes |
| 1 |
Initialize analysis |
Create .ai/workspace/analysis/[name].analysis.md with structured sections |
| 2 |
Discovery & file analysis |
Semantic search, batch files in groups of 10, document dependencies |
| 3 |
Root cause analysis |
Rank causes across technical, business logic, data, integration dimensions |
| 4 |
Approval gate |
Present findings and fix strategy -- DO NOT fix without user approval |
| 5 |
Execute fix |
Minimal targeted changes following platform patterns |
Key Principles:
- Always use external memory file for structured analysis -- never rely on context alone
- If confidence < 90%, request user confirmation before proceeding
- For systematic multi-file debugging, use
debug skill instead
Disambiguation
- For systematic multi-file debugging with verification protocols -> use
debug
- For feature investigation without fixes -> use
investigate
- 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
- Initialize the analysis file with: Metadata, Progress, Errors, File List, Knowledge Graph sections
- 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
- Count total files, split into batches of 10 in priority order
- 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
- Technical: Code defects, architectural issues
- Business Logic: Rule violations, validation failures
- Data: Data corruption, integrity violations
- 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:
If confidence < 90% -> REQUEST USER CONFIRMATION
Common Bug Categories
| Category |
Examples |
| Data Issues |
Missing null checks, race conditions, stale cache |
| Validation |
Missing rules, bypassed validation, async not awaited |
| Cross-Service |
Message bus failures, sync ordering, API contract mismatches |
| Frontend |
Lifecycle issues, state bugs, missing error handling |
| Authorization |
Missing role checks, wrong company context |
Related
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
1---2name: bug-diagnosis-53description: > 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 debug skill instead. For feature investigation without fixes, use investigate.4---56---7name: bug-diagnosis8version: 2.0.19description: "[Fix & Debug] Quick triage skill for initial bug assessment and user-reported issues. Use for bug reports, error reports, quick diagnosis, initial triage, "what's causing", "why is this failing". For systematic multi-file debugging with verification protocols, use `debug` skill instead."10infer: true11allowed-tools: Read, Write, Edit, Bash, Grep, Glob, Task, WebFetch, WebSearch, TodoWrite12---1314> **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 `debug` skill instead. For feature investigation without fixes, use `investigate`.1516## Summary1718**Goal:** Quick triage and diagnosis of user-reported bugs with external memory-driven analysis and approval gate before fixing.1920| Step | Action | Key Notes |21|------|--------|-----------|22| 1 | Initialize analysis | Create `.ai/workspace/analysis/[name].analysis.md` with structured sections |23| 2 | Discovery & file analysis | Semantic search, batch files in groups of 10, document dependencies |24| 3 | Root cause analysis | Rank causes across technical, business logic, data, integration dimensions |25| 4 | Approval gate | Present findings and fix strategy -- DO NOT fix without user approval |26| 5 | Execute fix | Minimal targeted changes following platform patterns |2728**Key Principles:**29- Always use external memory file for structured analysis -- never rely on context alone30- If confidence < 90%, request user confirmation before proceeding31- For systematic multi-file debugging, use `debug` skill instead3233## Disambiguation3435- For **systematic multi-file debugging** with verification protocols -> use `debug`36- For **feature investigation** without fixes -> use `investigate`37- This skill focuses on **quick triage** of user-reported bugs3839# Bug Diagnosis & Debugging4041You 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]`.4243**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.4445**Prerequisites:** **MUST READ** `.claude/skills/shared/anti-hallucination-protocol.md` before executing.4647---4849## PHASE 1: EXTERNAL MEMORY-DRIVEN BUG ANALYSIS5051Build a structured knowledge model in a Markdown analysis file at `.ai/workspace/analysis/[semantic-name].analysis.md`.5253### PHASE 1A: INITIALIZATION AND DISCOVERY54551. **Initialize** the analysis file with: Metadata, Progress, Errors, File List, Knowledge Graph sections562. **Discovery searches**: Semantic and grep search all error keywords. Prioritize: Domain Entities, Commands, Queries, Event Handlers, Controllers, Background Jobs, Consumers, Frontend Components5758### PHASE 1B: SYSTEMATIC FILE ANALYSIS59601. Count total files, split into batches of 10 in priority order612. For each file, document: filePath, type, content, symbols, dependencies, businessContext, errorPatterns, stackTraceRelevance, validationLogic6263### PHASE 1C: OVERALL ANALYSIS6465Write comprehensive summary showing: end-to-end workflows, error propagation paths, integration points and failure points.6667---6869## PHASE 2: ROOT CAUSE ANALYSIS & FIX STRATEGY7071### Root Cause Dimensions72731. **Technical**: Code defects, architectural issues742. **Business Logic**: Rule violations, validation failures753. **Data**: Data corruption, integrity violations764. **Integration**: API contract violations, communication failures7778### Generate Fix Strategy7980Document alternatives with: suggestedFix, riskAssessment, regressionMitigation, testingStrategy, rollbackPlan.8182---8384## PHASE 3: APPROVAL GATE8586**CRITICAL**: Present root cause analysis and fix strategy for explicit user approval before implementation.8788---8990## PHASE 4: DEBUGGING EXECUTION9192Once approved: execute fix plan, make minimal targeted changes, follow platform patterns.9394---9596## Platform Error Patterns Reference9798### Backend Validation99```csharp100return base.Validate()101 .And(_ => condition, "Error message")102 .AndAsync(async req => await ValidateAsync(req));103104await repository.GetByIdAsync(id).EnsureFound($"Not found: {id}");105await entity.ValidateAsync(repository, ct).EnsureValidAsync();106```107108### Frontend Error Handling109```typescript110this.apiService.getData().pipe(111 this.observerLoadingErrorState('loadData'),112 this.tapResponse(113 data => this.updateState({ data }),114 error => this.handleError(error)115 ),116 this.untilDestroyed()117).subscribe();118```119120---121122## Quick Verification Checklist123124Before removing/changing ANY code:125- [ ] Searched static imports?126- [ ] Searched string literals?127- [ ] Checked dynamic invocations?128- [ ] Read actual implementations?129- [ ] Traced dependencies?130- [ ] Declared confidence level?131132**If confidence < 90% -> REQUEST USER CONFIRMATION**133134---135136## Common Bug Categories137138| Category | Examples |139|----------|---------|140| Data Issues | Missing null checks, race conditions, stale cache |141| Validation | Missing rules, bypassed validation, async not awaited |142| Cross-Service | Message bus failures, sync ordering, API contract mismatches |143| Frontend | Lifecycle issues, state bugs, missing error handling |144| Authorization | Missing role checks, wrong company context |145146## Related147148- `debug`149- `code-review`150151---152153**IMPORTANT Task Planning Notes (MUST FOLLOW)**154- Always plan and break work into many small todo tasks155- Always add a final review todo task to verify work quality and identify fixes/enhancements
majiayu000