home / skills / thebushidocollective / han / fix

fix skill

safe

This skill helps you debug and fix bugs and unexpected behavior in your TypeScript projects by guiding a structured, test-driven repair process.

npx playbooks add skill thebushidocollective/han --skill fix

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.9 KB

---
name: fix
description: Debug and fix bugs, errors, or unexpected behavior

---

# fix

## Name

han-core:fix - Debug and fix bugs, errors, or unexpected behavior

## Synopsis

```
/fix [arguments]
```

## Description

Debug and fix bugs, errors, or unexpected behavior

## Implementation

Investigate, diagnose, and fix bugs or unexpected behavior in the codebase.

## Process

Follow this process to fix bugs:

1. **Reproduce the issue**: Confirm the bug exists and understand when it happens
2. **Gather information**: Error messages, logs, stack traces, user reports
3. **Form hypothesis**: What might be causing the issue?
4. **Investigate**: Use debugging tools, add logging, trace execution
5. **Identify root cause**: Find the actual source of the problem
6. **Implement fix**: Change code to resolve the issue
7. **Verify fix**: Confirm the bug is resolved and no new issues introduced
8. **Add regression test**: Prevent the bug from returning

## Bug Fixing Principles

**Understand before fixing:**

- Don't guess and patch - find the root cause
- Reproduce reliably before attempting fix
- Understand why the bug exists, not just symptoms

**Fix properly:**

- Fix the cause, not symptoms
- Consider edge cases and similar issues
- Add tests to prevent regression
- Document why the fix works

**Verify thoroughly:**

- Original issue resolved
- No new bugs introduced
- Related scenarios still work
- Tests pass (existing + new)

## Examples

When the user says:

- "This function throws an error when passed null"
- "The page crashes on mobile devices"
- "Users report checkout fails intermittently"
- "Fix the memory leak in the background worker"
- "Debug why tests are failing on CI"

## Debugging Techniques

**Add logging:**

```typescript
console.log('Value at checkpoint:', value)
logger.debug('Processing item', { id: item.id, status: item.status })
```

**Use debugger:**

```typescript
debugger;  // Browser will pause here
```

**Binary search:**

- Comment out half the code
- If bug disappears, it's in that half
- Repeat until isolated

**Compare working vs broken:**

- What changed between working and broken?
- Git bisect to find breaking commit
- Compare with known-good version

## Output Format

After fixing:

```markdown
## Bug Fix: [Brief description]

### Issue
[What was broken and how it manifested]

### Root Cause
[Why the bug existed]

### Fix
[What was changed and why it fixes the issue]

### Verification
[Evidence the fix works - use proof-of-work skill]
- Original issue no longer reproduces
- Tests pass (include test output)
- Related scenarios still work

### Prevention
[What test was added to prevent regression]
```

## Notes

- Use TaskCreate to track debugging steps
- Document findings even if you don't find the root cause immediately
- Use proof-of-work skill to show the bug is actually fixed
- Consider using boy-scout-rule skill to improve surrounding code
- Add test to prevent regression (use test-driven-development skill)

Overview

This skill helps debug and fix bugs, errors, or unexpected behavior in a TypeScript codebase. I follow a disciplined process to reproduce issues, identify root causes, implement corrections, and prevent regressions. The goal is reliable fixes with tests and clear documentation of the change.

How this skill works

I reproduce the reported problem and gather diagnostics like logs, stack traces, and user reports. I form hypotheses, use debugging tools and binary search to isolate the faulty code, then implement a targeted fix. After applying the change I verify the outcome with tests and runtime checks, and add a regression test and documentation.

When to use it

A function throws errors or returns incorrect values
Intermittent failures occurring in production or CI
Performance or memory leaks in background workers
Platform-specific crashes (mobile, browser, Node)
When tests start failing after a recent change

Best practices

Reproduce the issue reliably before changing code
Diagnose root cause; avoid symptom-only patches
Use logging, debugger statements, and binary search to isolate faults
Add focused regression tests that fail before the fix and pass after
Document the root cause, fix rationale, and verification steps

Example use cases

Investigate a null-reference error thrown by a utility when given null input
Track down and fix a memory leak in a long-running worker
Resolve intermittent checkout failures reported by users
Repair a crash occurring only on mobile layouts
Diagnose CI test flakiness and add stable tests

FAQ

What evidence should I include after fixing a bug?

Include a concise bug description, root cause, code changes, test output or screenshots showing the issue no longer reproduces, and the new regression test.

How do I avoid introducing new bugs when fixing one?

Limit the scope of changes, run full test suites, add regression tests for the fixed scenario, and verify related features manually or with automated checks.