process-issues · git:20260710.f3f77b6 · 2026-07-10 · sha256 7b0d6780e867c846
process-issues git:20260710.f3f77b6A
Immutable. This exact content never changes and is served at /api/v1/blob/7b0d6780e867c846.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_bfco32bqqahqqsou/7b0d6780e867c846561c8d92e38b180aa405e0284e5ea5a6febacd963f62c03a.json
Then /plugin install process-issues@markdownregistry-bfco32bqqahqqsou in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.
---
name: process-issues
description: Process Linear issues — pick up, fix, and ship one PR per issue. Use when the user asks to process one issue, a specific Linear issue ID, multiple issues, the backlog, or outstanding bugs/features.
metadata:
internal: true
user-invocable: true
---
# Process Issues
Goal: resolve open Linear issues from the **OSS** project by shipping one merged PR per issue, with full `/ship` quality.
This skill is outcome-oriented. Do not blindly walk a fixed checklist. Start from the issue backlog, pick the highest-value work, and drive each issue to a merged PR.
See [`specs/issue-tracking.md`](../../../specs/issue-tracking.md) for project scope and prerequisites.
## When To Use
Use this skill when the user asks to:
- process one Linear issue or a specific issue ID
- process issues or work on Linear issues
- tackle the backlog or fix open issues
- pick up and ship Linear issues
- work through outstanding bugs or features
Invoke this skill even when the request names exactly one issue. A single issue still follows the same ownership, implementation, `/ship`, and Linear-closing workflow.
## Arguments
- `$ARGUMENTS` — Optional: specific issue IDs, priority filter, or project override (defaults to OSS project)
## Required Outcomes
1. **One PR per issue, always.**
- Every issue gets its own branch and PR. No batch PRs. No partial fixes.
- Branch naming: `{issue-id}-{short-description}` from `origin/main` (lowercase kebab-case).
2. **Each PR ships via the `/ship` skill.**
- Always invoke `/ship` using the Skill tool — never duplicate its logic (validation, PR creation, CI checks, merge).
- `/ship` owns the full shipping lifecycle: diff review, simplification, security review, artifact sync, evidence gathering, PR creation, CI wait, and squash merge.
- Each PR must satisfy all `/ship` required outcomes: goal met, validation matches risk, artifacts updated, CI green, PR merged safely.
3. **Issues are fully resolved or explicitly skipped.**
- Resolved: PR merged via `/ship`, issue marked **Done** in Linear with a comment linking the merged PR.
- Skipped: leave a Linear comment only when the current run investigated the issue and the skip is due to a blocker, missing clarification, or missing access. For ownership-only skips, raise the issue to the human user without leaving an automated takeover comment. Leave the issue as **In Progress** or unchanged.
4. **Ownership is checked before pickup.**
- Before touching an issue, inspect its Linear state, `updatedAt`, recent comments, and linked PRs to detect active ownership.
- If the issue is already **In Progress** and was updated within the last 1 day, treat it as actively owned by somebody else and skip it.
- If the issue is already **In Progress** and `updatedAt` is older than 1 day, raise it to the human user as a stale-ownership conflict. Do not auto-take over, auto-reassign, or silently reset the issue.
- If the issue is available to pick up, immediately move it to **In Progress** and assign it before starting analysis or implementation. Do this as the first state-changing action after the ownership check so humans can see the issue is actively owned.
5. **Sequential merging prevents conflicts.**
- After `/ship` merges each PR, rebase remaining open PRs onto updated `main` before shipping the next.
- When multiple PRs touch `Cargo.toml` workspace deps, the second merge can create duplicate key errors — rebase catches this.
- Never ship a PR whose CI ran against a stale base.
6. **A summary report is delivered.**
- Issues completed (with PR links)
- Issues skipped (with reasons)
- Issues raised to the human because stale **In Progress** ownership needed a decision
- Issues that failed (with error details)
## Operating Model
### Prerequisites
Verify environment before starting:
```bash
doppler run -- env | rg 'LINEAR_API_KEY|GITHUB_TOKEN'
doppler run -- bash -lc 'GH_TOKEN="$GITHUB_TOKEN" gh auth status'
```
Linear MCP server must be configured in `.mcp.json`.
### Query and Prioritize
1. Query open issues from the **OSS** project via Linear MCP (apply `$ARGUMENTS` filters if provided)
2. Read each issue's title, description, labels, priority, state, `updatedAt`, recent comments, and linked PRs
3. Check ownership before pickup:
- **In Progress**, updated within 1 day: somebody else is actively working on it; skip
- **In Progress**, updated more than 1 day ago: raise to the human user for a takeover decision; do not auto-claim it
- Any other state: eligible to pick up
4. Sort eligible issues by priority (Urgent > Critical > High > Medium > Low), then oldest first within same priority
5. Select up to **5 issues** to process
### Per-Issue Execution
For each issue, process up to 5 concurrently using subagents:
1. **Pick up immediately** — only after the ownership check passes, mark as **In Progress** in Linear and assign it before analysis, branching, or implementation
2. **Analyze** — parse requirements, search codebase, identify root cause or scope. If ambiguous: comment in Linear requesting clarification, skip
3. **Branch** — `git fetch origin main && git checkout -b {issue-id}-{short-description} origin/main`
4. **Implement** — write the code change:
- Parse issue description and acceptance criteria
- Write failing test first for bugs; validate acceptance criteria for features
- Commit with conventional-commit messages referencing the issue (e.g., `fix(core): resolve X — Fixes EVE-123`)
5. **Ship via `/ship` skill** — invoke `/ship` using the Skill tool to handle validation, PR creation, CI, and merge. **Do NOT** duplicate `/ship` logic (validation, PR creation, merge sequencing) inline — always delegate.
- Pass context: what was implemented, which issue it resolves, the branch name
- `/ship` owns: diff review, simplification, security review, artifact sync, evidence gathering, PR creation, CI wait, and merge
6. **Keep Linear updated** — add Linear comments for major processing milestones when useful for human visibility, especially when opening a PR, discovering a blocker, making a meaningful scope decision, or when CI/review requires substantial follow-up. Keep comments concise and include PR links for PR-related updates
7. **Close** — after `/ship` completes merge: mark issue **Done** in Linear, add comment with merged PR link
### Merge Sequencing
When multiple issues produce PRs, merge sequentially (not in parallel):
1. Let `/ship` merge the first PR (CI must be green)
2. Rebase next PR onto updated `main`, push, then invoke `/ship` for that PR
3. Repeat until all PRs are merged
### Skip Rules
Skip an issue if:
- Already **In Progress** and updated within the last 1 day (active owner)
- Already **In Progress** and older than 1 day until a human decides whether to take it over
- Blocked by external dependency
- Requirements ambiguous and clarification pending
- Requires access/permissions not available
Leave a Linear comment explaining the skip only when the current run actively investigated the issue and the skip is due to a blocker, missing clarification, or missing access. Do **not** leave an automated Linear comment for ownership-only skips: if the issue is already **In Progress** and stale, raise it to the human user for a takeover decision instead.
## Constraints
- Max 5 issues in parallel
- The same workflow applies to a single requested issue and to a batch of issues
- No batch PRs — one PR per issue
- No partial fixes — fully resolve or skip
- No manual deployment steps (CI/CD handles deployment)
- No backward compatibility shims (internal code, just change it)
- **No shipping shortcuts** — always invoke `/ship` via the Skill tool for validation, PR, CI, and merge. Never inline `/ship` logic or skip shipping steps