Fix

Overview

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

Workflow

Step 1: Bug Report Intake

• 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

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.

• 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)

Simple Fix (proceed in this skill)

• 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

)

• 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

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.

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

Step 5: Verify

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

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

Step 6: Complete and Report

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

docs/project-pdr.md

docs/codebase.md

docs/architecture.md

docs

Rules

• No guessing: ask when critical context is missing.
• 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.
• Follow project docs: align with

  docs/

  guidance, especially

  docs/code-standard.md

  .

Optional Bug Report Template

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