RonanCodes/linear-grill

/ro:linear-grill

Process a collaborator's Linear tickets so every one ends the run in one of three places: Question for <name> (we asked, they answer async in comments), Grilled (build-ready, the gate /ro:linear-nightshift consumes), or Done (shipped and confirmed). The agent moves the tickets; the collaborator only ever answers in comments (dragging a ticket to "Ready for agent" is their priority nudge, not a build-ready signal). Pairs with /ro:linear-nightshift (consumes Grilled) and /ro:linear-update (closes the loop on deploy).

Part of the hybrid one-way sync model (locked 2026-06-11, see ronan-skills#61): Linear is where collaborator stories are born and prioritised; GitHub is the execution layer. This skill is the grilling step that makes a born story buildable.

Linear API mechanics (shared by all three linear-* skills)

• Endpoint https://api.linear.app/graphql. Header Authorization: <key> — NO Bearer prefix for personal API keys. Key: LINEAR_API_KEY in ~/.claude/.env.
• Complexity cap ~10k/query — keep queries slim (one team, named fields; never a teams{issues{comments}} mega-query).
• Mentions: @[displayName](user-uuid) in markdown bodies renders as a real mention and notifies. Get the uuid via { users { nodes { id name displayName } } }.
• Issue creators are auto-subscribed (comments notify them). For issues YOU create, add subscriberIds: [<their-uuid>] so they're notified too.
• States are per-team: query team(id){ states { nodes { id name type } } }, match by name (Backlog / Question for <name> / Grilled / In Progress / Done).
• Label names collide case-insensitively with workspace-level labels — look up before creating.

Step 0: Resolve the board (.ro-linear.json)

The current repo maps to its Linear board via a committed .ro-linear.json at the repo root:

{
  "teamKey": "NUT",
  "collaborator": "econnolly321",
  "states": { "questions": "Question for Eoin", "grilled": "Grilled" }
}

If the file exists, skip discovery entirely. If it doesn't: infer the team (repo name vs team names, or the one obvious collaborator team), ask when ambiguous, then WRITE the file and commit it so the next run starts instantly. Not in a repo, or no plausible team: ask.

Step 1: Resolve scope

1. --team <KEY> overrides the config file; both override workspace inference.
2. --collaborator <name>: config file, else the team's non-Ronan member with created issues (match on users.displayName).
3. Target set: --issue <ID> list if given; else ALL team issues in backlog-type or unstarted-type states except Grilled (so: Backlog, Ready for agent, Question for <name>), regardless of creator. Ronan files proposal/menu tickets on the collaborator's board too (e.g. NUT-61, a "which of these would you use?" ticket); a creator filter silently drops their answers to those. Tickets already in Grilled are the nightshift's queue, leave them alone.
4. Never rely on the collaborator to move a ticket. They answer in comments and stop; every state transition is this skill's job. An answered ticket in the questions state that nobody scans is invisible (NUT-61 sat answered for half a day, 2026-06-13), which is exactly why the questions state is in the target set above.

Step 2: Classify each ticket (idempotency)

Read each candidate's comments, latest grill comment first:

• Open grill (Ronan asked, no collaborator reply after): skip, re-asking is noise.
• Answered grill: promote, see Step 3 outcomes.
• Never grilled: grill it, unless it's decidable without asking (clear bug with an obvious fix, or the collaborator has already said "use your judgement" on the deciding question), in which case confirm instead of asking.

Step 3: Write the questions

The comment shape that works (worked example: NUT-50…54 + NUT-55…58, 2026-06-11):

1. Status first when relevant: if part of the ask already shipped, open with that + a try-it link + "tick this off if it does what you wanted". Best possible collaborator experience: their board answers them.
2. 3-5 decision-extracting questions, numbered, each one decides a real build choice (where it lives, which variant, defaults, data dependencies, budget). Never generic "can you clarify?".
3. Plain language — the collaborator is not an engineer. Translate data/infra constraints into choices they can make ("qualifiers and friendlies need the paid plan — worth paying for, or is World Cup + Euros enough this summer?").
4. Honest constraints inline — name what's blocked on money/data/decisions rather than hiding it.
5. Open with the mention: @[<displayName>](<uuid>) — a few questions so this gets built the way you picture it:.

Post via commentCreate. With --dry-run, print the would-be comments instead.

Step 3b: Move the ticket (every processed ticket MOVES)

The board is the report; never leave a processed ticket where you found it. Three outcomes, each a comment + issueUpdate of stateId:

1. Questions posted → state questions from the config (e.g. "Question for Eoin"; create it, type backlog, if missing).
2. Build-ready (grill answered, or decidable without asking) → post a short confirmation that locks the decisions in plain language ("Locked in: … Moving this to Grilled.") → state grilled (create it, type unstarted, if missing). Creating a state that already exists fails with "duplicate workflow state": on that error, look it up with workflowStates(includeArchived: true, filter: {team, name}) instead.
3. Shipped and confirmed by the collaborator ("all good", "done") → one-line closing comment → state Done.

Step 4: Report

Print per ticket: questioned / grilled (build-ready) / done / skipped (open grill). The cycle: the collaborator answers in comments, the NEXT grill run promotes answered tickets to Grilled, and /ro:linear-nightshift drains Grilled.

Errors

| Condition | Behaviour | |---|---| | No LINEAR_API_KEY | Fail loudly, point at ~/.claude/.env | | Collaborator not found in workspace | List members, ask | | Mention renders literally (@[name](id) as text) | Fallback: profile-URL link form + subscriberIds; note it in the report |

Related

• /ro:linear-nightshift — consumes the Grilled tickets this skill matured
• /ro:linear-update — closes the loop on deploy
• /ro:day-shift — the GitHub-native sibling for Ronan's own backlog
• ronan-skills#61 — the hybrid-sync design record