// Diagnose and fix bugs through systematic investigation, root cause analysis, and targeted validation. Use when something is broken, errors occur, performance degrades, or unexpected behavior manifests.
| name | Fixing Bugs Systematically |
| description | Diagnose and fix bugs through systematic investigation, root cause analysis, and targeted validation. Use when something is broken, errors occur, performance degrades, or unexpected behavior manifests. |
Structured protocol for isolating root causes and implementing focused fixes in existing features.
Read relevant documentation:
docs/feature-spec/F-##-*.md for affected featuredocs/user-stories/US-###-*.md for expected behavior and acceptance criteriadocs/api-contracts.yaml if API-relateddocs/system-design.md for architecture contextDocument the bug:
Use direct investigation:
Delegate to async agents in parallel:
Spawn senior-engineer agents to:
Spawn Explore agents to:
Example: For authentication bug, spawn:
Wait for results using ./agent-responses/await {agent_id}
Generate hypotheses:
Decision point:
Add minimal debugging:
Test to confirm root cause before proceeding to fix.
Fix the confirmed root cause:
Update documentation if needed:
docs/api-contracts.yaml if contract changed (requires approval)/manage-project/update/update-feature to correct spec/manage-project/update/update-story if ACs were ambiguous/manage-project/update/update-api if API changed (with approval)Verify fix against acceptance criteria:
docs/data-plan.md still fire correctlyFor direct investigation:
When to validate before fixing:
For async investigation:
Inputs:
docs/feature-spec/F-##-*.md — Feature specsdocs/user-stories/US-###-*.md — Expected behavior and ACsdocs/api-contracts.yaml — API specsdocs/system-design.md — Architecture contextOutputs:
| Scenario | Approach |
|---|---|
| Single subsystem, obvious entry | Direct investigation → immediate fix |
| Multiple subsystems, unclear origin | Spawn 2-4 agents in parallel → synthesize findings → fix |
| Runtime-dependent or intermittent | Add targeted logging → reproduce → analyze logs → fix |
| Multiple independent fixes needed | Pass investigation results to fix agents via artifact files |
Defines required structure, frontmatter format, and best practices for SKILL.md files. Use BEFORE creating or editing any skill - this is the spec to follow, not optional reference.
Systematically evaluate code changes for security, correctness, performance, and spec alignment. Use when reviewing PRs, assessing code quality, or verifying implementation against requirements.
Maintain project documentation synchronized with code. Keep feature specs, API contracts, and README current with init-project standards. Use when updating docs after code changes, adding new features, or ensuring documentation completeness.
Systematically trace code flows, locate implementations, diagnose performance issues, and map system architecture. Use when understanding how existing systems work, researching concepts, exploring code structure, or answering "how/where/why is X implemented?" questions.
Coordinate concurrent task execution through agent delegation. Plan independent work, manage dependencies, and execute multiple agents simultaneously. Use when handling multiple unrelated tasks, research investigations, or layer-based implementations that can run concurrently.
Create structured implementation plans before coding. Use when breaking down complex features, refactors, or system changes. Validates requirements, analyzes codebase impact, and produces actionable task breakdowns with identified dependencies and risks.