Fix Bug from GitHub Issue

Workflow

1. Fetch → 2. Analyze → 3. Locate → 4. Reproduce → 5. Plan → 6. Implement → 7. Verify → 8. PR

Step 1: Fetch Issue

# From URL: https://github.com/owner/repo/issues/123
gh issue view 123 --json title,body,labels,comments,state

# From another repo
gh issue view 123 --repo owner/repo --json title,body,labels,comments,state

https://github.com/owner/repo/issues/42

gh issue view 42 --repo owner/repo

#42

42

gh issue view 42

owner/repo#42

gh issue view 42 --repo owner/repo

Step 2: Analyze Issue

• What's broken: Expected vs actual behavior
• Reproduction steps: How to trigger the bug
• Environment: Database type, connection method (DSN, SSH tunnel, TOML config), transport (stdio/HTTP)
• Labels/comments: May reveal affected area or prior investigation
• Linked PRs/issues: Check for related context

Step 3: Locate Relevant Code

src/connectors/{db-type}/index.ts

src/connectors/manager.ts

src/tools/execute-sql.ts

src/utils/allowed-keywords.ts

src/tools/search-objects.ts

src/connectors/{db-type}/index.ts

src/utils/dsn-obfuscate.ts

src/utils/safe-url.ts

src/utils/ssh-tunnel.ts

src/utils/ssh-config-parser.ts

src/config/toml-loader.ts

src/types/config.ts

src/connectors/manager.ts

src/utils/tool-handler-helpers.ts

src/tools/custom-tool-handler.ts

src/tools/registry.ts

src/server.ts

src/utils/allowed-keywords.ts

src/utils/sql-parser.ts

src/utils/sql-row-limiter.ts

src/api/sources.ts

src/api/requests.ts

src/utils/aws-rds-signer.ts

Step 4: Reproduce

• Database connector bugs → extend existing integration test in

  src/connectors/__tests__/

• Utility bugs → add cases to existing unit tests in

  src/utils/__tests__/

• Tool handler bugs → add to

  src/tools/__tests__/

• Config bugs → add to

  src/config/__tests__/

src/__fixtures__/

Step 5: Plan the Fix

EnterPlanMode

Step 6: Implement

• Fix the root cause, not just the symptom
• Keep changes minimal and focused
• Follow existing code conventions (see CLAUDE.md for style guide)
• Use parameterized queries for any database operations
• Validate inputs with zod schemas where appropriate

Step 7: Verify

pnpm test:unit                    # Quick check — no Docker needed
pnpm test src/path/to/test.ts     # Run the specific test file
pnpm test:integration             # Full integration suite if needed

• The failing test (if written) now passes
• No existing tests regressed
• The diff fully addresses the issue

Step 8: Create PR

1. Create a branch:
   bash

   git checkout -b fix/issue-123

2. Commit changes referencing the issue:
   bash

   git add <changed-files>
   git commit -m "$(cat <<'EOF'
   Fix: <short description>
   
   Closes #123
   EOF
   )"

3. Push and create the PR:
   bash

   git push -u origin fix/issue-123
   gh pr create --title "Fix: <short description>" --body "$(cat <<'EOF'
   ## Summary
   <What was broken and how this fixes it>
   
   ## Changes
   <Bullet list of changes>
   
   Closes #123
   
   ## Test plan
   - [ ] Existing tests pass
   - [ ] New test covers the bug scenario (if applicable)
   EOF
   )"

4. Return the PR URL to the user.

Common Mistakes

• Fixing symptoms instead of root cause: Trace the full code path before patching
• Skipping reproduction: A fix without a repro is a guess
• Scope creep: Fix the reported issue, don't refactor surrounding code
• Missing edge cases: Check if the fix handles related scenarios mentioned in comments
• Not testing with the right database: If the bug is database-specific, test with that connector