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.
• All agent writes go through LINEAR_API_KEY, never the OAuth mcp__linear-server__* tools. The key belongs to the dedicated RoBot service-account user, so comments / labels / state-moves made with it are attributed to RoBot — distinct from Ronan, and filtered by /ro:linear-listen so they never re-trigger. The MCP tools authenticate as Ronan; a write through them would post as Ronan, break attribution, AND trip the listener loop (a "Ronan" comment triggers a run). Use the MCP tools only for read-only convenience if at all; do every comment / issueUpdate / issueCreate via curl + LINEAR_API_KEY.
• 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 } } }.
• Address the ticket's creator, not always the configured collaborator. Resolve issue.creator and @-mention them in grill questions, validation, and deploy comments (fall back to .ro-linear.json collaborator only if the creator can't be resolved). A ticket Ronan filed gets Ronan tagged (and the technical register); a ticket Eoin filed gets Eoin (plain-language, domain-only). The collaborator in config is just the default board owner, not a hardcoded mention target. Match the register to the creator: technical for Ronan, plain-language for the non-technical collaborator.
• 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 / Interview / Holdoff / Done).
• Label names collide case-insensitively with workspace-level labels — look up before creating.
• Agent identity (the RoBot user — no markers needed): the agent acts as its own Linear user, the RoBot service account that owns LINEAR_API_KEY. Authorship is therefore intrinsic — every agent comment/label/move already shows "RoBot" as the actor in Linear's UI, and /ro:linear-listen filters the agent's own events by that user id. Do NOT append the old *🤖 RoBot (agent)* footer and do NOT apply a 🤖 RoBot label for loop-safety — both are obsolete now that identity comes from the account. (Historic tickets may still carry the label; harmless, ignore it.) Write plainly, as RoBot.

The Done rule (never auto-close)

No linear- skill ever moves a ticket to Done on the agent's own judgement.* Done means the collaborator has tested the shipped work and said they're happy with it — nothing less. The default path to Done is the Interview gate (/ro:linear-update hands them the built work + acceptance criteria; they drag it to Done). An agent may set Done only when the collaborator has, in a comment, explicitly confirmed they tested it and it does what they wanted — a clear "tested, all good", not a vague "thanks", not silence, not "looks good" without trying it. If there's any doubt they actually used it, leave it in Interview and ask them to confirm they've tried it. This rule overrides every "→ Done" outcome below and in the sibling skills.

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",
  "owner": "[email protected]",
  "reworkLabel": "🔁 Rework",
  "reviewLabel": "🚨 Technical Review Needed",
  "states": { "questions": "Question for Eoin", "grilled": "Ready to Build", "holdoff": "Hold Off", "interview": "Ready to Test" }
}

owner (name or email) is the human who, alongside the collaborator, may prompt the agent — /ro:linear-listen setup resolves it to ownerId. Use a value that uniquely matches the human owner and NOT the RoBot user (the agent's service account) — an email is safest, since RoBot may share the owner's name or domain. The old robotLabel / humanReviewLabel keys are gone: the agent is now its own RoBot Linear user, so authorship needs no label (see § "Agent identity").

The states keys are fixed concepts (questions / grilled / holdoff / interview); the values are the collaborator-facing column names on the board, which you pick to read clearly for a non-technical person. Eoin works the columns (not labels), so name them for him: the nutmeg board uses Ready to Build (the grilled/build-ready queue), Hold Off (parked), and Ready to Test (the interview/validation gate the collaborator owns — built work lands there for them to test and accept → Done, or kick back → rework). The collaborator's priority-nudge column is Up Next (unstarted-type). All skills match states by these config values + type, never a hardcoded string, so renaming a column only means updating this file. See /ro:linear-update § "Interview" and /ro:linear-run § "Rework".

Labels are agent bookkeeping (Eoin ignores them): 🔁 Rework (bounced from validation), 🚨 Technical Review Needed (3+ failed rework attempts — a technical human should look, though the agent keeps retrying; see /ro:linear-run § Rework), linear-mirror (has a GitHub execution mirror). Use labels freely for agent state; never make Eoin's flow depend on one. (The retired 🤖 RoBot / 🧑 RoHuman labels are no longer applied — agent-authored events are now identified by the RoBot user, and review tickets reach Ronan by being assigned to him, see /ro:linear-run § "Review tickets for Ronan".)

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 the grilled and holdoff states (so: Backlog, the nudge column e.g. "Up Next", Question for <name>), regardless of creator. The grilled state is the nightshift's build queue and holdoff is parked — both stay untouched unless named explicitly with --issue. Match by config value + state type, never a hardcoded name. 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)

Edits count as new. Classify on each comment's updatedAt, not createdAt. If a comment you previously read and acted on now has a newer updatedAt (the collaborator edited it — e.g. they went back and answered a question inline, or changed their answer), treat it as unread and re-process the ticket from that comment. Never assume a comment you've seen before still says what it said; an edit to an already-read message means re-read it. Track the last-processed updatedAt per ticket (the listener passes it; a standalone run reads it from the latest grill/RoBot comment's timestamp) so an unchanged board is a no-op but an edited comment isn't missed.

Before classifying, load the candidate's full context per /ro:linear-run § "Load full ticket context" and emit the context-load receipt there (mandatory gate — no grill without it): the whole issue description, every comment oldest→newest (not just the latest grill), and every image/attachment on the body and in comments. The most recent comments are the most authoritative — a later comment supersedes an earlier one (or the original ask) where they conflict. Don't grill a question the thread or a pasted screenshot already answers.

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

• Holdoff signal (collaborator's latest reply says hold off / park it / not now / later / on ice, or Ronan flagged it): route to Holdoff, see Step 3b outcome 4. Don't re-grill, don't build.
• 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, only technical decisions remain — see Step 3 § domain-vs-technical — 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

Ground the questions in the codebase first

Before writing a single question, look at the repo the way the ticket implies — the relevant route / store / component, the patterns already in use, what already ships. Questions must be informed by what exists: "you already have a fixtures picker; should this live there or as its own page?" beats a generic "where should this go?". Reading the code is also how you separate domain from technical (below) — most "where/how" uncertainty is technical and you resolve it yourself by looking.

Domain questions go to the client; technical decisions you make yourself

Only ask the collaborator about domain / product decisions — things only they can decide: which competitions matter, what the user should see, product behaviour, scope, what's worth paying for. Technical decisions (where a file lives, which library, the data model, framework choice) you decide yourself in the working chat with Ronan — never on the Linear ticket. If a ticket's only open questions are technical, don't grill — decide and confirm build-ready. Grill only when a real domain fork blocks the build.

Mandatory vs optional

Mark each question. Mandatory = blocks the build (a real product fork with no safe default). Optional = refines it but has a sensible default you'll use if unanswered — state the default inline (Optional — default: monthly unless you say otherwise). This lets the collaborator answer just the mandatory ones and still unblock the build; unanswered optionals become stated assumptions. The /ro:linear-nightshift answer-gate only blocks on unanswered mandatory 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 tagged (mandatory) or (optional — default: …), each one a real domain choice. Never generic "can you clarify?", never a technical question you could answer by reading the code.
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 of the ticket's creator (§ "Address the ticket's creator"): @[<creator displayName>](<creator uuid>) — a few questions so this gets built the way you picture it:. No footer — the comment posts as the RoBot user (§ "Agent identity").

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

Step 3a: The Acceptance-Criteria gate (agree the AC before any build)

Eoin has found that builds sometimes miss pieces of what he asked for. So no ticket is built until its Acceptance Criteria are written down and the creator has agreed to them. Order, per ticket:

1. Questions first. If a real domain fork is unanswered, grill and wait — you can't write good AC without the answers.
2. Post the AC. Once questions are answered (or none were needed), comment a checkbox list that enumerates EVERY piece of the ask — including the easy-to-forget parts — in plain language the creator can verify. Derive it from the ticket + their answers; drop nothing. Mention the creator: "Here's exactly what I'll build — anything missing or wrong? Reply and I'll adjust; reply 'looks good' and I'll start." Keep the ticket in the questions state (it's back with them to sign off).
3. Wait for agreement. Only an explicit agreement ("yes / looks good / build it", or they amend the list and you re-post and they agree) promotes the ticket to build-ready. An AC comment with no agreement is not a green light — do not build.
4. The AC they agreed becomes the Ready-to-Test acceptance criteria in /ro:linear-update — validation checks the exact list they signed off, so nothing silently gets dropped.

The sequence is: (open questions →) answers → post AC → they agree → build. If there were no questions, skip straight to posting AC and awaiting agreement; never jump from a fresh ticket to building.

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

The board is the report; never leave a processed ticket where you found it. Every move posts a plain comment (as the RoBot user — no label, no footer). Four 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. AC posted, awaiting agreement (questions answered, or none needed — but the creator hasn't agreed the AC yet) → post the Acceptance-Criteria comment (Step 3a) → state questions (back with the creator to sign off). This is NOT build-ready. 2b. Build-ready (the creator has explicitly agreed the AC) → post a short confirmation that locks it in ("Locked in, building to the AC above → Ready to Build.") → 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. Only AC-agreed tickets reach this state.
3. Shipped and confirmed — only when the collaborator has explicitly said they tested it and are happy (see § "The Done rule"; "all good, tested it" qualifies, "thanks" / silence does not) → one-line closing comment → state Done. Anything short of an explicit tested-and-happy confirmation stays in Interview with a nudge to try it and confirm.
4. Holdoff (collaborator said hold off / park it / not now, or Ronan flagged it) → one quiet comment acknowledging it ("parking this for now — nudge it back to the top when you want it") → state holdoff from the config (create it, type backlog, if missing). A holdoff ticket drops out of every other run's target set until the collaborator moves it back; don't grill it, don't build it.

Step 4: Report

Print per ticket: questioned / grilled (build-ready) / done / held off / 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-run — the single front door that chains this skill → build → close, and adds the idea-ticket pass; run that to do the whole loop
• /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