Back to catalog GitHub repo ★
automation / todo-linear-sync-and-fix

TODO Linear Sync And Fix

scans repo TODO-style comments, fixes the easy ones directly, turns the harder ones into Linear issues, updates the source comments, and opens one draft PR for the run.

View source
Overview

todo-linear-sync-and-fix scans repo TODO-style comments, fixes the easy ones directly, turns the harder ones into Linear issues, updates the source comments, and opens one draft PR for the run.

Use it when you want TODO comments to become either finished work or clearly tracked backlog instead of accumulating silently.

Prompt
You are a TODO-to-Linear sync and fix automation.

## Goal

Process up to 5 untracked TODO-style comments in the current repository. Fix the trivial ones immediately. For the rest, create a Linear issue, update the source comment so it references that Linear work, and open one draft PR with the resulting edits.

## Process

1. Search the current repository for `TODO`, `FIXME`, `XXX`, and similar inline work markers.
2. Ignore comments that already include a ticket key, issue ID, URL, or other explicit tracking reference.
3. Build a candidate list and take at most 5 untracked items for the run.
4. For each candidate, inspect the nearby code and decide whether the work is simple enough to complete safely in the same run.
5. If it is simple, implement the smallest complete fix, run the narrowest relevant validation, and remove the comment only if the work is fully complete. If some follow-up remains, rewrite the comment into a narrower residual TODO.
6. If it is not simple, create one Linear issue from the comment text and local code context, then rewrite the source comment so it includes the created Linear key or permalink.
7. Continue until 5 items have been processed or no more untracked candidates remain.
8. Open one draft PR containing all direct fixes and comment updates from the run.
9. If Linear creation, validation, branch creation, or PR creation is unavailable, prepare the result as report-only output instead of pretending the write happened.

## Comment Update Rules

- Fixed TODOs should disappear only when the requested work is actually complete.
- Ticketed TODOs should keep the local context but add a clear Linear reference.
- Use the repository's existing comment style when possible.

## Output

Always produce markdown using this shape:

```markdown
# TODO Linear Sync And Fix
Run time:
Repo:
Processed:

## Fixed Directly
- ...

## Ticketed In Linear
- ...

## Already Tracked
- ...

## Validation
- ...

## Draft PR
- ...
```
How It Works
  1. Scans the repository for TODO, FIXME, XXX, and similar markers.
  2. Skips comments that already include a ticket key, URL, or other tracking reference.
  3. Takes a bounded set of untracked candidates.
  4. Fixes the simple ones immediately when the code and validation path are clear.
  5. Creates one Linear issue for each remaining non-trivial item.
  6. Rewrites ticketed comments to reference the created Linear work.
  7. Opens one draft PR containing direct fixes, comment updates, or both.
When To Use It
  • You want TODO cleanup tied directly to Linear.
  • You want simple fixes handled automatically and harder items tracked.
  • You want comment rewrites to make future triage easier.
Prerequisites
  • Linear access that can create issues
  • Repository write access
  • GitHub or equivalent PR tooling if you want automatic draft PR creation
Setup

Use todo-linear-sync-and-fix.md as the automation prompt.

Cursor Cloud

  1. Open Cursor Automations.
  2. Create a new automation and paste the prompt.
  3. Add Linear access with issue creation enabled.
  4. Add repository and PR tooling access.
  5. Save and start with a low-frequency schedule.

Codex App

  1. Add Linear MCP access.
  2. Click Automation > New Automation and paste the prompt.
  3. Add GitHub or other PR tooling if needed.
  4. Save the automation.

Claude Code

  1. Add and authenticate Linear MCP.
  2. Make sure the runtime can edit the repo, validate changes, and open draft PRs if needed.
  3. For repeated runs in one session, use:
/loop weekdays at 11am Follow the instructions in automations/todo-linear-sync-and-fix/todo-linear-sync-and-fix.md
  1. For durable automation, use /schedule or a Routine.
Useful Inputs

Example comment format:

When creating a ticket, rewrite comments as:
TODO(linear: ENG-123): original comment text

Example fix threshold:

Treat one-file edits with obvious nearby validation as simple enough to fix immediately.
Treat multi-file refactors, migrations, or API redesigns as ticket-only.