RonanCodes/skills/linear-update

/ro:linear-update

The deploy-time half of the hybrid sync (ronan-skills#61): the collaborator filed the story on Linear, answered the grill, and the build ran on GitHub — this skill brings the outcome back to where THEY live, so the board is self-explanatory without ever opening GitHub.

API mechanics (auth header without Bearer via the RoBot key — never the OAuth MCP — @[displayName](uuid) mentions, per-team states, agent identity as the RoBot user with no label/footer): see /ro:linear-grill § "Linear API mechanics".

Step 1: Resolve inputs

• --issue <ID> (e.g. NUT-21) — required. Resolve to the issue id + team, then load its full context per /ro:linear-run § "Load full ticket context" and emit the context-load receipt there (mandatory gate — no validation comment without it): the whole description, every comment oldest→newest, and every image/attachment (the most recent comments are most authoritative). The acceptance criteria you validate against come from the complete ask, including anything refined in later comments or shown in a pasted mockup — and review any image the collaborator already attached before you capture your own screenshots.
• --pr <number> + --repo — fetch title, merge SHA, and the close-with-summary comment from the linked GH issue if one exists (richest source for "what shipped" and the acceptance criteria).
• --state: default Interview (the human-validation gate — see below). --state Done only when the collaborator has already explicitly confirmed they tested it and are happy (see /ro:linear-grill § "The Done rule"), or In Review for merged-but-not-deployed when there's nothing for them to try yet. Never auto-jump to Done — Done is the collaborator's to set once they've tried it and accepted.
• --try-url: default = the repo's production URL if known (e.g. from the README or wrangler config); omit the try-it line when unknown — never invent a URL.

The hand-off gate (mandatory, no transition without it)

This skill is the only sanctioned path to the Interview / Ready-to-Test state. The transition is gated: a ticket does not move until the validation comment carries both of:

1. An acceptance-criteria checklist that enumerates the original ask as things the collaborator does and what they should see (the "Validate these flows" block in Step 2). One line per criterion, derived from the complete ask (description + every grill answer + any pasted mockup).
2. At least one screenshot of the built feature, embedded in the comment (Step 2b).

If you cannot produce both, you cannot transition. Hold the ticket where it is, post a comment saying which half is missing and why (e.g. "no live URL yet to screenshot, lands with the next deploy"), and use In Review instead of Interview. A silent state change with no RoBot hand-off comment is a defect: the collaborator is then asked to verify a build with nothing to verify against, which is exactly the no-AC-for-verification bounce this gate exists to stop (ronan-skills#122).

The gate applies to quick bug fixes too — no small-ticket exemption. The 2026-07-03 board audit found the template holding on feature tickets but slipping to 57% on rapid-fire evening bug fixes (prose hand-offs, no checklist, no screenshot). A one-line fix still gets a one-line AC checklist and one screenshot; that's cheap, and it's what lets a non-technical collaborator verify at a glance.

Wire-in point for the night-shift path: /ro:linear-nightshift Step 4 routes its → Ready to Test transitions through this skill specifically so the gate is enforced on the night-shift path too. That path must never reach the interview state by a bare issueUpdate.

Mobile / responsive tickets: real-device evidence required (ronan-skills#127)

A headless screenshot does not prove a mobile fix. For any ticket that is mobile- or responsive-tagged, OR whose bounce / description text names a phone or mobile symptom (soft-keyboard jump, visualViewport, touch target, viewport overflow, iOS/Android-specific, "on my phone"), the gate tightens: the hand-off comment must also carry explicit real-device or device-emulation verification evidence, a literal verified on <device/viewport> line (e.g. verified on iPhone 15 / 390×844 emulation, or verified on Eoin's iPhone), not just a headless desktop screenshot.

Surface the limitation plainly. A class of mobile bug (the visualViewport soft-keyboard page-jump being the canonical example, nutmeg feedback-mobile-dropdown-jump-visualviewport) cannot be reproduced or confirmed headless. Print "headless cannot reproduce this class; confirming on a real device/emulation before hand-off" rather than re-dispatching a blind headless pass. If no real-device or emulation evidence exists, do NOT transition: hold the ticket and say so. NUT-64 burned 4 blind bounces because the skill let mobile tickets through on an invisible headless "pass"; this gate stops that.

The build path in /ro:linear-run is where the emulation capture is actually run (mobile viewport via Playwright, see Step 2b). Wire-in pointer only, not edited here.

Step 2: Move to Interview + comment (the validation gate)

The collaborator owns acceptance. We never mark our own work Done — we hand it to them to validate.

1. issueUpdate → Interview state (from .ro-linear.json states.interview; create it, type started, if missing) and keep the ticket's people subscribed. (All writes as the RoBot user via LINEAR_API_KEY — no label, see /ro:linear-grill § "Agent identity".) Address the ticket's creator (issue.creator), not always the configured collaborator: a ticket Ronan filed tags Ronan; an Eoin ticket tags Eoin (see /ro:linear-grill § "Address the ticket's creator"). Resolve the creator's displayName + uuid for the mention in step 2.
2. commentCreate with the validation comment — mention-first so they're notified, acceptance criteria they can actually tick through:

@[<creator displayName>](<creator uuid>) — **built and ready for you to check** ✅

**What we built:** <1-3 plain-language lines — outcome, not implementation. "Type a team in the fixture picker and pick from their upcoming games" beats "added upcoming_fixtures store">
**Try it:** <try-url, ideally deep-linked to the feature>

**Here's how it looks:**
<embedded screenshot(s) — see Step 2b; before + after when feasible>

**Validate these flows:**
1. <acceptance criterion in plain language — a thing they do and what they should see>
2. <…>
3. <…>

Reply and let me know if it's all good. **If it does what you wanted, move this to Done.** If anything's off, drop it back to **To-do** with a line on what's wrong and I'll pick it up.
**Under the hood:** PR <link> (merged <sha-short>)

<If anything was assumed or descoped from their answers, one honest line about it + what would change it.>

Rules: plain language (the collaborator is not an engineer); calibrated — if it's merged-but-not-deployed, say "lands with the next deploy" and use In Review, don't claim live; if the build made assumptions on their unanswered questions, surface them here, not never. The acceptance criteria come from the ticket's original ask + the grill answers — derive them, don't ask the collaborator to invent them.

Step 2b: Screenshots (attach the built feature to the comment)

Show, don't just tell — a screenshot of the actual result lets the reviewer validate at a glance. After the deploy:

1. Capture the feature on the live URL with the repo's browser tooling (Playwright is in nutmeg; or /ro:playwright-check). A throwaway script: navigate to the deep-linked try-url, set the right viewport (use a mobile viewport when the ticket is a mobile issue — e.g. iPhone), do the flow, page.screenshot({ path: '/tmp/NUT-x-after.png' }).
2. Before + after when feasible (the user asked for this; skip if it's not cheap): capture "before" first — from production, or by stashing the change / checking out main and screenshotting the old state, then "after" on the new build. Don't spend long on it; one "after" beats none.
3. Upload + embed: python3 "${CLAUDE_PLUGIN_ROOT:-$HOME/Dev/ronan-skills}/skills/linear-update/scripts/upload-image.py" /tmp/NUT-x-after.png "after" prints ![after](https://uploads.linear.app/…). Drop those lines into the comment's "Here's how it looks" block (before above after). The helper does Linear's fileUpload → signed PUT → assetUrl dance.

Mobile bugs especially: a screenshot at a real phone viewport is often the fastest way for the reviewer to confirm a fix (and pairs with the diagnostic screenshots we ask them for on repeated rework, see /ro:linear-run § Rework). For mobile/responsive tickets this capture is load-bearing for the gate (see "Mobile / responsive tickets" above): run it at a real device viewport and add the verified on <device/viewport> line to the comment. A desktop-viewport screenshot does not satisfy the gate for this class.

Step 3: Report

Print: ticket → state, comment posted, and (when called from /ro:linear-nightshift) accumulate into the run's nightsheet line ("Sent for interview: NUT-21, NUT-24 → Interview, assigned to Eoin").

The loop isn't closed when this skill runs — it's handed off. Closure happens when the collaborator moves the ticket to Done. If instead they kick it back to To-do, the next /ro:linear-run treats it as rework and introspects why we missed (see /ro:linear-run § "Rework").

Daily-digest mode (--daily-digest --issue <pinned-ID>)

A separate mode (ronan-skills#69) for collaborator-facing release notes. Linear has no first-class release notes, so the fit is a pinned "📰 Release notes" issue: every day that shipped something gets ONE comment, and comments notify subscribers: a push-style changelog they read where they already live.

Invoked at the end of a run, after deploy and after the per-ticket /ro:linear-update hand-offs have run. Wire-in points are /ro:linear-nightshift's close-out and /ro:night-shift's tail. This mode does NOT move any state and does NOT touch the per-ticket tickets; it only appends one comment to the pinned issue.

1. Gather the day's shipped work. Source = the run's nightsheet / merged-PR list (merged + deployed today). If called standalone, fall back to gh pr list --state merged --search "merged:>=<today>" on --repo. Each item: the user-facing outcome + a try-it link where there is one.
2. Zero-change day → skip silently. No merged+deployed work today: post nothing, print "no changes today, skipping digest", exit 0. Never post an empty or "nothing shipped" comment; silence is the signal.
3. Write it in the "what you get / try it" voice. Plain language, outcomes not implementation, honest about partial ships. Group by theme, not by ticket id. One comment, posted to the pinned issue via commentCreate (RoBot user, no label).

**📰 What shipped <weekday D Mon>: <N> updates**

**<Outcome headline in their words>**
<1-2 plain lines: what you can now do, why it helps.>
Try it: <deep-link>

**<Next outcome>**
<…> Try it: <deep-link>

<One honest line if anything shipped partial / behind a flag / lands next deploy.>

Rules: no PR numbers or SHAs in the digest (that's the per-ticket "Under the hood" line's job, not the changelog's); deduplicate against the previous day's digest comment so a slow-merging PR isn't announced twice; if the pinned issue id doesn't resolve, error and ask rather than posting to the wrong place.

Idempotency

Re-running on a ticket already in Interview with an existing validation comment for the same PR: skip with "already sent for interview on PR #N". A NEWER PR for the same ticket appends a fresh comment (e.g. after a rework round).

Daily-digest: re-running for the same day appends nothing new if a digest comment for that date already exists with the same shipped set; a larger shipped set replaces by appending a corrective comment, never edits silently.

Errors

| Condition | Behaviour | |---|---| | Issue ID not found | List the team's recent identifiers, ask | | --deployed but no deploy evidence (no live URL probe passes) | Post as In Review with "lands with the next deploy" instead; say why | | Gate not satisfiable (no screenshot possible, no live URL) | Do NOT transition to Interview; hold, post comment naming the missing half, use In Review | | Mobile/responsive ticket with no real-device/emulation evidence | Do NOT transition; print "headless cannot reproduce this class", hold for emulation capture | | --daily-digest with zero merged+deployed work today | Skip silently (no comment), print "no changes today", exit 0 | | --daily-digest --issue does not resolve to the pinned issue | Error and ask; never post to a guessed issue |

Related

/ro:linear-run (the front door) · /ro:linear-nightshift (calls this at its tail) · /ro:linear-grill (the upstream questions this answers) · ronan-skills#61 (design)