Exposed Bug Fix Workflow

Fix Bug Skill

Automates the full bug-fix lifecycle for the Exposed project: understand issue, reproduce, fix, validate, and open a PR.

Input Parsing

The user provides one of:

• #123 — GitHub issue in jetbrains/exposed
• EXPOSED-1234 — YouTrack issue ID
• https://youtrack.jetbrains.com/issue/EXPOSED-5678 or https://youtrack.jetbrains.com/issue/EXPOSED-9012/some-slug — YouTrack URL

Parse the input to determine the source:

1. GitHub: Extract the number, fetch via gh issue view NUMBER --repo jetbrains/exposed
2. YouTrack ID (pattern EXPOSED-XXXX): Fetch via the YouTrack MCP (see below)
3. YouTrack URL: Extract the EXPOSED-XXXX ID from the URL, then fetch via the YouTrack MCP (see below)

Fetching YouTrack Issues

Use the YouTrack MCP tools to fetch issue details. Call mcp__youtrack__get_issue with the issue ID (e.g., EXPOSED-1234).

If the YouTrack MCP server is not configured (tool calls fail), instruct the user to set it up:

claude mcp add --header "Authorization: Bearer <token>" --transport http youtrack https://youtrack.jetbrains.com/mcp

The permanent token can be created in JetBrains Hub account security settings (linked from YouTrack profile).

From the issue, extract:

• Title and description of the bug
• Steps to reproduce (if provided)
• Expected vs actual behavior
• Affected module(s) — identify which Exposed Gradle module is relevant
• Affected databases - identify which databases are affected by the issue, these databases could be used for reproducer tests first
• Issue comments — read through comments as they might contain useful information (reproduction details, workarounds, related context)
• Issue ID for branch naming and commit messages (e.g., EXPOSED-1234 or #123)

Step 1: Assign Issue and Set In Progress

For YouTrack issues only, update the issue status to reflect that work is starting:

1. Call mcp__youtrack__get_current_user to get the current user's login.
2. Call mcp__youtrack__change_issue_assignee to assign the issue to the current user.
3. Call mcp__youtrack__update_issue with customFields: {"State": "In Progress"} to mark work as started.

If any of these calls fail because the YouTrack MCP is not configured, inform the user how to set it up (see "Fetching YouTrack Issues" section above) and continue with the rest of the workflow — issue tracking updates are not blocking.

Skip this step for GitHub-only issues.

Step 1.1: Save the information about the issue to file

Save the issue as a json file under issues directory.

Github issues should be saved in the /issues/github/ directory. The json file of the issue should be named as the issue number github-<id>.json

Youtrack issues should be saved in the /issues/youtrack/ directory. The json file of the issue should be named as the issue number youtrack-<id>.json

Step 2: Understand the Codebase Context

Before creating a branch, understand the affected area:

• Check the CLAUDE.md file in the root of the project to get basic information about the project.
• Identify the Gradle module from the issue description or affected APIs
• Read existing tests in that module to understand test patterns and conventions
• Identify whether this needs a unit test or integration test based on the bug nature
• Remember: this project uses a flattened Gradle structure

Use the Explore agent or direct file reads to understand:

• The relevant source code where the bug likely lives
• Existing test infrastructure (test utilities, base classes, server setup patterns)
• How similar tests are structured in the same module

Step 3: Create branch

Determine the base branch:

• Use main branch for creating new branch that will be used for the PR with the fix

git checkout <base-branch> && git pull && git checkout -b claude/<issue-id>-<short-description>

Branch naming rules:

• For YouTrack issues: claude/EXPOSED-1234-short-description
• For GitHub issues: claude/123-short-description
• The short description is 3 words max, lowercase, hyphenated, derived from the issue title

Step 4: Write a Failing Reproducer Test

Write a test that demonstrates the bug as described in the issue. The goal is:

• Minimal: Only test the specific buggy behavior, nothing extra
• Clear: Test name in backticks should describe what it checks (e.g., `requestWithEmptyBodyDoesntCausesNPE`)
  • Comment of the test should say what is the issues that caused necessity in this test (e.g., /* EXPOSED-9352 request with empty body causes NPE */)
• Failing: The test MUST fail on the current codebase to confirm the bug exists

Place the test appropriately:

• Primary test modules: exposed-tests (JDBC) and exposed-r2dbc-tests (R2DBC)
  • Core DSL and DAO functionality tests go here
  • Many features that work with both drivers should have tests in both modules
• Extension module tests: If the bug is in an extension module, add tests there:
  • exposed-java-time, exposed-jodatime, exposed-kotlin-datetime for date/time issues
  • exposed-json for JSON column type issues
  • exposed-crypt for encrypted column issues
  • exposed-money for monetary amount issues
  • exposed-migration-jdbc, exposed-migration-r2dbc for migration issues
  • exposed-spring-boot-starter, spring-transaction for Spring integration issues
• Database-specific tests: If the feature is only relevant to specific databases, exclude other databases from the test using the excludeSettings parameter in test helper functions

After writing the test, run it to confirm it fails:

./gradlew gradle :exposed-tests:test --tests "fully.qualified.TestClassName.methodName"

./gradlew gradle :exposed-r2dbc-tests:test --tests "fully.qualified.TestClassName.methodName"

Tests for specific databases could be run in isolation. For example for the H2 it will be the following commands:

./gradlew gradle :exposed-tests:test_h2_v2 --tests "fully.qualified.TestClassName.methodName"

./gradlew gradle :exposed-r2dbc-tests:test_h2_v2 --tests "fully.qualified.TestClassName.methodName"

You must verify that the tests are compiled without errors. The tests should fail according to the test assertions only.

If the test passes (bug is already fixed or test doesn't reproduce correctly):

• Re-read the issue carefully
• Adjust the test to more precisely match the reported scenario
• If the bug truly cannot be reproduced, inform the user and stop

Step 5: Commit the Reproducer

Stage and commit the failing test. All the commit message should follow the Conventional Commits format:

git add <test-file>
git commit -m "fix: <ISSUE-ID> Add failing test for <short bug description>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>"

For GitHub issues, use #NUMBER in the commit message. For YouTrack, use EXPOSED-XXXX.

Step 6: Plan the Fix

Analyze the bug based on what you learned from the issue and the reproducer test:

• Trace the code path that leads to the failure
• Identify the root cause
• Plan the minimal fix

Present your analysis and plan to the user for review. Include:

• Root cause: What is causing the bug?
• Proposed fix: What changes will be made and where?
• Approach: Why is this the right solution?
• Scope: Confirm the fix is minimal and focused

Wait for user approval before implementing.

If user provides additional context, concerns, or feedback, take it into account, and repeat Step 6 with the new input

Step 7: Implement the Fix

After receiving user approval, implement the planned fix. Keep changes minimal and focused:

• Fix only the bug, do not refactor surrounding code
• Do not add features beyond what's needed
• Preserve existing comments and code style