linear

# /linear — Linear Feedback Resolution Pipeline (v4.1) <linear-skill> > **📦 PORTABLE INSTALL NOTE (Claude desktop app).** This skill was authored for the Agentik OS > VPS. All VPS dependencies are bundled inside this skill's `references/` folder: > `43-linear-ticket-pipeline.md` (the full protocol), `audit-selector.py`, `dispatch-to-session.sh`, > `linear-mission.sh`, `ram-guard.sh`, `linear-ticket-gate.sh`. Whenever this file says > `Read ~/.claude/docs/rules-archive/43-linear-ticket-pipeline.md`, read > `references/43-linear-ticket-pipeline.md` instead. The dispatch / tmux / oracle steps assume > the Omega multi-session infra; on a plain desktop install, run the protocol **single-threaded in > the current session** (do each ticket sequentially yourself) instead of dispatching workers. > Requires the Linear MCP connector to be enabled in the Claude app. ## MANDATORY FIRST STEP — READ THE FULL RULES DOC **Before doing ANYTHING else**, Read the complete canonical protocol (bundled with this skill): ``` Read references/43-linear-ticket-pipeline.md ``` That file is the **single source of truth** for the Linear workflow. This skill file is a launcher — the rules file contains the full 10-step protocol, strict comment template, banned patterns, BEFORE/AFTER Playwright captures, auth bypass setup, quality gate criteria, audit scoping, 100/100 threshold, and Move-to-In-Review logic (Gareth alone marks Done). If anything in this launcher contradicts the rules file, **the rules file wins**. Never execute `/linear` without having Read that file in the current session. ## AUTO INTENT DETECTION (three modes) When `/linear` is invoked, detect intent by scanning the user's full prompt for keywords AND by inspecting each fetched ticket's last comment author. Read the prompt as a whole — never blindly pattern-match one word out of context. ### Mode 1 — FIX (default) **Triggers:** no keyword, or any of: `fix`, `resolve`, `feedback`, `regler`, `corriger`, `tickets ouverts`, `open tickets` **Action:** fetch OPEN tickets (`state.type NOT IN ["completed", "canceled"]`), run full 10-step protocol. ### Mode 2 — VERIFY-DONE **Triggers (any of):** `verify`, `verifie`, `vérifie`, `reverifie`, `revérifie`, `re-verify`, `recheck`, `done`, `revérifier les tasks`, `check done`, `audit done`, `validate done`, `nouveau protocole`, `new protocol` **Action:** fetch DONE tickets (`state.type IN ["completed"]`), run **Step 8 only** (targeted DYNAMIC audit chain, audit-selector.py picks 4-12 audits per ticket, 100/100 threshold each + adversarial confirmed + intent Q1-Q5 PASS). Re-open any ticket that fails. ### Mode 3 — RE-REVIEW (auto-detected per-ticket, no user keyword needed) **Trigger (per ticket):** ticket state is NOT Done/Completed (Backlog, Todo, In Progress, …) AND `lastComment.user.name` (case-insensitive) contains `"gareth"`. **Meaning:** Gareth has rejected the previous fix and re-opened the ticket with a new comment (typically text + screenshot explaining what's still wrong). **Action:** treat as a fresh fix iteration where Gareth's latest comment is the **new authoritative spec**: 1. Read the FULL ticket: original description + EVERY comment in chronological order + EVERY screenshot. 2. Download Gareth's latest screenshot (if any) via `curl -sL -H "Authorization: $LINEAR_API_KEY" URL -o file.jpg` and Read it. 3. Re-run the full 10-step protocol, but the BEFORE state must reflect the CURRENT state of the page (which is the supposedly-fixed version), and the fix must address Gareth's specific complaint. 4. The Linear comment for the new fix MUST quote Gareth's latest message verbatim under "What was requested" (instead of the original ticket description). ### Mode 4 — REGRESSION (auto-detected per-ticket, NEW 2026-05-08) **Trigger (per ticket):** ticket state is NOT Done/Completed (Backlog, Todo, In Progress) AND `comments.nodes` contains ≥1 prior `## Fix Verification Report` (or `Status: RESOLVED`, `Status: RÉSOLU`) by the bot/oracle AND (state transition history shows it was previously Done/Completed OR last bot comment is followed by a state revert). **Meaning:** Gareth (or a teammate) moved a previously-"fixed" ticket back to Backlog because **the fix did NOT actually work** OR the feature is not yet live. The prior verification report is a LIE — runtime did not match the claim. First Law violation. **Action:** This is the most serious mode. The previous fix attempts must be treated as confirmed failures, not as starting points. Workflow: 1. **Read EVERY prior Fix Verification Report comment** chronologically. Extract: commit hash, files changed, claimed root cause, claimed fix. 2. **List the failed attempts** in the new prompt (see WORKER PROMPT TEMPLATE — `PRIOR FAILED ATTEMPTS` block, mandatory in Mode 4). 3. **Forbid repeating the same approach.** If the prior fix touched `src/auth/foo.ts:42` with approach X, the new attempt MUST either: - touch a different layer (root cause is upstream/downstream of the prior fix), OR - apply a fundamentally different technique on the same line, OR - explicitly explain why the prior fix was correct in code but the issue is environmental (deployment, caching, feature flag, env var, build artifact). 4. **Run a deeper diagnosis FIRST** (before proposing any fix): live runtime evidence per First Law — actual logs from prod, actual screenshots NOW (not "should look like"), actual network requests, actual console state. Hypothesis-driven, not pattern-match. 5. **The new comment MUST include a "Why prior attempts failed" section** quoting each prior verification report and explaining the false-positive cause. Without this section the gate fails. ### Resolution rules 1. If both Fix and Verify keywords present → ask user which mode (don't guess). 2. If zero tickets in the chosen mode → report empty, do not fallback silently. 3. If `/linear` is typed alone with no keywords → default = Fix mode. 4. **Mode priority (when multiple match for a single ticket):** Mode 4 (REGRESSION) > Mode 3 (RE-REVIEW) > Mode 1 (FIX). Mode 4 wins because the prior-failure data is more important than the latest comment author check. 5. Always echo the detected mode to the user before starting: - Mode 3: `Mode detected: RE-REVIEW for {TICKET-ID} — Gareth posted feedback at {timestamp}, treating as fresh fix with new spec.` - Mode 4: `Mode detected: REGRESSION for {TICKET-ID} — {N} prior Fix Verification Report(s) by bot, ticket back in {state}. Treating prior fixes as confirmed failures, deep root-cause analysis required.` ## LINEAR API KEY LOOKUP ```bash LINEAR_API_KEY=$(cat .mcp.json | python3 -c "import json,sys; print(json.load(sys.stdin)['mcpServers']['linear']['env']['LINEAR_API_KEY'])" 2>/dev/null) LINEAR_API_KEY=${LINEAR_API_KEY:-$(grep '^LINEAR_API_KEY=' .env.local 2>/dev/null | cut -d= -f2)} ``` --- ## THE 10-STEP PROTOCOL (10/10 standard, non-negotiable) ``` 1. DEEP ANALYSIS Download screenshots from comments, Read each, parse description 2. BEFORE CAPTURE tunnel-browser.sh → auth cascade → screenshot + console BEFORE any code 3. IMPLEMENT FIX Based on complete analysis, npm run build must pass 4. AFTER CAPTURE tunnel-browser.sh → same auth → screenshot + console AFTER fix 4.1 MULTI-STEP AFTER If ticket describes a workflow/conversation/N-phase flow, capture after-step-1.png … after-step-N.png — one screenshot per stage. Triggers: workflow, agent, chat, étape, phase, wizard, onboarding, "then/ensuite". Single static state → keep one after.jpg. 5. SELF VERIFY 5 mandatory questions, all YES (covers ALL stages if multi-step) 6. STRICT COMMENT Exact template with Before/After (all stages) + verify URL + console diff 7. QUALITY GATE COMMENT Oracle verifies comment has all required sections 8. DYNAMIC AUDIT CHAIN audit-selector.py picks 4-12 audits per ticket (mission-aware), parallel, 100/100 each + adversarial dual-pass + intent verification 8b. FIX-AND-REAUDIT LOOP If any audit < 100, fix every finding, re-run failing audits (max 5 iter) 8c. INTENT VERIFICATION /featureaudit-style — does AFTER state match user's stated need? Live runtime evidence + user quote vs measured behavior. 100/100 strict. 9. MOVE TO "In Review" Oracle moves to "In Review: Gareth" — NEVER Done (Gareth alone marks Done) 10. POST-MISSION AUDIT BLOCKS done_clean. oracle-mark-done.sh invokes oracle-post-mission-audit.sh which unions every done ticket's files_touched, picks 4-12 audits via audit-selector on the cumulative footprint, dispatches them in parallel, gates 100/100 on each, iterates max 5x. Catches regressions only visible in the combined diff that per-ticket Step 8 cannot see. Escape hatch: SKIP_POST_MISSION_AUDIT=1 (tests only — logs WARN). ``` **Auth method (Steps 2 + 4)**: Always call `~/.claude/lib/tunnel-browser.sh`. By default it uses the **JWT method** (dev@agentik-os.com via Clerk Backend API) — reliable, VPS-autonomous, works when user's Mac is off. Set `USE_TUNNEL=1` only when you know the Mac is on AND want to reuse the user's real session (for example when investigating an issue that only reproduces with the user's actual data). **Default = JWT, not tunnel.** Full protocol reference: `~/.claude/docs/rules-archive/43-linear-ticket-pipeline.md` --- ## MODE 2 — VERIFY-DONE PROTOCOL (re-verification of already-closed tickets) When Verify-Done mode is detected, the pipeline is SIMPLIFIED. No new fixes, no new screenshots unless DYNAMIC audit chain fails. Goal: retroactively certify that Done tickets meet the current quality bar (v4.1, 100/100 threshold). ### Verify-Done step sequence ``` V1. FETCH DONE graphql: state.type IN ["completed"] V2. DISPLAY list tickets with original fix commit hash (parse existing comments) V2.5. COMMENT CHECK For each Done ticket: search comment bodies for "Fix Verification" or "Rapport de Vérification". If MISSING: a. Find original fix commit: `git log --oneline --all --grep={TICKET_ID}` b. Extract: commit hash, date, files changed, commit message c. Post retroactive verification comment using template below d. Log: "Posted retroactive comment on {TICKET_ID} — commit {hash}" This step is NON-NEGOTIABLE. A Done ticket without a verification comment is incomplete. V3. SELECT user picks: all / last N / by identifier V4. LOOP (sequential, one ticket at a time): a. Read ticket description + original Linear comment (extract files/URL/selector). If no verification comment found, Step V2.5 should have already posted one — verify it exists before proceeding. b. Run Step 8 (Targeted Quadruple Audit) scoped STRICTLY to original fix: files_modified = files from original commit page_url = URL from ticket selector = from ticket c. Evaluate: all 4 audits = 100/100 ? d. If PASS: - Post re-verification comment (template below) - Leave ticket Done e. If FAIL: - Post failure comment with findings - REOPEN ticket (set state to "In Progress" or equivalent) - Flag for next Fix-mode run V5. REPORT X passed, Y failed-and-reopened, Z errors ``` ### Re-verification comment template (PASS case) ```markdown ## Re-Verification Report (v4.1 protocol) **Ticket:** {ID} - {Title} **Originally resolved:** {original commit} on {original date} **Re-verified:** {today} under the new 10-step protocol with 100/100 DYNAMIC audit chain ### Targeted Audit Results | Audit | Score | Status | |-------|-------|--------| | codeaudit | {X}/100 | PASS | | uiuxaudit | {X}/100 | PASS | | flowaudit | {X}/100 | PASS | | debugaudit | {X}/100 | PASS | Scope: original fix files + original ticket URL only. ### Status: RE-VERIFIED (still DONE) ``` ### Re-verification comment template (FAIL case → reopen) ```markdown ## Re-Verification Report (v4.1 protocol) — REOPENED **Ticket:** {ID} - {Title} **Originally resolved:** {original commit} **Re-verified:** {today} — FAILED new 100/100 threshold ### Targeted Audit Results | Audit | Score | Status | |-------|-------|--------| | codeaudit | {X}/100 | {PASS/FAIL} | | uiuxaudit | {X}/100 | {PASS/FAIL} | | flowaudit | {X}/100 | {PASS/FAIL} | | debugaudit | {X}/100 | {PASS/FAIL} | ### Findings requiring fix {bulleted findings from failing audits, only the ones in ticket scope} ### Status: REOPENED — needs new fix under v4.1 protocol ``` ### Retroactive verification comment template (for VERIFY-DONE mode, when no original comment exists) When Step V2.5 detects a Done ticket with NO verification comment, post this template using data extracted from `git log --all --grep={TICKET_ID}` and `git show --stat {hash}`: ```markdown ## Rapport de Vérification Rétrospective **Ticket:** {ID} — {title} **Commit:** {hash from git log} **Date du fix:** {date from git log} **Vérifié par:** Claude AI (protocole v4.1 rétrospectif) ### Ce qui a été demandé > {quote from ticket description} ### Ce qui a été fait - **Fichiers modifiés:** {files from git show --stat} - **Changement:** {commit message summary} ### Pourquoi ça fonctionne {Technical explanation derived from commit message + files changed} ### Statut: RÉSOLU ✅ (commentaire rétrospectif) ``` This is NON-NEGOTIABLE. A Done ticket without any verification comment is incomplete, even if it was fixed correctly. The retroactive comment provides traceability. ### Reopen mutation ```graphql mutation { issueUpdate(id: "UUID", input: { stateId: "IN_PROGRESS_STATE_UUID" }) { success } } ``` Query workflowStates first to get the correct `In Progress` state UUID for the team. ### Dispatch rule for Verify-Done Still SEQUENTIAL (one ticket at a time) but MUCH faster than Fix mode — no BEFORE/AFTER captures, no code edits. Each ticket = 3 parallel audits then decision. Work session name: `{Project}-linear-verify-{TICKET_ID}`. --- ## DISPATCH RULE: TRUE SLIDING WINDOW (refill-on-completion, supersedes wait-for-batch) (2026-05-09, supersedes 2026-04-18 wait-for-batch which superseded SEQUENTIAL) ``` WRONG (old): dispatch 5 -> wait for ALL 5 .done.json -> dispatch next 5 (idle slots while fast workers wait for slow ones) RIGHT: maintain pool of POOL_SIZE=5 active workers. As soon as ANY worker writes .done.json, gate it AND immediately call next-batch N=1 to refill that slot. ``` **Per oracle wake protocol:** 1. **RAM guard first.** `~/.aisb/lib/ram-guard.sh check 70` — exit 1 (>70% used) → `ScheduleWakeup(180s)` and retry. Exit 0 → proceed. Rationale: each worker can peak at 4–13 GiB. 2. **Count active workers.** `ACTIVE=$(ls ~/.aisb/state/worker-{Project}-worker-*.progress.json 2>/dev/null | xargs -I{} sh -c "test ! -f {%.progress.json}.done.json && echo 1" | wc -l)` — number of in-flight workers (progress file exists, done.json does not). 3. **Compute slots to fill.** `SLOTS=$((POOL_SIZE - ACTIVE))` where `POOL_SIZE=5`. 4. **Drain done workers FIRST.** For every `worker-{Project}-worker-*.done.json` that exists: a. DYNAMIC audit chain (audit-selector.py picks 4-12 audits) b. `close-gate.sh ack-worker` c. `linear-ticket-gate.sh` validates v2 chain d. `linear-mission.sh done <ticket-id>` e. `linear-move-to-review.sh` (or equivalent state transition) 5. **Refill open slots.** While `SLOTS > 0`: - `~/.aisb/lib/linear-mission.sh next-batch <mid> 1 {Project}-worker` — N=1 because each call refills one slot atomically. - exit 0 + 1 ticket → dispatch via `dispatch-to-session.sh`, decrement `SLOTS` - exit 2 (queue empty) → break refill loop - exit 3 (all pending conflict with in-progress) → break refill loop, `ScheduleWakeup(90s)` to wait for slots to free