Workflow for working on a Linear issue
Scope
Use this workflow only when you are explicitly assigned a Linear issue, with an issue ID like
.
Guidelines
Behavioral rules
- Do NOT change issue status unless explicitly required by a workflow step or requested by the user.
- Do NOT run local test, lint, build, or typecheck unless explicitly requested by the user.
- Always keep Linear updated with meaningful progress, especially after fixing CI failures or when the PR becomes ready to merge.
Linear MCP References
- Get Issue - get_issue (MCP)(id: "L-115")
- List Comments - list_comments (MCP)(issueId: "L-115")
- Create Comment: save_comment (MCP)(issueId: "L-115", body: "<comment body>")
- Update commentt: save_comment (MCP)(id: "<comment_id>", issueId: "L-115", body: "<comment body>")
- Delete comment: delete_comment (MCP)(id: "<comment_id>")
Description
You will be assigned an issue with issue ID such as 'L-114'.
You need to strictly follow the steps listed below. You may consider each step as a task.
Goal
Complete the issue by:
- updating the Linear issue
- creating a dedicated git worktree and branch
- planning before implementation
- making the code changes
- opening a GitHub PR linked to the Linear issue
- relying on GitHub Actions for default validation unless the user explicitly requests local validation
Phase 1: Implementation
Step 1: Read and understand the issue
Before making changes:
- Read the issue title, description, comments, and any linked context.
- Identify the expected outcome, constraints, and acceptance criteria.
- If the issue is ambiguous, state the ambiguity clearly in a Linear comment before proceeding.
- Do not start coding until the scope is understood well enough to produce a concrete plan.
Step 2: Update the Linear issue
When starting work:
- Change the issue status to .
- Add a comment that:
- you have started working on it,
- you are creating a branch/worktree,
- you will follow up with implementation progress and a PR link.
Step 3: Create a git worktree and branch
Create a dedicated worktree under:
~/Developer/worktrees/<repo>/<branch>
Branch rules:
- Base the branch on .
- Branch name should follow this format:
linear/<issue-id>-<short-slug>
Example:
linear/L-114-fix-login-timeout
Behavior:
- If the branch does not exist, create it from .
- If the branch already exists locally, reuse it.
- Move into the worktree directory before making changes.
Step 4: Plan before implementation
Before editing code:
- Summarize the issue in your own words.
- Write an implementation plan.
- Identify the files or modules likely to be affected.
- Consider edge cases, risks, and whether tests need to be added or updated.
Step 5: Implement the change
- Make the smallest set of code changes necessary to solve the issue.
- Follow the repository’s existing conventions and patterns.
- Avoid unrelated refactors unless they are required to complete the issue safely.
- If you discover the issue is larger than expected, leave a Linear comment describing the new scope before continuing too far.
Step 6: Prepare for PR
Before opening a PR:
- Review the diff for correctness and unnecessary changes.
- Do NOT run test, lint, build, or typecheck
- Prefer to rely on the repository’s GitHub Actions / CI to perform full validation after the PR is opened.
Step 7: Commit and open a PR
Create a commit and open a PR with GitHub CLI.
PR requirements:
- Push the branch to origin.
- PR title should clearly describe the change.
- PR should merge to branch.
- The first line of the PR description must be:
Example:
After the first line:
- explain the problem,
- describe the implementation,
- summarize validation performed,
- explicitly note that full validation is expected to run in GitHub Actions / CI,
- mention any known limitations or follow-up work.
Phase 2: PR Follow-up
Step 8: Check GitHub Actions results only when explicitly requested
Only perform this step when explicitly notified by the user.
When asked to check PR status or validation results:
• inspect the GitHub PR checks / GitHub Actions results,
• summarize which checks passed, failed, or are still running,
• if a check failed, identify the relevant error clearly,
• make only the changes necessary to address the failure,
• update the branch and push additional commits,
• summarize what was fixed.
Do not proactively wait for CI, poll for results, or repeatedly re-check the PR unless the user explicitly asks.
- After making fixes and pushing updates, add a comment to the Linear issue summarizing:
- what failed,
- what was fixed,
- that CI has been re-run and is expected to validate the changes.
Step 9: Update Linear with PR and follow-up status
After opening a PR OR after any significant PR update (e.g. CI failure fix, CI passing, PR ready):
Add a comment to the Linear issue containing:
- a short summary of what changed,
- current PR status (e.g. CI failed, CI passed, ready to merge),
- whether validation is handled or completed by GitHub Actions / CI,
- any remaining caveats.
Linear Statue: change to 'In Review'
Failure or blocker handling
If you are blocked, add a Linear comment explaining:
- what blocked you
- what you tried
- what is needed to proceed
If you cannot complete the issue safely, do not pretend it is done
Cleanup
Only perform cleanup when explicitly requested by the user
Before performing cleanup:
- Do NOT assume the PR is merged or CI has passed.
- If PR status or CI results are relevant, only use information that has been explicitly checked or provided by the user.
Cleanup may include:
- removing the git worktree
- deleting the local branch
- posting a final Linear comment summarizing:
- the problem
- the plan
- the result
- the PR status or merge status