Fix Linear Issues

The fix-linear-issues skill automates the full lifecycle of resolving a batch of issues in a Linear project. Given a project name, it fetches all open issues, implements fixes using parallel subagents, creates a GitHub PR, runs a closed-loop review process with two different models, and marks each issue as done.

The skill is split into two independent phases that share data through a JSON state file:

Phase	What it does	Can I re-run it?
Setup (PR creation)	Fetch issues → triage → fix → PR → link issues → write state file	No (one-shot: creates the PR)
Review (polish & approve)	Load state file → dual-model review → fix findings → loop up to 3× → summary	Yes — run it again against the same PR

This split means you can:

• Run setup today, review tomorrow.
• Re-run the review phase after a force-push without re-doing the fixes.
• Use only setup if you want a PR without the review loop.

How it works

Phase A — Setup

1. Fetch all open issues from a Linear project
2. Triage each issue: is it still open? Is it blocked by another issue? Is it already assigned to someone else?
3. Locate or clone the GitHub repository
4. 🔴 Confirm local main matches remote main (mandatory — skipped at your peril)
5. Implement fixes in parallel — subagents work on non-overlapping files
6. Build, test, commit, push — create a branch with all fixes
7. Create a PR with a summary of every fix
8. Link each Linear issue to the PR and set state to Done
9. Write a state file (.fix-linear-issues-state.json) for Phase B

Step 2 (the triage gate) is new — it prevents wasted work on issues that are already completed, blocked by another open issue, or owned by someone else. Triage results are reported to you before any code is written.

Phase B — Review

0. Load the state file written by Phase A
1. Verify the PR and branch still exist and are in sync
2. Dispatch two model reviews in parallel (worker-zai + worker-vllm)
3. Classify findings into actionable (critical bugs, correctness issues) and non-actionable (suggestions, nits)
4. Fix actionable findings with a rollback escape — tag the current state, attempt the fix, and if it breaks the build twice, revert and defer that finding instead of burning the iteration budget
5. Repeat the review-fix loop up to 3 iterations
6. Deliver a final summary with PR link, issue list, deferred findings, and merge-readiness status

The rollback protocol (step 4) is new — it prevents a single risky fix from consuming all three review iterations. Each finding gets max 2 attempts; if both fail, the finding is documented as deferred and the loop moves on.

Prerequisites

The skill depends on the linear-cli skill (setup phase only), the pi-gh skill, the pi-subagents skill, and the GitHub CLI:

# Check you have the tools
linear --version
gh auth status

The review phase also requires two worker agents (worker-zai and worker-vllm) for the dual-model review. These are configured separately as pi agent definitions.

Typical usage

# === Full pipeline ===

# 1. Run the setup phase
#    Follow the process in phases/setup/SKILL.md of the skill directory.
#    → Produces .fix-linear-issues-state.json

# 2. Run the review phase
#    Follow the process in phases/review/SKILL.md of the skill directory.
#    → Reads .fix-linear-issues-state.json, delivers final summary

# === Quick shortcut (state file already exists) ===
# Skip setup, go straight to review:
# → Follow phases/review/SKILL.md

# === Quick shortcut (redo setup) ===
rm -f .fix-linear-issues-state.json
# → Follow phases/setup/SKILL.md

Grouping issues for parallel fixes

Issues that touch different files can be fixed in parallel by separate subagents. Issues that touch the same file should be grouped into a single subagent. The skill provides detailed guidance on creating an issue-to-file matrix and dispatching worktree-isolated tasks.

Review loop

After the PR is created, two different models review the changes independently:

Agent	Perspective
worker-zai	ZAI-based model, catches different failure modes
worker-vllm	vLLM-based model, different reasoning patterns

If both models flag the same issue, it is high-confidence. Actionable findings (critical bugs, correctness issues) must be fixed before merging. Suggestions and style nits can be deferred.

The review-fix cycle runs up to 3 iterations or until both reviewers give a clean pass. Before each re-review, the skill checks for merge conflicts — if the PR has become conflicted, the loop stops and flags it for manual resolution.

Rollback escape

Each fix attempt is preceded by tagging the current known-good state (git tag review-loop/N/start). If a fix breaks the build after two attempts, the skill reverts to the tag, classifies the finding as deferred with a reason, and proceeds to the next finding. This prevents a single risky fix from consuming the entire iteration budget.

Anti-patterns to avoid

Pitfall	Why it matters
Rate limiting	The Linear API is strict — insert sleep 1 between every linear call
Stale local main	Always verify your local main matches remote before starting (Phase A, Step 3)
Skipping the triage gate	Fixing issues that are already done, blocked, or assigned to someone else is wasted effort (Phase A, Step 1.5)
Overlapping subagent edits	Never let two subagents edit the same file — group by file path first
Skipping build+test	Rebuild and retest after every code change, no exceptions (Phase B, Step 2)
Runaway fix attempts	Max 2 attempts per review finding, then defer. Don’t burn all 3 iterations on one risky fix (Phase B, Step 2)
Stale state file	Before re-running the review phase, verify the PR is still open and the branch still exists (Phase B, Step 0.5)
Missing shared utilities	Create shared utility files before dispatching subagents (Phase A, Step 4)

File structure

~/.agents/skills/fix-linear-issues/
├── SKILL.md                     # Parent orchestrator (runs both phases)
├── references/
│   ├── list-issues.md           # Linear issue listing reference
│   ├── subagent-grouping.md     # Parallel subagent grouping strategy
│   └── review-loop.md           # Dual-model review protocol
└── phases/
    ├── setup/
    │   └── SKILL.md             # Phase A: issue triage → PR creation
    └── review/
        └── SKILL.md             # Phase B: review loop → final summary

Why it matters

Manually working through a batch of issues is tedious and error-prone. This skill automates the entire pipeline — from Linear to GitHub to review to closing — so you can resolve an entire project’s backlog in a single automated pass. The two-phase split makes it practical to run the phases independently, and the triage gate + rollback protocol catch the two most common failure modes before they waste time.