|
| 1 | +--- |
| 2 | +description: Debug and fix a GitHub issue end-to-end — reproduce, fix, test, create PR, and research related issues. |
| 3 | +--- |
| 4 | + |
| 5 | +### User Input |
| 6 | + |
| 7 | +```text |
| 8 | +$ARGUMENTS |
| 9 | +``` |
| 10 | + |
| 11 | +You **MUST** consider the user input before proceeding. The input should be a GitHub issue number (e.g., `1247`) or a full GitHub issue URL. If empty, ask the user for an issue number. |
| 12 | + |
| 13 | +## Goal |
| 14 | + |
| 15 | +Fix a GitHub issue with a minimal, well-tested change and create a PR linked to the issue. After the fix, research the codebase for related patterns that may have the same bug. |
| 16 | + |
| 17 | +## Steps |
| 18 | + |
| 19 | +### Step 1: Fetch and Understand the Issue |
| 20 | + |
| 21 | +1. Determine the target repo from the current git remote (default to `databricks/databricks-jdbc`) and use it as the resolved repo for all subsequent `gh` commands. |
| 22 | +2. Use `gh issue view <number> --repo <resolved-repo>` to fetch the issue title, description, reproduction steps, expected vs actual behavior, and environment details. |
| 23 | +3. Summarize your understanding of the bug to the user and ask for confirmation before proceeding. |
| 24 | + |
| 25 | +### Step 2: Reproduce the Issue |
| 26 | + |
| 27 | +Write a **minimal failing test** that demonstrates the bug: |
| 28 | + |
| 29 | +1. Identify the relevant module and test directory. |
| 30 | +2. Write a unit test that reproduces the exact scenario described in the issue. Prefer unit tests over integration tests when possible. |
| 31 | +3. Run the test and **confirm it fails** with the expected error. Show the failure output to the user. |
| 32 | +4. If the bug requires E2E/integration testing against a live workspace: |
| 33 | + - Verify the required environment variables are set: `DATABRICKS_HOST`, `DATABRICKS_TOKEN`, and `DATABRICKS_HTTP_PATH`. |
| 34 | + - If any are missing, ask the user to set them before proceeding. |
| 35 | + - Ask if they want to proceed with integration tests or stick with unit tests. |
| 36 | + |
| 37 | +### Step 3: Identify Root Cause |
| 38 | + |
| 39 | +1. Use the Explore agent or search tools to trace the code path involved in the bug. |
| 40 | +2. Identify the **minimal set of files and methods** that need to change. |
| 41 | +3. Explain the root cause to the user with file paths and line numbers. |
| 42 | +4. Confirm the fix approach before making changes — keep the blast radius minimal. |
| 43 | + |
| 44 | +### Step 4: Implement the Fix |
| 45 | + |
| 46 | +1. Make the **smallest code change** that fixes the bug. No unrelated refactors, no over-engineering. |
| 47 | +2. Follow existing code patterns and conventions. |
| 48 | +3. Run the failing test from Step 2 and confirm it now **passes**. |
| 49 | +4. Run the full test class to check for regressions. |
| 50 | + |
| 51 | +### Step 5: Add Tests |
| 52 | + |
| 53 | +Ensure adequate test coverage for the fix. **Add tests to existing test suites whenever possible — only create a new test file if absolutely necessary.** |
| 54 | + |
| 55 | +1. The reproduction test from Step 2 should already cover the primary case. |
| 56 | +2. Add edge case tests as needed (e.g., null values, boundary conditions, alternate input formats). Prefer parameterised tests (e.g., JUnit `@ParameterizedTest`) wherever possible to cover multiple inputs concisely. |
| 57 | +3. Add tests for related code paths if the same bug pattern applies (e.g., if a bug in STRUCT also affects ARRAY and MAP, test all three). |
| 58 | +4. Run the full test suite for affected test classes and confirm all pass. |
| 59 | + |
| 60 | +### Step 6: Create PR |
| 61 | + |
| 62 | +1. Ensure the correct GitHub account is active for this repository, following `CLAUDE.md` guidance. Check with `gh auth status` and switch if needed with `gh auth switch --user <account>`. |
| 63 | +2. Create a descriptive branch: `fix/<issue-number>-<short-description>` |
| 64 | +3. Commit with DCO sign-off (`-s` flag) and a clear message referencing the issue. |
| 65 | +4. Push and create a PR with: |
| 66 | + - Title referencing the issue |
| 67 | + - Summary section explaining the bug and fix |
| 68 | + - Test plan section listing all tests added |
| 69 | + - `Closes #<issue-number>` in the body |
| 70 | + - A `NEXT_CHANGELOG.md` entry for user-facing changes, or `NO_CHANGELOG=true` for internal-only changes (see `CLAUDE.md` for guidance; ask the user if unclear) |
| 71 | +5. Share the PR URL with the user. |
| 72 | + |
| 73 | +### Step 7: Research Related Issues |
| 74 | + |
| 75 | +**After the fix is complete**, proactively research the codebase for similar patterns: |
| 76 | + |
| 77 | +1. Search for code that follows the same pattern as the bug (e.g., if a type conversion was wrong for DATE, check if TIMESTAMP, TIME, etc. have the same issue). |
| 78 | +2. Search for similar method calls, switch cases, or conversion logic that could be affected. |
| 79 | +3. Check if the same fix pattern needs to be applied elsewhere (e.g., in `DatabricksArray`, `DatabricksStruct`, or other parsers). |
| 80 | +4. Report findings to the user as a list of potential related issues with file paths and line numbers. |
| 81 | +5. Let the user decide whether to fix those in the same PR or create follow-up issues. |
| 82 | + |
| 83 | +## Important Notes |
| 84 | + |
| 85 | +- Always read files before modifying them. |
| 86 | +- Follow the project's coding conventions (Google Java Style Guide, run `mvn spotless:apply`). |
| 87 | +- Keep changes minimal — fix only what's broken. |
| 88 | +- The reproduction test must fail before the fix and pass after. |
| 89 | +- Research related issues is not optional — always do it as the final step. |
0 commit comments