Linear Issue Fixer

Automatically fetch the most urgent Linear issue with the "studio" label and "XS" size estimate, analyze it, implement a fix, verify with tests, and create a pull request.

Prerequisites

• Linear MCP server connected
• GitHub CLI (gh) authenticated
• Docker running (for integration tests)
• Python 3.12 with virtualenv
• Checkout main branch and pull the latest changes

Linear MCP Server Setup

If Linear MCP is not configured, set it up first:

claude mcp add --transport sse linear https://mcp.linear.app/sse

Then restart Claude Code and run /mcp to authenticate with Linear via OAuth.

Alternatively, add via JSON:

claude mcp add-json linear '{"command": "npx", "args": ["-y","mcp-remote","https://mcp.linear.app/sse"]}'

To troubleshoot auth issues:

rm -rf ~/.mcp-auth

Workflow

Step 1: Fetch Candidate XS Studio Issues

Use Linear MCP tools to find candidate issues:

1. First, check Linear MCP is connected:
   Run /mcp to verify "linear" server is connected

2. Search for issues with "studio" label and XS size:
   Use list_issues with:
   - label: "studio"
   - Sort by priority (highest first)
   - limit: 10

3. Filter results to find XS-sized issues:
   - Look for issues with estimate/size "XS" or 1 point
   - Prioritize by urgency: Urgent > High > Medium > Low

4. If a specific issue ID was provided as argument, fetch that instead:
   $ARGUMENTS

Priority Levels in Linear:

• 1 = Urgent
• 2 = High
• 3 = Medium
• 4 = Low
• 0 = No priority

Step 2: User Selection

IMPORTANT: Always ask the user to select which issue to work on.

Present the candidate issues to the user with:

• Issue identifier (e.g., DXP-123)
• Title
• Priority level
• Size estimate
• Brief description summary

Use the AskUserQuestion tool to let the user choose which issue to work on. Do NOT proceed with an issue automatically - always wait for user confirmation.

Example prompt:

I found the following XS studio issues:

1. DXP-456 [High] "Fix address validation" - XS
2. DXP-789 [Medium] "Update error message" - XS
3. DXP-012 [Low] "Typo in config" - XS

Which issue would you like me to work on?

Step 3: Analyze the Selected Issue

Once the user has selected an issue:

1. Get full issue details including:
   - Title and description
   - Current status
   - Any linked issues or dependencies
   - Comments with context
   - Acceptance criteria

2. Understand the scope:
   - What files are likely affected?
   - Is this a bug fix, feature, or improvement?
   - Are there any blocking dependencies?

Gather from analysis:

• Issue type (bug, feature, task, improvement)
• Affected area (backend, frontend, infrastructure)
• Expected behavior vs current behavior
• Acceptance criteria
• Related files mentioned in description

Step 4: Explore the Codebase

Before implementing, understand the relevant code:

1. Launch an Explore agent to find relevant code:
   - Search for files/functions mentioned in the issue
   - Understand the existing implementation
   - Identify patterns and conventions used

2. Read key files that will need modification

3. Check for existing tests covering the affected area

Step 5: Plan the Fix

Create a clear implementation plan:

1. Root Cause / Current State
   • What is the current behavior?
   • Why does it need to change?
2. Proposed Solution
   • What changes are needed?
   • Which files need modification?
   • Are there related areas to consider?
3. Risk Assessment
   • Could this fix break other functionality?
   • Does it need backward compatibility?
4. Testing Strategy
   • What unit tests should be added/modified?
   • What integration tests are relevant?

Present the plan to the user and get approval before implementing.

Step 6: Implement the Fix

1. Create a Feature Branch

   git checkout main
   git pull origin main
   git checkout -b <issue-identifier>-<short-description>

   Use the Linear issue identifier (e.g., DXP-123) as branch prefix.

2. Make Code Changes
   • Implement the planned fix
   • Follow codebase conventions
   • Add appropriate error handling
   • Add or update tests
3. Commit Changes

   git add <files>
   git commit -m "<type>: <description>
   
   Resolves <LINEAR-ISSUE-ID>
   
   Co-Authored-By: Claude <noreply@anthropic.com>"

Step 7: Run ALL Test Suites

IMPORTANT: You MUST run ALL of the following test suites before creating a PR. Do NOT skip any.

7.1 DB/SQLAlchemy Tests (Primary Backend Tests - Dockerized)

docker compose -f tests/db-sqlalchemy/docker-compose.yml --project-directory . run --build --rm tests

7.2 Backend Unit Tests

.venv/bin/pytest tests/unit/ -v --tb=short --ignore=tests/unit/test_rpc_endpoint_manager.py

7.3 Frontend Unit Tests

cd frontend && npm run test

If any tests fail:

• Analyze the failure
• Fix the issue
• Re-run ALL test suites until they pass

Step 8: Run Integration Tests (if needed)

For changes that affect runtime behavior:

# Ensure Docker is running with the studio
docker compose up -d

source .venv/bin/activate
export PYTHONPATH="$(pwd)"

# Run integration tests
gltest --contracts-dir . tests/integration -n 4 --ignore=tests/integration/test_validators.py

Step 9: Create Pull Request

Use the /create-pr skill to create the pull request.

This skill will:

1. Push the branch to origin
2. Analyze the diff against main
3. Create a PR with the proper template format

Make sure to include the Linear issue URL in the PR body with Fixes <LINEAR-ISSUE-URL> so the issue gets linked automatically.

Step 10: Update Linear Issue

After PR is created:

1. Add a comment to the Linear issue with:
   - Link to the PR
   - Brief summary of the implementation

2. Update issue status to "In Review" or appropriate status

Use linear_add_comment and linear_update_issue tools

Issue Size Reference

Linear MCP Tools Reference

Common Search Patterns

# Find urgent studio issues
linear_search_issues(labels=["studio"], priority=1)

# Find all studio issues sorted by priority
linear_search_issues(labels=["studio"], limit=20)

# Find in-progress issues
linear_search_issues(status="In Progress", teamId="...")

Troubleshooting

Linear MCP Not Connected

• Run claude mcp list to check status
• Run /mcp to trigger authentication
• Clear auth with rm -rf ~/.mcp-auth and retry

Cannot Find Issues

• Verify the "studio" label exists in your Linear workspace
• Check you have access to the relevant team
• Try searching without filters first

Tests Failing

• Check Docker is running: docker compose ps
• View logs: docker compose logs -f
• Run specific test file to isolate issue

Example Session

1. Check Linear MCP connection:
   > /mcp
   > linear: Connected

2. Search for XS studio issues:
   > list_issues(label="studio")
   > Found 3 XS issues

3. Ask user to select:
   > "Which issue would you like to work on?"
   > 1. DXP-456 [High] "Fix address validation" - XS
   > 2. DXP-789 [Medium] "Update error message" - XS
   > User selects: DXP-456

4. Analyze selected issue:
   - Bug: addresses without 0x prefix cause validation errors
   - Affected: backend validation logic
   - Acceptance: addresses like "abc123..." should be accepted

5. Explore codebase:
   - Find address validation code
   - Understand current validation logic

6. Plan fix:
   - Add normalization to accept addresses without prefix
   - Add unit test for edge case

7. Implement:
   - Edit validation.py
   - Add test_address_without_prefix.py

8. Test:
   - docker compose -f tests/db-sqlalchemy/docker-compose.yml run tests
   - All pass

9. Create PR:
   - Use /create-pr skill
   - Include "Fixes https://linear.app/genlayer/issue/DXP-456"

10. Update Linear:
    - Add PR link as comment
    - Move to "In Review"