organize-linear-tasks

## Instructions You are running a weekly audit of the OpenMates Linear backlog. This is an interactive, multi-section workflow that cross-references Linear tasks with git history, presents findings section-by-section, and applies only user-approved changes. **Arguments:** - `--quick` — skip comment fetching and task decomposition analysis (faster, less thorough) - `--section N` — jump directly to section N (0-10) to resume an interrupted audit --- ### Step 1: Data Gathering Gather all data upfront before any analysis. Run these in parallel where possible. #### 1a. Fetch all open issues Use `python3 scripts/linear.py list --team OPE --all --limit 100 --json` to fetch Linear issues from team OpenMates, then filter out Done and Canceled. Fetch in batches if needed. For each issue, collect: identifier, title, description, state, priority, labels, project, milestone, createdAt, updatedAt, assignee. Store the full list mentally — you'll reference it across all sections. #### 1a-bis. Fetch completed issues for archival review Also fetch ALL issues with state **Done** from team OpenMates. Collect: identifier, title, completedAt (or updatedAt), labels, project. These are used in Section 0 for archival cleanup. #### 1b. Fetch organizational context Run these in parallel where useful: ```bash python3 scripts/linear.py states --team OPE --json python3 scripts/linear.py labels --team OPE --json ``` #### 1c. Fetch comments (skip if `--quick` or if ALL tasks are < 14 days old) For each open issue, fetch comments via `python3 scripts/linear.py get OPE-XX --comments --json`. Record the date of the most recent comment per issue — this is the "last activity" signal for staleness detection. **Optimization:** If the oldest open task is < 14 days old, skip comment fetching entirely — nothing can be stale. Use updatedAt as the activity signal instead. #### 1d. Git cross-reference Scan the past week of git history across all branches for task references: ```bash git log --all --oneline --since="1 week ago" | grep -oP 'OPE-\d+' | sort | uniq -c | sort -rn ``` For each open task that appears in git, get its commit details: ```bash git log --all --oneline --since="1 week ago" --grep="OPE-XX" ``` Also check for any OPE references in git that don't match an open task (orphaned commits): ```bash git log --all --oneline --since="1 week ago" | grep -oP 'OPE-\d+' | sort -u ``` #### 1e. Present Overview After gathering, show a quick summary before diving into sections: ``` ## Backlog Audit — Overview Open tasks: XX (Backlog: X, Todo: X, In Progress: X, In Review: X) Projects: X | Milestones: X | Labels: X Git references found (past week): X tasks mentioned in Y commits Tasks with no description: X Tasks with no priority: X Starting analysis... ``` --- ### Step 2: Section 0 — Delete Done Tasks Linear's free plan has a 250-issue limit. This section permanently deletes completed tasks older than 24 hours to keep the workspace clean. Filter the Done issues fetched in Step 1a-bis: - Only show tasks where completedAt (or updatedAt if completedAt unavailable) is **more than 24 hours ago** - Skip tasks completed in the last 24 hours — they may still need review or follow-up Present findings: ``` ## 0. Delete Done Tasks — Completed >24h Ago (N found) | # | Task | Title | Completed | Project | Labels | |---|------|-------|-----------|---------|--------| | 1 | OPE-XX | "Fix auth race condition" | 3 days ago | Web App | Bug | ``` Use `AskUserQuestion` with options: - **all** — delete all listed tasks - **pick** — go through one by one (keep / delete) - **skip** — skip this section, keep all **For approved deletions, use the Linear GraphQL API directly** (the MCP doesn't expose delete): ```bash API_KEY="$LINEAR_API_KEY" # Get UUID from identifier UUID=$(curl -s -X POST https://api.linear.app/graphql \ -H "Content-Type: application/json" \ -H "Authorization: $API_KEY" \ -d '{"query": "{ issue(id: \"OPE-XX\") { id } }"}' \ | python3 -c "import sys,json; print(json.load(sys.stdin)['data']['issue']['id'])") # Delete curl -s -X POST https://api.linear.app/graphql \ -H "Content-Type: application/json" \ -H "Authorization: $API_KEY" \ -d "{\"query\": \"mutation { issueDelete(id: \\\"$UUID\\\") { success } }\"}" ``` **Batch deletions** into a single bash script for efficiency — don't make 18 sequential tool calls. > **Note:** `issueDelete` is a soft delete — issues go to trash and can be restored for 30 days in Linear. Report the count of deleted tasks for the summary. --- ### Step 2.5: Section 0.5 — In Review Cleanup Many "In Review" tasks are actually done — the review step is often skipped. Check all In Review tasks and ask which are truly complete. Present findings: ``` ## 0.5. In Review Cleanup — Are These Done? (N found) | # | Task | Title | In Review Since | Has Git Commits | |---|------|-------|-----------------|-----------------| | 1 | OPE-XX | "Fix passkey login crash" | 2 days | Yes (3 commits) | | 2 | OPE-YY | "Remove npm validation from deploy" | 1 day | Yes (1 commit) | ``` Use `AskUserQuestion`: - **all done** — mark all as Done - **pick** — go through one by one - **skip** — leave all in In Review --- ### Step 3: Section 1 — Ghost Tasks (done in git, open in Linear) > From this section onward, exclude any tasks handled in Sections 0 and 0.5. Cross-reference the git history from Step 1d with open tasks. A "ghost task" is one where: - Commits in the past week clearly reference OPE-XX - The commit messages suggest the work is complete (e.g., "fix:", "feat:", "implement", "close", "resolve") - But the Linear task is still in Todo, In Progress, or Backlog Present findings — **always include title in every table**: ``` ## 1. Ghost Tasks — Completed in Code, Open in Linear (N found) | # | Task | Title | Status | Commits (past week) | Last Commit | Suggested Action | |---|------|-------|--------|---------------------|-------------|-----------------| | 1 | OPE-XX | "Fix chat pagination" | Todo | 2 commits | 2026-03-28 | → Mark Done | ``` Use `AskUserQuestion` with options: - **all** — mark all as Done - **pick** — go through one by one - **skip** — skip this section For approved items, call `python3 scripts/linear.py update OPE-XX --state Done`. Remove approved ghost tasks from your working set for subsequent sections. --- ### Step 3.5: Section 1.5 — `claude-is-working` Label Cleanup Find tasks with the `claude-is-working` label that are in Done, In Review, or Backlog status — these likely have stale labels from ended sessions. Present findings: ``` ## 1.5. Stale `claude-is-working` Labels (N found) | # | Task | Title | Status | Label Should Be Removed? | |---|------|-------|--------|--------------------------| | 1 | OPE-XX | "Fix show more chats" | Done | Yes — task is done | | 2 | OPE-YY | "Improve home search" | In Progress | Maybe — check if session is active | ``` Use `AskUserQuestion`: - **all** — remove `claude-is-working` from all listed - **pick** — go through one by one - **skip** — leave as-is --- ### Step 4: Section 2 — Stale Tasks A task is stale if: - **Backlog** status AND updatedAt/last comment > 30 days ago AND no git commits reference it - **Todo** status AND updatedAt/last comment > 14 days ago AND no git commits reference it - **In Progress** status AND updatedAt/last comment > 7 days ago AND no git commits in the past week Present findings: ``` ## 2. Stale Tasks — No Activity (N found) | # | Task | Title | Status | Last Activity | Age | Suggested Action | |---|------|-------|--------|---------------|-----|-----------------| | 1 | OPE-XX | "Old feature request" | Backlog | 45 days ago | Created 60d ago | → Cancel or re-prioritize | ``` Use `AskUserQuestion` — for each stale task, options are: - **cancel** — delete the task - **backlog** — move to Backlog (demote) - **keep** — leave as-is (user confirms it's still relevant) - **skip** — skip this section entirely Apply approved changes. Remove deleted tasks from working set. --- ### Step 5: Section 3 — Duplicate / Merge Candidates Compare all remaining open tasks for duplicates or near-duplicates: - Normalize titles: lowercase, strip prefixes (Feat:, Fix:, Docs:, etc.), strip common words - Flag pairs where titles share >60% of significant words - Flag pairs where descriptions mention the same files, components, or error messages - **Detect title prefix stacking**: flag titles starting with "Fix: Fix:", "Feat: Feat:", etc. Present findings: ``` ## 3. Duplicate / Merge Candidates (N pairs found) ### Pair 1: - **OPE-XX**: "Fix encryption key sync on mobile" (In Progress, High) - **OPE-YY**: "Encryption key not syncing across devices" (Todo, Medium) - **Overlap**: Both reference encryption key sync, likely same issue ``` Use `AskUserQuestion` per pair: - **merge** — close the lower-priority one, add a comment linking to the kept one - **relate** — keep both but note they're related (comment on both) - **skip** — they're different, leave both For merges: mark the duplicate as Done (the work was done under the other task), post comment on both linking them. Remove merged tasks from working set. --- ### Step 6: Section 4 — Unclear Tasks Flag tasks that need clarification: - Title is < 5 words AND no description - Title contains only vague terms ("fix thing", "update stuff", "do the thing") - Description is empty or < 20 characters - Title is a question without context - **Title has prefix stacking** ("Fix: Fix:", "Feat: Feat:") Present findings — **always include the full title**: ``` ## 4. Unclear Tasks — Need Better Titles or Descriptions (N found) | # | Task | Title | Has Description | Created | |---|------|-------|-----------------|---------| | 1 | OPE-XX | "fix it" | No | 15 days ago | | 2 | OPE-YY | "Fix: Fix: update the component" | No | 8 days ago | ``` For EACH unclear task, use `AskUserQuestion`: - "What did you mean by **OPE-XX: 'fix it'**? I'll update the title and add a description." Based on the user's response, call `python3 scripts/linear.py update OPE-XX --title "..." --description-file <file>` to update the title and description. If the user says they don't remember or it's no longer relevant, delete the task. --- ### Step 7: Section 5 — Priority Audit Flag tasks with priority issues: - **No priority set** — any task in Todo or In Progress without a priority - **Questionable priority** — Urgent/High priority but sitting in Backlog for >7 days (was it actually urgent?) - **Low priority In Progress** — someone started a low-priority task while high-priority items wait Present findings — **always include title**: ``` ## 5. Priority Audit (N issues found) ### Missing Priority (X tasks): | # | Task | Title | Status | Labels | Suggested Priority | |---|------|-------|--------|--------|--------------------| | 1 | OPE-XX | "Critical auth bug" | In Progress | Bug | → High (2) | ``` Use `AskUserQuestion` with approval per group. Apply priority changes via `python3 scripts/linear.py update OPE-XX --priority N`. --- ### Step 8: Section 6 — Label Cleanup Analyze label usage across all remaining open tasks: - Tasks with NO labels at all - Tasks where labels seem wrong (e.g., a backend Python task labeled "frontend") - Unused labels that exist but aren't on any open tasks - Tasks that should have the `Idea` label (questions, brain dumps, "what if" titles) Present findings — **always include title**: ``` ## 6. Label Cleanup (N issues found)