fix

name	fix
description	Diagnose and fix bugs with root-cause analysis and verification. Use when you have a concrete issue report, failing behavior, runtime error, or test regression that should be resolved safely. For ambiguous, high-risk, or broad-scope issues, stop and route to write-plan first.

Fix

Overview

Use this skill to resolve bugs through a structured flow:

1. Intake a clear bug report
2. Reproduce and isolate root cause
3. Apply the smallest safe fix
4. Verify with focused and project-wide checks
5. Document what changed and why

Prefer correctness and safety over speed. Do not guess.

Workflow

Step 1: Bug Report Intake

Collect or confirm the minimum required issue context before changing code.

Required intake fields:

• Title: short bug summary
• Expected behavior: what should happen
• Actual behavior: what happens now
• Reproduction steps: exact steps/inputs
• Evidence: logs, stack trace, screenshots, failing test output
• Environment: branch, OS/runtime, app version/commit (if available)
• Impact: severity and affected users/areas

If key fields are missing, ask targeted follow-up questions first.

Step 2: Reproduce and Diagnose

1. Reproduce the issue consistently.
2. Locate the failure point (file, function, line range, or subsystem).
3. Trace data/control flow to identify the root cause.
4. Define a fix hypothesis and confirm it explains the observed behavior.

Guidelines:

• Read surrounding code, not just the failing line.
• Prefer root-cause fixes, not symptom patches.
• Add temporary diagnostics/logging only if needed to isolate behavior.
• Remove or clean up temporary diagnostics after verification.

Step 3: Complexity Gate (Go / No-Go)

Classify the fix before implementation:

Simple Fix (proceed in this skill)

All or most are true:

• Clear root cause
• Localized change (small surface area)
• Low architectural risk
• Limited file impact
• Verification path is straightforward

Complex/Risky Fix (stop and route to write-plan)

Any are true:

• Root cause still unclear
• Cross-cutting or architectural changes needed
• Significant refactor or migration involved
• High regression risk
• Multi-phase rollout required
• External dependency or infra uncertainty

If complex, stop and recommend creating a plan with write-plan.

Step 4: Implement the Fix (Simple Path)

1. State a brief fix plan in 1-3 bullets.
2. Apply minimal, targeted code changes.
3. Keep behavior changes explicit and scoped.
4. Add/adjust tests to prevent regression when applicable.

Implementation rules:

• Avoid unrelated refactors.
• Preserve existing conventions and project standards.
• Keep changes idempotent and safe to re-run where relevant.

Step 5: Verify

Run verification in increasing scope:

1. Focused checks for the affected module/feature
2. Regression checks for nearby behavior
3. Project checks as relevant (lint/typecheck/tests/build)

Bug is fixed only when:

• Reproduction no longer fails
• Expected behavior is confirmed
• No critical regressions introduced

If verification fails unexpectedly, stop and reassess diagnosis.

Step 6: Complete and Report

Provide a concise completion report:

• Root cause
• What changed
• Why this fix works
• Verification performed and results
• Residual risks / follow-ups (if any)

If architecture, codebase structure, or product behavior changed materially, update documentation artifacts (typically docs/project-pdr.md, docs/codebase.md, docs/architecture.md) via the docs workflow.

Rules

• No guessing: ask when critical context is missing. Follow the AskUserQuestion mandate.
• Root cause first: never ship symptom-only patches knowingly.
• Smallest safe change: minimize blast radius.
• Verify before done: no fix is complete without checks.
• Escalate complexity: use write-plan for risky/broad changes.

Optional Bug Report Template

Use this template when the user provides an incomplete issue report:

• Title:
• Expected behavior:
• Actual behavior:
• Reproduction steps:
• Error logs/stack trace:
• Environment:
• Impact/severity:
• Additional context: