Merge branch 'next' into jc/docs-fee-juice-bridging

Author: critesjosh

.claude/skills/create-issue/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: create-issue
+description: Create a well-formed Linear issue — with complete context for a fresh agent, a point estimate (1/2/3/5), and acceptance criteria. Works standalone or as part of planning a project with multiple issues. Use when asked to file/create/open a Linear issue, "make a ticket", or when breaking a plan into tracked work.
+---
+
+# Create a Linear Issue
+
+Turn a unit of work — a bug, a CI failure, a task, or one slice of a larger plan — into a Linear issue that a **fresh agent with no prior context** could pick up and execute end-to-end. The default failure mode is an under-specified ticket; the whole point of this skill is to prevent that.
+
+## Two modes
+
+This skill applies in two situations. The difference is only *how much you already know* — the quality bar for the issue body is identical.
+
+- **Standalone** — the user asks you to file a single issue. You likely need to ask for team, project, labels, and priority.
+- **Planning / project breakdown** — you've been designing a project with the user and are now creating one or more issues under it. The project, team, labels, milestones, and conventions are already established in the conversation — **inherit them, don't re-ask.** Apply the same project/labels/priority conventions across the set, set `parentId` or `project` accordingly, and use `blockedBy`/`blocks` to encode dependencies between the issues you create. Only ask when something is genuinely ambiguous.
+
+## Principle: the issue must be self-contained
+
+Whoever (or whatever) picks up the issue will not have seen this conversation. Before writing, gather the real context — read the PR/diff, the failing test, the relevant source files, the CI log, the design discussion — and put the *findings* into the issue, not a pointer to "go investigate". A good issue includes:
+
+- **Summary** — one paragraph: what the work is and what the resolution looks like.
+- **Context / evidence** — for a bug: the actual error output, failing test name, log excerpt, or reproduction (paste it, don't just link it). For planned work: the relevant design decisions and constraints from the discussion.
+- **Approach / root cause** — the *why* and the *how*, with concrete file paths and line references (`path/to/file.ts:63`). For a bug, the root cause; for a feature, the intended approach. If something is genuinely unknown, say so explicitly and scope the issue as an investigation.
+- **The change** — the specific work to do, including code snippets where they clarify. Call out anything that looks like an obvious approach but is **wrong**, and why (saves the next agent from a dead end).
+- **Acceptance criteria** — see below; always required.
+- **References** — PRs, related issues, branches, dashboards, design docs.
+
+Match scope to the work: a one-line fix needs a short issue, a feature needs more. But "self-contained" is non-negotiable at every size.
+
+## Acceptance criteria are required
+
+Every issue gets a checklist of concrete, verifiable criteria that define "done". Each item must be objectively checkable — a test passes, a value is set, a behavior changes — not vague ("works better"). Include negative criteria where relevant ("does NOT also add X, because Y"). If you cannot write acceptance criteria, the issue is too vague to file — clarify it first.
+
+## Point estimate (the scoring system)
+
+Estimates use the scale **1, 2, 3, 5** (no other values). Roughly:
+
+- **1** — trivial, fully understood. A known one-line / few-line change with the diagnosis already done. Minimal risk.
+- **2** — small and well-understood, but more than trivial: a handful of files, or a tiny change that still needs non-trivial verification (e.g. landing a timing-sensitive test through CI).
+- **3** — medium. Real implementation work, multiple files, or meaningful unknowns to resolve along the way.
+- **5** — large. Substantial work, cross-cutting changes, or significant design/unknowns. If it feels bigger than 5, it should probably be split into multiple issues.
+
+Pick the estimate, then state your reasoning to the user in one line so they can override (they often will). Set it via the `estimate` field on `save_issue`.
+
+## What to confirm (ask only what you don't already know)
+
+In planning mode most of these are already settled — inherit them. In standalone mode, use `AskUserQuestion` to resolve anything unclear rather than guessing:
+
+1. **Team** — which Linear team. Get the user's teams from `get_user` (query `"me"`); offer them as options. Required to create an issue.
+2. **Project** — whether to attach to a project. If a project is being planned, use it. Otherwise ask, and if yes, list the team's projects (`list_projects`) to choose.
+3. **Labels** — which labels to apply. Fetch the team's labels (`list_issue_labels` with the team) and offer the relevant ones as a multi-select rather than a blank prompt. In planning mode, apply the project's agreed label convention.
+4. **Priority** — if not already stated or implied by the plan, ask. Linear priority values: `1`=Urgent, `2`=High, `3`=Medium, `4`=Low, `0`=None.
+
+If the user already specified any of these, honor it and don't re-ask.
+
+## Standard fields
+
+- **Assignee** — `assignee` accepts `"me"`, a name, email, or user ID.
+- **Cycle** — "this cycle" / "current cycle": call `list_cycles` with the team's ID and `type: "current"`, then pass the cycle number or ID to the `cycle` field.
+- **Parent / dependencies** — `parentId` for sub-issues; `blockedBy` / `blocks` to encode ordering between issues created from the same plan.
+- **Links** — attach source PRs/runs/docs via the `links` field (`[{url, title}]`).
+
+## Steps
+
+1. Gather context for the unit of work — read PR/diff/logs/source/design as relevant. Do not file from memory alone.
+2. Decide the point estimate (1/2/3/5) and draft acceptance criteria.
+3. Resolve team, project, labels, priority. In planning mode inherit them from the project; in standalone mode `get_user` ("me") and ask for anything not already specified.
+4. If "this cycle", resolve the current cycle via `list_cycles`.
+5. Create with `mcp__linear-server__save_issue` (`team`, `title`, `description` in Markdown, `assignee`, `priority`, `estimate`, `cycle`, `labels`, `project`, `parentId`, `blockedBy`/`blocks`, `links` as applicable).
+6. Report each created issue's identifier and URL, and state the estimate + reasoning so the user can adjust.
+
+## Notes
+
+- `save_issue` `description` takes Markdown with **literal** newlines — do not escape them.
+- Re-running `save_issue` with an `id` updates the issue (e.g. to change the estimate after the user weighs in).
+- When creating several issues from one plan, keep titles, labels, and estimate reasoning consistent across the set.

.claude/skills/merge-train-infra/SKILL.md

@@ -29,7 +29,7 @@ The merge-train system is fully automated via GitHub Actions in `.github/workflo
 
 Merge-train branches influence CI mode:
 - `merge_group` events or `ci-merge-queue` label → `merge-queue` mode
-- If the merge-group event is for `merge-train/spartan` or `merge-train/spartan-v5` → upgraded to `merge-queue-heavy` mode (10 parallel grind runs instead of 4)
+- If the merge-group event is for `merge-train/spartan-v5` → upgraded to `merge-queue-heavy` mode (10 parallel grind runs instead of 4)
 - Target branch `merge-train/docs` → `ci-docs` mode
 - Target branch `merge-train/barretenberg` → `ci-barretenberg` mode
 

.claude/skills/merge-trains/SKILL.md

@@ -43,7 +43,7 @@ A merge train is an automated batching system (inspired by [Rust rollups](https:
 ## CI Behavior for Merge Trains
 
 - **Specialized CI modes**: PRs targeting `merge-train/docs` run docs-only CI. PRs targeting `merge-train/barretenberg` run barretenberg-only CI. This avoids running the full test suite for domain-specific changes.
-- **Merge-queue mode**: When the merge-train PR enters GitHub's merge queue, it runs the full `merge-queue` CI mode (4 parallel grind runs on AMD64 + 1 ARM64). `merge-train/spartan` and `merge-train/spartan-v5` use the heavier `merge-queue-heavy` mode (10 grind runs).
+- **Merge-queue mode**: When the merge-train PR enters GitHub's merge queue, it runs the full `merge-queue` CI mode (4 parallel grind runs on AMD64 + 1 ARM64). `merge-train/spartan-v5` uses the heavier `merge-queue-heavy` mode (10 grind runs).
 - **Full concurrency**: Merge-train PRs get unique CI concurrency groups (using `github.run_id`), so multiple CI runs can proceed in parallel without cancelling each other.
 - **Test history tracking**: Test results are tracked for merge-train PRs, same as merge-queue runs.
 

.claude/skills/prep-cycle/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: prep-cycle
+description: Build or adjust a Linear cycle — for a whole team or just yourself. Size capacity from last-3-cycle velocity, fill with backlog bugs/high-priority items first and project work after (in your chosen project focus order), with no unassigned issues. Use when planning/prepping a cycle for a team, or when one member wants to fill/rebalance their own cycle work.
+---
+
+# Prepare a Cycle
+
+Assemble a capacity-sized cycle by **curating existing issues** (from focus projects + the backlog) — not by authoring new ones. The output is a cycle where each in-scope member is loaded up to their historical velocity, high-priority/bug work sits ahead of project work, and nothing in scope is unassigned.
+
+If you do need to *create* a missing issue along the way, follow the [[create-issue]] standard for it.
+
+## Before you start — resolve scope, team & target
+
+1. **Scope** — determine who this run is for:
+   * **Whole team** — prep/rebalance the cycle for every included member (the default when prepping a team's cycle).
+   * **Just me / a single member** — a member filling or adjusting *their own* cycle work. Skip the roster-inclusion prompt entirely; the one member is the roster. Resolve "me" via `get_user` ("me"), or use the named member.
+   If the request doesn't make scope obvious (e.g. "prep Alpha's cycle" → team; "fill my cycle" / "sort out my sprint" → self), ask which.
+2. **Team** — the skill is team-agnostic; **always ask which team** unless the user already named one. Resolve options from `get_user` ("me") / `list_teams`. In self mode, default to the team that owns the target cycle.
+3. **Target cycle** — ask whether you're filling the **current** cycle or the **next** one. Get cycle numbers via `list_cycles` (type `current` / `next`). Call the target cycle's number `C`.
+4. **Build vs adjust** — a target cycle may already hold issues. If so, ask whether to **top up** in-scope members to capacity (leave existing cycle items in place, only add) or **rebalance** (also reconsider what's there). Either way, only ever touch the in-scope members' own work — never move or reassign another member's issues.
+
+## Step 1 — Roster & focus (prompt per in-scope member)
+
+* **Inclusion** — *team mode only.* Get the team's members (`get_team` / `list_users team:<team>`) and ask which are in this cycle (`AskUserQuestion` multiSelect; if more than 4 members, split across questions, max 4 options each). If the team has a **default roster** below, pre-select those as the default and just confirm. In self mode, skip this — the single member is the roster.
+
+  **Default rosters** (the usual cycle members for a team; confirm, don't assume):
+  * **Alpha** — Phil, Palla, Alex, Facundo, Spyros.
+
+  Add other teams' defaults here as they're established.
+* **Project focus order** — for each in-scope member, ask the **ordered** list of projects they focus on (first = highest focus). `AskUserQuestion` options don't encode order reliably, so either ask the projects as a multiSelect then confirm the resolved order back in text, or ask the user to state the order explicitly. List the team's projects (`list_projects team:<team>`) as the option set. In self mode this is just one quick question for the calling member.
+
+Record, per in-scope member: `{ projects: [ordered] }`. Out-of-scope members get nothing assigned and their existing work is left untouched.
+
+## Step 2 — Size capacity from the last 3 cycles
+
+For each in-scope member `m`, compute their **per-cycle velocity** from completed work:
+
+* For each of cycle numbers `C-1`, `C-2`, `C-3`: `list_issues` with `cycle:<number>`, `assignee:<m>`, and a completed state filter (`state:Done` / completed-type). Sum the `estimate` of those issues → that cycle's completed points for `m`.
+* `capacity(m) = round(mean of the available cycle totals)`. If `m` has fewer than 3 cycles of history, average over what exists. If `m` has **no** history, ask the user for a manual capacity rather than guessing.
+
+Report the per-member capacities (and team total in team mode) before filling, so the user can adjust. The cycle is filled **up to** each member's capacity — never over it. In self mode, subtract any work already in the target cycle for `m` from their capacity so a top-up doesn't overload them.
+
+> Only **completed** issues count (Linear "Done"/completed type). Canceled/Duplicate do not. Issues without an `estimate` contribute 0 to history and can't be allocated by points later — flag them (see Step 4).
+
+## Step 3 — Backlog bugs & high-priority items go first
+
+Pull **non-project** backlog work that must jump the queue:
+
+* `list_issues` for the team with `state` of backlog/triage type and **no project**, filtered to: priority **Urgent (1)** or **High (2)**, OR carrying a bug label (`Bug`). Run the queries you need and dedupe.
+* **Team mode:** for each such issue ensure an assignee — keep the existing one; if **unassigned**, ask the user who to assign it to (these cannot stay unassigned), preferring the member whose focus/expertise fits.
+* **Self mode:** only pull items already assigned to `m`, plus unassigned ones the member explicitly chooses to take — don't hand out bugs to other people. Leave items assigned to others alone.
+* Add each in-scope item to the target cycle. These count against that member's `capacity(m)` and are placed **ahead** of their project work (see ordering note below).
+
+## Step 4 — Fill remaining capacity with project work (in focus order)
+
+For each included member `m`, after their Step-3 items, walk their `projects` in focus order and pull issues to fill the rest of `capacity(m)`:
+
+* `list_issues` per project, restricted to unstarted/backlog issues. Within a project, take them in priority order (Urgent → High → Medium → Low), then backlog order.
+* Assign each pulled issue to `m` (if it already has a different assignee, leave it for that person and skip — don't reassign someone else's in-progress work) and set its `cycle` to the target.
+* Keep a running total; stop adding to `m` once the next issue would exceed `capacity(m)`. Move to the next project in focus order only while capacity remains.
+* **Issues with no estimate** can't be point-allocated. Don't silently skip or guess: **propose an estimate** on the 1/2/3/5 scale (per [[create-issue]]) from the issue's scope/complexity, **prompt the user to confirm or correct it**, then write it back with `save_issue` (`estimate`) before counting it toward capacity. Batch these confirmations (one prompt covering several issues) rather than one prompt per issue.
+
+Don't assign the same issue to two members. If a project appears in multiple members' focus lists, split its issues between them as you go.
+
+## Step 5 — Enforce: no unassigned items
+
+Everything **this run added** to the cycle must have an assignee. In team mode, `list_issues cycle:<C> assignee:null` for the team must come back **empty** — assign anything unassigned (ask when the owner isn't obvious) or remove it. In self mode, only guarantee this for the items you added/own; don't touch pre-existing unassigned issues you didn't put there (mention them if you spot them).
+
+## Step 6 — Write & report
+
+* Apply changes with `save_issue` (`id`, `cycle:<C>`, `assignee`) per issue.
+* Report a per-member summary: capacity, points allocated, the ordered list of issues (bugs/high-priority first, then project work by focus order), and any flagged items (no estimate, newly assigned, capacity left unfilled because the projects ran dry).
+
+## Ordering note (Linear limitation)
+
+This MCP can't set a manual board position within a cycle, so "ahead of project work" is expressed through **priority** — Urgent/High bug items already sort above Medium project work. If a strict manual order is needed beyond what priority gives, call it out so the user can drag-order in the Linear UI.
+
+## Tools
+
+`get_user`, `get_team`, `list_users`, `list_projects`, `list_cycles`, `list_issues` (by `cycle` / `project` / `assignee` / `state` / `priority` / `label`), `save_issue` (set `cycle`, `assignee`, `estimate`).
+
+**Linear MCP reliability (learned the hard way — follow exactly):**
+- **Apply `save_issue` writes ONE AT A TIME, never in parallel.** Multiple `save_issue` calls issued together in one turn get silently dropped — only some persist. Sequential, one write per turn, is reliable.
+- **All reads lag (eventual consistency)** — `list_issues`, `save_issue` echoes, *and even `get_issue`* can return pre-write state for several seconds after a write. A "missing" change is usually read-lag, not a failed write. To confirm: re-issue the (idempotent) `save_issue` and check that its echo reflects the change (the echo returns the last *persisted* state), rather than trusting one `get_issue`.
+- `list_issues` for a whole cycle/large project can exceed the output limit and be saved to a file — filter (by `state`/`priority`/`assignee`) or `jq` the file instead of widening the limit.
+- Large multi-cycle history: query per cycle and aggregate completed `estimate` by assignee with `jq`.