name	linear-issue-fixer
description	Fetch the most urgent Linear issue with tag "studio" and size XS, then fix it
invocation	user
argument-hint	Optional issue ID to work on a specific issue

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:

Root Cause / Current State
- What is the current behavior?
- Why does it need to change?
Proposed Solution
- What changes are needed?
- Which files need modification?
- Are there related areas to consider?
Risk Assessment
- Could this fix break other functionality?
- Does it need backward compatibility?
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

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.

Make Code Changes
- Implement the planned fix
- Follow codebase conventions
- Add appropriate error handling
- Add or update tests

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:

Push the branch to origin
Analyze the diff against main
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

Size	Points	Typical Scope
XS	1	Trivial fix, typo, config change
S	2	Simple bug fix, small feature
M	3	Moderate feature, multiple files
L	5	Large feature, significant changes
XL	8+	Epic-level work

Linear MCP Tools Reference

Tool	Purpose
`linear_search_issues`	Find issues with filters (labels, priority, status)
`linear_update_issue`	Update issue status, assignee, etc.
`linear_add_comment`	Add comment to an issue
`linear_create_issue`	Create new issues
`linear_get_user_issues`	Get issues assigned to a user

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"