Skip to content

πŸͺ’ Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

docs(agents): let agents write to the tracker, and give the practice a home (#17017)

Nikita Kabardin0b8d7eb18176
diff --git a/.agents/AGENTS.md b/.agents/AGENTS.md
index 59f5fbd337..686cbcf196 100644
--- a/.agents/AGENTS.md
+++ b/.agents/AGENTS.md
@@ -36,10 +36,14 @@ evaluating, and debugging AI applications.
commands, to avoid zsh glob expansion issues with dynamic Next.js routes.
- Never invoke Node-installed binaries through `./node_modules/.bin/*`. Always run them through `pnpm`.
- Never put internal ticket ids (`LFE-1234`, `LFINT-1234`, `CLI-Q226-12`) or
- Linear URLs into anything this repo publishes: code comments, docs prose,
- commit messages, PR titles and descriptions, or changelog entries. They mean
- nothing to OSS readers. Describe the problem on its own terms; a
- ticket-prefixed branch name is the one place the identifier belongs.
+ tracker URLs into anything an OSS reader meets: code comments, commit messages,
+ PR titles and descriptions, changelog entries, or user-facing docs. They mean
+ nothing to them. Describe the problem on its own terms; a ticket-prefixed
+ branch name is the one place the identifier belongs.
+ - `.agents/skills/**` is the exception, for identifiers only. Those files are
+ maintainer guidance, and an id there is provenance an engineer can follow β€”
+ "the shape from LFE-10959", "the worked example". Tracker URLs stay out even
+ here: they cannot be opened from a fork and they carry the workspace name.
- Code comments document behavior for future readers, not the reasoning
behind the current change. Do not reference PR/review history ("changed X
to Y", "now also handles", "per review", "was previously") or describe
@@ -81,10 +85,9 @@ Two moments in every task, both easy to skip and both expensive:
later.
The practice, its template and its tooling are the `linear-context-handover` and
-`linear-planning` skills in the private `langfuse/langfuse-internal-skills`
-plugin, alongside `linear-agent-writes`, which is the policy for what an agent
-may write to the tracker and how it must be marked. Read those rather than
-improvise. If this environment cannot reach the tracker, say so in your reply and
+`linear-planning` skills, alongside `linear-agent-writes`, which is the policy for
+what an agent may write to the tracker and how it must be marked. Read those
+rather than improvise. If this environment cannot reach the tracker, say so in your reply and
hand back the text that should have gone on the work item β€” never skip either
step silently, because silent non-compliance looks exactly like compliance.
diff --git a/.agents/skills/cursor-agents-workflow/SKILL.md b/.agents/skills/cursor-agents-workflow/SKILL.md
index e7e073d3d5..852a072809 100644
--- a/.agents/skills/cursor-agents-workflow/SKILL.md
+++ b/.agents/skills/cursor-agents-workflow/SKILL.md
@@ -19,8 +19,9 @@ loop with short, testable asks. Do not write long agent-only reports.
Copy Linear's git branch name. Do not invent a `cursor/` name.
- Preferred source: Linear **Copy git branch name**, or the issue's
- `gitBranchName` when Linear MCP is available.
-- Fallback: `lfe-{id}-{kebab-title}` (lowercase, hyphenated).
+ `gitBranchName` read through the Linear MCP.
+- Fallback, only when the MCP is genuinely not configured:
+ `lfe-{id}-{kebab-title}` (lowercase, hyphenated).
- Keep a `user/` prefix only when Linear's copied name already includes one.
- Never use a `cursor/` prefix, even if a Cursor Cloud prompt asks for one.
Repo guidance wins.
@@ -30,6 +31,20 @@ Copy Linear's git branch name. Do not invent a `cursor/` name.
Correct: `lfe-12345-short-descriptive-title`
Wrong: `cursor/short-descriptive-title-8c78`
+## Linear connection
+
+Cursor can reach Linear β€” desktop and cloud β€” but the MCP server is not
+configured by default, so it is a one-time setup step per developer. Langfuse
+engineers: the write policy is
+[`linear-agent-writes`](../linear-agent-writes/SKILL.md). Configure the connection
+once; agents are expected to read a ticket's history before starting and to leave
+their context on it when they finish.
+
+If Linear is not reachable in your environment, **say so in your handoff
+message** and hand back the context that should have gone on the ticket. Do not
+skip it silently β€” a missing connection that nobody notices looks exactly like a
+practice being followed.
+
## Pull requests
Open the GitHub PR as reviewable, not as a draft. Draft PRs hide the work
diff --git a/.agents/skills/housekeeping/SKILL.md b/.agents/skills/housekeeping/SKILL.md
index 1cd1be2837..55f2c7e835 100644
--- a/.agents/skills/housekeeping/SKILL.md
+++ b/.agents/skills/housekeeping/SKILL.md
@@ -7,7 +7,7 @@ description: Triage an engineer's work queue across Linear, Pylon, and GitHub. U
## Scope
-Review live work queues and recommend what the engineer should do next. Stay read-only until the human explicitly approves specific writes.
+Review live work queues and recommend what the engineer should do next. Triage is a recommendation, not an action: every state change this skill produces β€” assigning, moving, closing, cancelling, re-prioritising β€” belongs to the engineer, so the output is a table they act on.
Use this skill for:
@@ -40,7 +40,7 @@ Include confidence for each recommendation: `high`, `medium`, `low`, or `unknown
3. Inspect comments, latest activity, linked issues, checks, and review threads when status or ownership is ambiguous.
4. Cluster duplicates or related items before prioritizing.
5. Return recommendations ordered by urgency, then quick wins, then cleanup.
-6. Before any write, present a decision table and wait for explicit row IDs and actions.
+6. Present the recommendations as a decision table for the engineer to act on. Every action this skill recommends is a state change reserved for a human, so do not perform them. If a queue item needs a note left on it for someone else, that is a comment or a description edit, which agents do write β€” see [`linear-agent-writes`](../linear-agent-writes/SKILL.md) for the shapes and the labels.
## Linear Review
@@ -109,14 +109,14 @@ Recommend:
- `stale-candidate` for old, conflicting, duplicate, or superseded PRs.
- `no-action` when a PR is blocked on the author, failing CLA, merge conflicts, unresolved requested changes, or unrelated team ownership.
-Do not approve, request changes, comment, close, merge, or edit a PR without explicit human approval for that PR.
+Do not approve, request changes, comment, close, merge, or edit a PR without explicit human approval for that PR. This is about **GitHub pull requests**, not the issue tracker β€” tracker comments and description edits follow `linear-agent-writes` and need nobody's permission.
## Human Gates
-All writes require explicit human confirmation by row ID. This includes:
+These writes require explicit human confirmation by row ID:
-- Linear comments, status changes, priority changes, assignee changes, labels, cancellation, or customer-need changes.
-- Pylon replies, internal notes, status changes, assignment, tags, snoozes, closes, or external-issue links.
+- Linear state β€” status, priority, assignee, labels, cancellation, or customer-need changes. Comments and description edits are **not** gated: they are two of the permitted agent write shapes, so leave them to [`linear-agent-writes`](../linear-agent-writes/SKILL.md), which owns the shapes and the labels.
+- Pylon replies, internal notes, status changes, assignment, tags, snoozes, closes, or external-issue links. This is customer-facing, and that gate stays.
- GitHub approvals, comments, requested changes, reviewer changes, closes, merges, labels, or branch actions.
If the user says "do the quick ones", first show the exact proposed writes and ask for confirmation unless they already named the exact row IDs.
diff --git a/.agents/skills/incident-alert-tickets/SKILL.md b/.agents/skills/incident-alert-tickets/SKILL.md
index 5fe8e5c755..25fa8fa113 100644
--- a/.agents/skills/incident-alert-tickets/SKILL.md
+++ b/.agents/skills/incident-alert-tickets/SKILL.md
@@ -1,9 +1,9 @@
---
name: incident-alert-tickets
description: |
- Read and, after human approval, update the Linear `incident-alert` knowledge
- base. Use before and after investigating a named Datadog monitor, incident.io
- alert or incident, or on-call page to find or record root causes.
+ Read and record root causes in the Linear `incident-alert` knowledge base. Use
+ before and after investigating a named Datadog monitor, incident.io alert or
+ incident, or on-call page to find or record root causes.
---
# Incident Alert Tickets
@@ -85,35 +85,45 @@ signals and classify:
investigation before any Datadog sweep.
- **New cause on existing ticket** β€” the monitor has a ticket but no section
matches the evidence. Propose appending a dated section.
-- **No ticket** β€” no ticket matches the monitor. Propose creating one.
+- **No ticket** β€” no ticket matches the monitor. Propose creating one, and file
+ it once that is approved.
Treat a partial match β€” some "Recognize it" signals fit, others do not β€” as a
**new cause**, never as a known one: do not recommend a documented "Fix"
whose recognition signals only partially match. Name the near-miss section in
-the draft so the human can judge the overlap.
-
-## Write-Back (Human Approval Gate)
-
-Never create or update a ticket without explicit human approval. Present the
-proposal first:
-
-| ID | Alert / Monitor | Classification | Proposed Action | Draft Content | Human Decision |
-| --- | --- | --- | --- | --- | --- |
-
-- `Proposed Action`: `append cause section to LFE-XXXX`, `create ticket`, or
- `none (known cause)`.
-- `Draft Content`: the dated section (or full ticket body) exactly as it would
- be written.
-- `Human Decision`: leave blank for the human to choose.
-
-Wait for the human to select row IDs and actions before writing. On approval:
-
-- **Append**: insert the new `---`-separated dated block after the existing
- cause sections, above the `Your cause is not listed?` trailer; leave
- everything else untouched.
-- **Create**: new Engineering (LFE) issue titled `[ENV] <Monitor title>` with
- the `incident-alert` label; description = alert header, the first dated
- cause section, and the `Your cause is not listed?` trailer.
+the proposed ticket so the human can judge the overlap.
+
+## Write-Back
+
+Appending a cause section to a ticket that already exists is a description edit,
+which agents do autonomously. A monitor with no ticket needs a parentless one,
+which is the single write that asks first β€” see
+[`linear-agent-writes`](../linear-agent-writes/SKILL.md) for the policy this
+follows, and read it before your first write.
+
+- **Append: do it.** Insert the new `---`-separated dated block after the
+ existing cause sections, above the `Your cause is not listed?` trailer; leave
+ everything else untouched. Mark the block as agent-written in its own text and
+ label the ticket `AI edited`. Never reflow or rewrite the human-written prose
+ around it.
+- **Create: show it, then file it.** Prepare the issue β€” title
+ `[ENV] <Monitor title>`, the `incident-alert` label, description = alert header,
+ the first dated cause section, and the `Your cause is not listed?` trailer β€”
+ show it for a go-ahead, and once you have one, create it yourself and label it
+ `AI created`. One go-ahead covers the whole run's proposed tickets.
+
+Report what you did either way:
+
+| ID | Alert / Monitor | Classification | Action | Content |
+| --- | --- | --- | --- | --- |
+
+- `Action`: `appended to <key> (AI edited)`, `awaiting your go-ahead`,
+ `filed <key> (AI created)`, or `none (known cause)`.
+- `Content`: the dated section, or the full ticket body exactly as it will be
+ filed β€” that text is what the go-ahead is given against.
+
+If Linear is unreachable in this environment, say so and return every row as text
+ready to paste rather than skipping the write-back silently.
## Division of Labor
diff --git a/.agents/skills/infra-scaling/SKILL.md b/.agents/skills/infra-scaling/SKILL.md
index 6a4c9539a0..92db0d0eea 100644
--- a/.agents/skills/infra-scaling/SKILL.md
+++ b/.agents/skills/infra-scaling/SKILL.md
@@ -24,7 +24,7 @@ Optimize the cost/performance tradeoff: run the smallest reliable container foot
- Use exact OpenTofu math for markers. Do not mental-math `ceil(target * boundary)` because Terraform float behavior can produce off-by-one results.
- For `web` and `web-iso`, do not reduce RPM per container solely because service latency is high. First inspect full APM traces, including ClickHouse spans, to distinguish container saturation from database-bound requests.
- If slow `web-iso` traces are dominated by ClickHouse child spans, do not lower RPM targets as the primary fix. Lowering RPM changes web-container scaling and request distribution, but it does not reduce ClickHouse query cost, total query workload, or an individual long-running query duration.
-- If scaling should be adjusted, create or update a GitHub PR. For Linear follow-ups, prepare a human-review table first and wait for explicit human approval before creating, updating, commenting on, or assigning tickets. Do not create or assign Linear tickets for Valeriy.
+- If scaling should be adjusted, create or update a GitHub PR. For the Linear follow-up, comment the evidence onto a ticket that already exists and label it; a new ticket has no parent, so show it and file it once that is approved, and never assign it. Step 8 has the detail.
## Files
@@ -207,22 +207,22 @@ Run a full plan only when credentials and workspace setup are available or the u
- Mention checks run and whether a full plan was not run.
- Return valid Markdown. Use valid headings, lists, links, tables, and code fences; include spaces after list markers; close every link, parenthesis, and code fence; and check for malformed tables before returning.
-8. Create a GitHub PR and prepare human-reviewed Linear follow-ups when scaling should be adjusted:
+8. Create a GitHub PR and record the Linear follow-up when scaling should be adjusted:
- Trigger this when the recommendation table contains at least one concrete scaling change, or when Terraform scaling settings were edited. Do not create a ticket for an all-`No change` review unless the user explicitly asks.
- Ensure there is a GitHub PR for the scaling change. If no PR exists yet, create one. Include the recommendation summary, validation, and rollout risks in the PR body.
-- Before any Linear write, present a review table and ask the human which row IDs and actions to approve:
-
-| ID | Finding | Evidence | Impact / Scope | Existing Ticket Match | Proposed Linear Action | Confidence | Human Decision |
-| --- | --- | --- | --- | --- | --- | --- | --- |
-| F1 | Scaling adjustment summary | Measured Datadog evidence, trace links, PR URL, or `No measurements found` | Affected env, service, route, customer segment, or blast radius supported by evidence | Existing issue key/link, duplicate candidate, or `None found` | Create new ticket, add evidence comment, update status/labels, or no action | High/medium/low plus one short reason | Leave blank for the human to choose |
-
-- Do not create Linear tickets, comment on tickets, edit ticket fields, add evidence, or assign an owner until the human explicitly selects one or more row IDs and actions. If the user asks for an automated sweep, still pause at this review table before writing to Linear.
-- After approval, use the Linear skill or Linear app tools. Create one ticket for the scaling adjustment, not one ticket per region, unless the user requests separate tickets.
-- Assign the ticket only when the user explicitly names an assignee. Otherwise leave it unassigned. Do not create or assign tickets for Valeriy.
-- Include the full skill output in the ticket description: recommendation table, Datadog evidence, trace interpretation, proposed or applied Terraform changes, marker math, validation results, plan status, PR URL, and known rollout risks.
-- Link the artifacts both ways after approval: put the PR URL in the Linear ticket, and put the Linear issue URL or identifier in the PR body or a PR comment. If one artifact is created after the other, update the first artifact once the second URL exists.
-- If GitHub PR creation or approved Linear ticket creation is unavailable, report that blocker and provide the exact PR body or ticket title/body that should be created manually.
+- Only three write shapes are permitted and each must be labelled and marked as agent-written. [`linear-agent-writes`](../linear-agent-writes/SKILL.md) is the authority; read it before your first write. For this skill: **adding evidence to a ticket that already exists is yours to do** (label it `AI commented`, or `AI edited` if you put the evidence in the description); **a new ticket has no parent, so it is the one write that asks first** β€” show the title and body, take one go-ahead, then create it and label it `AI created`.
+- Report what you wrote and what still needs a human:
+
+| ID | Finding | Evidence | Impact / Scope | Existing Ticket Match | Action | Confidence |
+| --- | --- | --- | --- | --- | --- | --- |
+| F1 | Scaling adjustment summary | Measured evidence, trace links, PR URL, or `No measurements found` | Affected env, service, route, customer segment, or blast radius supported by evidence | Existing issue key/link, duplicate candidate, or `None found` | `commented <key>`, `edited <key>`, `awaiting your go-ahead` plus the exact title and body, `filed <key>`, or `no action` | High/medium/low plus one short reason |
+
+- One ticket for the scaling adjustment, not one per region, unless the user requests separate tickets. Never leave an `awaiting your go-ahead` row without the full body β€” that text is what is being approved.
+- Do not assign an owner, move state, close, or re-prioritise β€” those stay with a human. Surface them as suggestions, and never propose an assignee the user did not name.
+- Include the full skill output in the ticket description: recommendation table, measured evidence, trace interpretation, proposed or applied Terraform changes, marker math, validation results, plan status, PR URL, and known rollout risks.
+- Put the PR URL in the Linear ticket. Do not put the ticket identifier or its URL in the PR body or a PR comment β€” this repo keeps those out of published artifacts; the branch name carries the link.
+- If the GitHub PR cannot be created, or Linear is unreachable in this environment, report that blocker and provide the exact PR body or ticket title and body that should be created manually. Do not skip the step silently.
## PR Handling
diff --git a/.agents/skills/langfuse-codebase-navigator/SKILL.md b/.agents/skills/langfuse-codebase-navigator/SKILL.md
index e356b23bb5..173b5e402c 100644
--- a/.agents/skills/langfuse-codebase-navigator/SKILL.md
+++ b/.agents/skills/langfuse-codebase-navigator/SKILL.md
@@ -27,6 +27,9 @@ Use this as the first stop for Langfuse org navigation. Your job is to choose th
- Product implementation in `langfuse/langfuse`: choose the matching repo-local skill under `.agents/skills`, such as `backend-dev-guidelines`, `frontend-browser-review`, `clickhouse-best-practices`, `add-model-price`, `turborepo`, `pnpm-upgrade-package`, `code-review`, or production-debug skills as applicable.
- Cursor Cloud or Cursor desktop agents implementing a Linear issue, opening a PR, asking a human to test, or handling Claude, Greptile, or Codex review comments: use `cursor-agents-workflow`.
- A change too large for one reviewable PR, splitting a long-lived branch into PRs, or propagating and retargeting a stack: use `pr-stack-workflow`.
+- Reconstructing why a surface is the way it is before changing it, or writing the reasoning behind finished work onto its Linear ticket: use `linear-context-handover`.
+- Turning a feature into Linear subtickets that map onto an intended PR stack: use `linear-planning`.
+- Before any agent write to Linear β€” a comment, a description edit, a ticket: use `linear-agent-writes`, the write policy.
- Frontend work under `langfuse/langfuse/web`: also check `web/.agents/skills/vercel-react-best-practices` and `web/.agents/skills/vercel-composition-patterns`.
- Infrastructure autoscaling or cloud capacity: use `infra-scaling`.
- Public Langfuse usage, docs lookup, API access, instrumentation, prompt migration, SDK upgrade, trace analysis, or CLI work: use the public `langfuse` skill from `langfuse/skills`.
diff --git a/.agents/skills/langfuse-previews/SKILL.md b/.agents/skills/langfuse-previews/SKILL.md
index 5e59439142..23a9ddbca9 100644
--- a/.agents/skills/langfuse-previews/SKILL.md
+++ b/.agents/skills/langfuse-previews/SKILL.md
@@ -193,8 +193,8 @@ kubectl annotate ns $NS downscaler/force-uptime- # undo later
your labeled PRs deploy β€” no admin needed.
- **Cluster access β€” available to all Langfuse engineers** (only needed to
debug with `kubectl`, not to *use* a preview). Set up local access using the
- `~/.aws/config` profile block from the internal Langfuse doc:
- https://linear.app/langfuse/document/connect-to-aws-instances-aurora-redis-from-local-machine-896fe46ff797
+ `~/.aws/config` profile block from the internal Langfuse tracker document
+ *"Connect to AWS instances (Aurora, Redis) from local machine"*.
1. Open `~/.aws/config` and add the `[sso-session langfuse]` + `[profile preview]`
blocks from that doc (keep any `[sso-session langfuse]` you already have).
2. `aws sso login --profile preview`
diff --git a/.agents/skills/linear-agent-writes/SKILL.md b/.agents/skills/linear-agent-writes/SKILL.md
new file mode 100644
index 0000000000..d368cf4fa6
--- /dev/null
+++ b/.agents/skills/linear-agent-writes/SKILL.md
@@ -0,0 +1,165 @@
+---
+name: linear-agent-writes
+description: |
+ The org policy for what an agent may write to Linear, and how it must be
+ marked. Read this before creating a ticket, editing a description, or
+ commenting on a ticket as an agent β€” "file this in Linear", "comment on the
+ ticket", "create subtickets for this plan", "write the handover". Also covers
+ the required Linear connection and what to do when there isn't one.
+---
+
+# Linear agent writes
+
+Agents write to Linear directly. There is **one** gate, for **one** shape: a
+ticket with no parent. Everything else β€” comments, description edits, subtickets
+β€” you just do.
+
+The guardrail is **marking plus a bounded set of shapes**: three permitted write
+shapes, each stamped with a label, each marked as agent-written in the text.
+Everything outside those three shapes still belongs to a human.
+
+This file is the **single authority** for that policy. Other skills and repo
+instructions point here; none of them restate the rules. If another document
+disagrees with this one, this one wins β€” fix the other document.
+
+It is maintainer-facing: it binds anyone whose agent can reach the Langfuse issue
+tracker, and it has nothing to ask of an outside contributor.
+
+*Provenance: the "Agentic Coding and Linear" RFC (LFE-15914), which replaced the
+earlier "Linear is read-only for agents" posture.*
+
+## Why the taboo went away
+
+Linear used to be human-only for agents, and every skill that touched it had to
+stop and present a review table first. That cost more than it protected: the
+expensive thinking in an agent session β€” the decisions, the reversals, the traps
+β€” evaporated when the session ended, because the one place it could have been
+written down was closed.
+
+Breaking the taboo is not removing the boundary. Marking is what replaces the
+gate: a human must always be able to tell, at a glance, which text on a ticket is
+theirs and which an agent wrote.
+
+## The three shapes
+
+They compose. Stamp **every** shape you used, so the labels read as a log of what
+agents did to the ticket.
+
+### 1. Comment β€” only when a human must be told something now
+
+Label `AI commented`. Mark the comment body itself as agent-written.
+
+A comment notifies every watcher. Use one when someone genuinely needs to see
+something today: a blocker, a question that stops the work, a finding that
+changes their plan.
+
+**Durable post-context does not go here.** A wrap-up handover posted as a comment
+sprays every watcher's inbox for something nobody needs to read today, and inbox
+spam is how a good practice gets switched off. That goes in the description.
+
+### 2. Edit a description β€” where post-context belongs
+
+Label `AI edited`. Add a **clearly separated agent block**; never rewrite,
+reflow, or "improve" the human's prose around it.
+
+This is the durable half of the practice. `AI edited` is the filter a future
+session uses to find prior agent reasoning, so the label is not decoration β€” it
+is the index.
+
+What belongs in such a block, how to append it without destroying the
+description, and why an attachment is not optional are
+[`linear-context-handover`](../linear-context-handover/SKILL.md).
+
+### 3. Create a ticket β€” a subticket freely, a top-level one after a yes
+
+Label `AI created`. Say in the description that an agent created it and who it is
+for.
+
+**A subticket of an existing ticket needs no permission.** The intended use is
+planning: one subticket per PR in an intended stack, created up front so the plan
+is visible before any branch exists, with enough context in each that an agent
+could implement it from the ticket alone β€”
+[`linear-planning`](../linear-planning/SKILL.md) is how.
+
+**A ticket with no parent needs the human's yes first** β€” a top-level issue, or
+one filed straight into a project. Show the title and the description you intend
+to file, get an explicit go-ahead, then **create it yourself**; do not hand the
+text back for them to paste, which is the cost you were meant to remove.
+
+This is the only gate in this policy, and it exists because a parentless ticket
+lands in somebody's triage queue. It is the one shape whose cost falls on people
+who did not ask for it.
+
+## What still belongs to a human
+
+Assigning, moving state, closing, estimating, re-prioritising, deleting,
+projects, and creating new labels.
+
+Surface these as suggestions in your reply β€” do not do them, and do not ask for
+permission to do them as a way of getting them done. (A top-level ticket is
+different: asking is exactly the right move there, and then you file it.)
+
+## Sweeps: ask once for the batch, not once per ticket
+
+A skill that reviews a whole queue β€” production errors, the alerts that fired
+last week, a scaling review β€” comes back with many findings at once, and the ones
+that have no ticket yet are parentless. So they need the yes.
+
+**Ask for the set, in one go.** Present the findings as a table with the title
+and body you would file for each, and get a single go-ahead β€” or a go-ahead for
+named rows. Then file them yourself and report what you filed. Asking twelve
+separate times is worse than the pasting it replaced.
+
+Evidence onto tickets that already exist is a comment or a description edit
+(shapes 1 and 2), so it is never part of that ask β€” do it as you go.
+
+## You need a Linear connection
+
+The practice only works if your agent can actually reach Linear β€” reading history
+before you start, writing the handover when you finish. In this repo the server is
+already declared for you: `.agents/config.json` lists `linear` as an HTTP MCP
+server, and `scripts/agents/sync-agent-shims.mjs` projects it into each tool's
+config on `pnpm install`. Those generated files are gitignored build artifacts β€”
+never hand-edit them.
+
+What is left per developer is **authorizing** it, which the first connection
+prompts for. On a headless surface there is nobody to approve that prompt, and a
+remote MCP can report itself connected before any token exists β€” so prove access
+with a real read rather than trusting an indicator, and use a token in an
+`Authorization` header there instead of the interactive flow. Do not commit that
+header: an unset variable is passed through literally and fails with no fallback.
+
+## When there is no Linear connection: say so, loudly
+
+If the Linear tools are absent, **do not silently skip the reconstruct or the
+handover.** Silent non-compliance is indistinguishable from compliance, and that
+is how a practice quietly dies.
+
+Say, in your reply, in plain language:
+
+- that this environment has no Linear access;
+- which step you could not complete (history reconstruction, the handover, the
+ subtickets);
+- and then **the content itself**, ready to paste β€” the handover block, the
+ subticket bodies, the comment.
+
+The work is not lost that way, and the missing configuration becomes visible
+instead of invisible.
+
+```text
+No Linear access in this environment, so the handover was not written.
+Here is the block that should go on the parent ticket's description
+(label it `AI edited`):
+
+<the handover block>
+```
+
+Never guess at a ticket's history from the code alone and present it as
+recovered context. Say the history could not be read.
+
+## Marking in the text, not only the label
+
+The Linear MCP writes as the **authenticated human**, not as a bot. An unmarked
+agent block reads as that person's own words to everyone who sees it. The label
+is for filtering; the in-text marking is what stops the misattribution. Do both,
+every time.
diff --git a/.agents/skills/linear-agent-writes/agents/openai.yaml b/.agents/skills/linear-agent-writes/agents/openai.yaml
new file mode 100644
index 0000000000..c2319582b3
--- /dev/null
+++ b/.agents/skills/linear-agent-writes/agents/openai.yaml
@@ -0,0 +1,4 @@
+interface:
+ display_name: "Linear Agent Writes"
+ short_description: "What an agent may write to Linear, and how it must be marked"
+ default_prompt: "Use $linear-agent-writes to check which Linear write shapes are permitted, which label stamps each one, and what still belongs to a human."
diff --git a/.agents/skills/linear-bug-triage/SKILL.md b/.agents/skills/linear-bug-triage/SKILL.md
index 3a121ea461..e5c94240f1 100644
--- a/.agents/skills/linear-bug-triage/SKILL.md
+++ b/.agents/skills/linear-bug-triage/SKILL.md
@@ -8,14 +8,30 @@ description: |
# Linear Bug Triage
Use this skill after a bug or regression candidate has measured evidence. This
-skill owns Linear search, deduplication, evidence comments, and ticket creation;
-the calling skill owns deciding whether the signal is issue-worthy.
+skill owns Linear search, deduplication, evidence comments, and filing new
+issues once a human says yes; the calling skill owns deciding whether the signal
+is issue-worthy.
-## Human Approval Gate
+## What This Skill May Write
-Before doing anything in Linear, first show the findings to the human in a
-compact markdown table and ask for explicit permission to share them in Linear.
-The table should include one row per candidate with:
+Every write carries a label and is marked as agent-written in the text, and only
+three write shapes are permitted at all.
+[`linear-agent-writes`](../linear-agent-writes/SKILL.md) is the authority for that
+policy; read it before your first write and prefer it over this summary wherever
+they differ.
+
+For this skill it resolves to:
+
+- **An evidence comment on an issue that already exists: just do it.** Label that
+ issue `AI commented` and say in the comment body that an agent wrote it. This
+ is the common case and needs nobody's permission.
+- **A new top-level issue: ask once, then file it.** A bug cluster surfaced by a
+ review has no parent, and a parentless ticket is the one shape that needs a
+ go-ahead. Take one go-ahead for the whole set, or for named rows β€” never one
+ question per candidate.
+
+So present the findings table either way: it is what the go-ahead is given
+against, and it is the report afterwards. One row per candidate:
- Candidate / cluster name.
- Environments.
@@ -23,15 +39,16 @@ The table should include one row per candidate with:
- Recent window measurement.
- Baseline measurement.
- Delta / regression summary.
-- Key Datadog evidence links.
-- Proposed Linear action (`comment existing`, `create new`, or `none`).
+- Key evidence links β€” the ones *Required Evidence* below asks for.
+- Action: `commented <issue key>` for what you already did, `filed <issue key>`
+ once a row is approved and created, or `awaiting your go-ahead`.
-If the human does not explicitly approve, stop after presenting the table. Do
-not search Linear, do not comment on issues, and do not create issues.
+Never present an `awaiting your go-ahead` row without the exact title and body
+you intend to file underneath it β€” that text is what is being approved.
+Deduplicate first, so comments land on the right issue.
-If a calling workflow already showed the findings table and obtained explicit
-human approval for a Linear handoff, skip this gate and proceed directly to
-deduplication.
+If Linear is unreachable in this environment, say so plainly and return every row
+as text ready to paste. Do not skip the handoff silently.
## Required Evidence
@@ -52,16 +69,17 @@ measurements alone.
## Deduplication
-After the human explicitly approves, before creating a new issue:
+Always, before writing anything:
1. Search Linear for related open issues using exact error text, route/resource,
- service, environment, monitor name, and Datadog link keywords.
+ service, environment, monitor name, and observability link keywords.
2. Search recently closed or canceled issues if the error is recurring or the
wording is distinctive.
-3. If a related issue exists, add a concise evidence comment instead of creating
- a duplicate.
-4. If no related issue exists, create one Linear issue in the `Triage` state for
- each distinct bug cluster.
+3. If a related issue exists, add a concise evidence comment to it and label it
+ `AI commented`.
+4. If no related issue exists, prepare the issue in the format below and put it
+ in the findings table as `awaiting your go-ahead`. File it once the go-ahead
+ comes, and update the row to `filed <issue key>`.
## Existing Issue Comments
@@ -70,14 +88,14 @@ For related existing issues, add only:
- Recent window and baseline window.
- Measured delta or `No measurements found` for unavailable signals.
- Affected environments, services, routes/resources, and top error messages.
-- Datadog links.
+- The evidence links from *Required Evidence*.
Do not add fix suggestions, root-cause guesses, implementation notes, owner
assignments, or next steps.
## New Issue Format
-Create new issues with:
+The shape to prepare, show for the go-ahead, and then file:
- State/status `Triage`; pass the Linear state explicitly on creation and do not
rely on workspace defaults.
diff --git a/.agents/skills/linear-context-handover/SKILL.md b/.agents/skills/linear-context-handover/SKILL.md
new file mode 100644
index 0000000000..5f5c1134ff
--- /dev/null
+++ b/.agents/skills/linear-context-handover/SKILL.md
@@ -0,0 +1,125 @@
+---
+name: linear-context-handover
+description: |
+ Use Linear as the org's memory: reconstruct a feature's history before
+ touching it, and leave the reasoning behind finished work in the ticket
+ description so the next agent inherits it. Use when starting work on an
+ existing feature, when planning multi-PR work, and always when wrapping up β€”
+ "what happened to this screen before", "write the handover", "why is this
+ code like this".
+---
+
+# Linear context handover
+
+Linear is the org's long-term memory. Agent sessions are not β€” they end, and
+everything they worked out ends with them. This skill is how reasoning survives
+the session that produced it.
+
+Two halves, and the second one is the one people skip:
+
+1. **Before you touch a feature, reconstruct its history.** Most "new" work on an
+ existing surface has a paper trail that answers half the design questions.
+2. **When you wrap up, write the handover into the ticket's description.**
+
+What an agent may write to Linear, which label stamps it, and what stays
+human-only are not in this file:
+[`linear-agent-writes`](../linear-agent-writes/SKILL.md) is the authority. Read
+it before your first write. This file is the *craft* β€” where post-context goes,
+what earns a place in it, and the two mechanics that stop it being destroyed on
+the way in.
+
+How to slice a big change into PRs, and what a planning subticket must contain,
+are the sibling skill: [`linear-planning`](../linear-planning/SKILL.md).
+
+## Before you touch a feature: reconstruct its history
+
+Do this before designing anything. A reversal already litigated once does not
+need re-litigating.
+
+**Start with the CLI**, which walks steps 1–3 for you and prints the ticket ids,
+the URLs and the exact MCP calls for step 4. Run it from inside the checkout you
+are about to change:
+
+```bash
+S=.agents/skills/linear-context-handover/scripts/lf-context.sh
+bash $S web/src/features/experiments/.../ExperimentsTable.tsx
+bash $S 65bbc753c # a sha Β· 16912 # a PR Β· LFE-15711 # a ticket
+bash $S --help # options, and what is automatic
+```
+
+Everything up to the ticket ids is automatic. The ticket bodies need Linear: the
+script queries the API directly if `LINEAR_API_KEY` is exported, and otherwise
+prints the ids, URLs and MCP calls for you to run β€” so the agent hand-off is the
+normal path, not a failure.
+
+By hand, the same chain is:
+
+1. **Code β†’ PR.** `git log --follow <path>` on the files you are about to change,
+ then the commit's PR (`gh api repos/<owner>/<repo>/commits/<sha>/pulls`).
+2. **PR β†’ ticket.** The **branch name** carries the identifier
+ (`lfe-15489-release-to-everybody` β†’ LFE-15489). PR titles and descriptions in
+ these repos deliberately omit ticket ids, so the branch is the only link.
+3. **Ticket β†’ the rest.** Read the description including any AI block, then walk
+ `parentId`, the subtickets, `relations`, and the project. The project's other
+ tickets are usually where the decisions live.
+4. **Ticket β†’ prior agent reasoning.** Filter the `AI edited` label to find where
+ earlier sessions left context.
+
+Read all of it before proposing a direction.
+
+## When you wrap up: write the handover
+
+Into the **description** of the ticket the work belongs to, as a clearly
+separated agent block. Label the ticket `AI edited`.
+
+**Scale it.** One substantial handover on the project or parent ticket, short
+pointers on the leaves. The same essay repeated on eight tickets is noise, not
+context.
+
+**The reversals are the payload.** A summary of what shipped is the least
+valuable section β€” the PR already carries the diff and the ticket already carries
+the state. What only this block can carry is the thing that was built and then
+deliberately removed, and why: without it the next session rebuilds it, argues
+the same argument, and reaches the same verdict a week later. Write the reversals
+first and the summary last; if you are short of room, cut the summary.
+
+The rest of what earns its place, and the paste-ready shape, is
+[`references/handover-template.md`](references/handover-template.md): decisions
+and why, how the human steered (quoted), the tools and recipes that reproduce the
+state, the traps, and what is left open.
+
+### Two mechanics, or the handover damages what it lands in
+
+**Write it with a `patch` `append` op, never by re-sending the description.**
+A full rewrite is how "never rewrite the human's prose" fails in practice, and it
+also flattens the inline `<user>` / `<linear-comment>` elements Linear stores
+inside a description β€” which no diff will show you afterwards. Use `patch` with
+`replace` and an exact `old_string` to correct your own block later.
+
+**Attach files and images; never paste an upload URL.** Linear's uploaded-file
+URLs are **signed and expire in about five minutes**, so a pasted image link is
+already dead by the time any agent β€” or human β€” opens the ticket. Go through
+`prepare_attachment_upload` + `create_attachment_from_upload`. This has cost real
+context twice: one piece of review feedback is permanently unactionable because
+the screenshot it pointed at was an expired signed URL. Long analyses belong in an
+attached `.md` for the same reason a description has a readable length.
+
+## The labels, and the one note the policy does not carry
+
+The permitted shapes, the label for each, the marking-in-text requirement and the
+human-only list are all in
+[`linear-agent-writes`](../linear-agent-writes/SKILL.md). If this file disagrees
+with it, this file is the bug.
+
+One thing specific to *reading* history: **`AI edited` is the filter that
+matters.** Post-context lives in descriptions, so that is the label that finds
+prior reasoning. `AI commented` only tells you an agent said something to a human
+on a particular day, usually stale by the time you read it.
+
+## No Linear access
+
+Say so, name the step you could not complete, and hand back the content ready to
+paste β€” the rule and the wording are in
+[`linear-agent-writes`](../linear-agent-writes/SKILL.md) β†’ *When there is no
+Linear connection*. Never reconstruct a feature's history from the code alone and
+present it as recovered context.
diff --git a/.agents/skills/linear-context-handover/agents/openai.yaml b/.agents/skills/linear-context-handover/agents/openai.yaml
new file mode 100644
index 0000000000..c575ff1ffc
--- /dev/null
+++ b/.agents/skills/linear-context-handover/agents/openai.yaml
@@ -0,0 +1,4 @@
+interface:
+ display_name: "Linear Context Handover"
+ short_description: "Reconstruct a feature's history, and hand your reasoning over"
+ default_prompt: "Use $linear-context-handover to reconstruct a feature's history before changing it, and to write the handover onto its work item before asking for review."
diff --git a/.agents/skills/linear-context-handover/references/handover-template.md b/.agents/skills/linear-context-handover/references/handover-template.md
new file mode 100644
index 0000000000..eac484862d
--- /dev/null
+++ b/.agents/skills/linear-context-handover/references/handover-template.md
@@ -0,0 +1,75 @@
+# Handover block template
+
+Append this to the ticket's **description**, below whatever is already there,
+separated by a rule. Never edit the text above it β€” it may be a human's prose or
+an earlier agent's block, and neither is yours to rewrite. Label the ticket
+`AI edited`.
+
+Keep the headings you have content for and drop the rest β€” an empty section is
+worse than no section. Quote the human verbatim where a decision hinged on a
+phrase; a paraphrase loses the force of it.
+
+```markdown
+---
+
+## πŸ€– AI post-context
+
+*Written by <agent> on <date>.*
+
+### What shipped
+
+One paragraph, then the PR numbers. Include the thing that was **not** obvious
+from the diff β€” the surface nobody tested, the path that changed by accident.
+
+### Decisions, and why β€” reversals included
+
+1. **<Decision>.** The reasoning, and the evidence if there was any. If it was
+ reversed later, say so here rather than leaving the first version to be found
+ and trusted.
+2. **<Thing that was built and then deliberately removed>.** What replaced it, or
+ why nothing did. Name where the deleted code can be recovered from.
+
+### How the human steered
+
+- What they were reacting to, and the redirect, quoted.
+- What they refuse outright (half-baked mechanisms, a particular register of
+ writing, a class of solution).
+- How they prefer to decide β€” from renders, from numbers, from a live click-path.
+
+### Tools and recipes
+
+The commands and fixtures that produced the work: seeder scenario, test command,
+analytics query, browser trick. Enough that the next agent reproduces the state
+instead of rebuilding it.
+
+### Traps
+
+The failures that cost time and would cost it again. One line each, cause first.
+
+### Left open
+
+- <Ticket id> β€” <what remains>
+- <Unticketed follow-up>, and why it was not done
+```
+
+## Pointer block, for leaf tickets
+
+```markdown
+---
+
+## πŸ€– AI post-context
+
+*Written by <agent> on <date>.*
+
+<One or two decisions specific to THIS ticket.>
+
+Full handover for the effort: <TICKET-ID>.
+```
+
+## What not to put in it
+
+- A changelog of the diff. The PR already has that.
+- Status updates ("in progress", "merged"). The state field has that.
+- The same essay copied onto every ticket in the project.
+- Anything confidential in a place that syncs outward: no customer names, no
+ support-ticket ids, no vendor references that the public PR rules already ban.
diff --git a/.agents/skills/linear-context-handover/scripts/lf-context.sh b/.agents/skills/linear-context-handover/scripts/lf-context.sh
new file mode 100755
index 0000000000..c2914af987
--- /dev/null
+++ b/.agents/skills/linear-context-handover/scripts/lf-context.sh
@@ -0,0 +1,393 @@
+#!/usr/bin/env bash
+#
+# lf-context.sh β€” walk the context chain behind a piece of Langfuse work and
+# print one readable brief.
+#
+# file / sha -> commits -> PRs (squash subject "(#N)" or the commits API)
+# -> branch names -> Linear ticket ids
+# -> ticket, parent, subtickets, relations, project, AI handover
+#
+# Shipped with the `linear-context-handover` skill, which is the reading and
+# writing practice around it; the planning practice is `linear-planning`.
+# Provenance: LFE-15914 ("Agentic Coding and Linear: an RFC").
+#
+# Run it from inside the checkout you are about to change, or point it at one
+# with --dir / $LANGFUSE_REPO.
+#
+# lf-context.sh web/src/features/experiments/components/table/ExperimentsTable.tsx
+# lf-context.sh 65bbc753c
+# lf-context.sh 16912
+# lf-context.sh LFE-15711
+# lf-context.sh --help
+#
+# Read-only by design: git log / gh read APIs / a Linear GraphQL query. It never
+# fetches, checks out, pushes, or mutates a ticket.
+set -uo pipefail
+
+# Which checkout to read history from, in order: --dir, $LANGFUSE_REPO, the
+# checkout you are standing in. No machine-specific default β€” this ships to
+# every engineer through the plugin.
+APP_DEFAULT="${LANGFUSE_REPO:-$(git rev-parse --show-toplevel 2>/dev/null)}"
+REPO_DEFAULT="${LANGFUSE_GH_REPO:-langfuse/langfuse}"
+SLUG="${LINEAR_WORKSPACE:-clickhouse}"
+KEYS="${LINEAR_KEYS:-lfe,lf}"
+
+KIND=""
+TARGET=""
+REV=""
+DIR=""
+REPO=""
+LIMIT=10
+ONLINE=1
+
+usage() {
+ cat <<'EOF'
+lf-context.sh β€” reconstruct the context behind Langfuse code, from git to Linear.
+
+USAGE
+ lf-context.sh <target> [options]
+
+ <target> is auto-detected:
+ a path web/src/features/experiments/.../ExperimentsTable.tsx (or an absolute path)
+ a sha 65bbc753c (7-40 hex chars, or anything git can rev-parse)
+ a PR 16912 / #16912 (all digits, <= 6)
+ a ticket LFE-15711 (<KEY>-<number>)
+
+OPTIONS
+ --path P | --sha S | --pr N | --ticket ID skip auto-detection
+ --dir PATH git checkout to read history from (default: $LANGFUSE_REPO, or
+ the checkout the current directory is in)
+ --repo O/R GitHub repo for gh calls (default: langfuse/langfuse, or the
+ checkout's origin)
+ --rev REF revision to walk for a path (default: HEAD, or origin/<default>
+ when HEAD is behind it β€” a stale checkout otherwise hides the
+ newest PRs)
+ --limit N how many commits / PRs to follow (default 10)
+ --offline git only: no gh, no Linear
+ -h, --help
+
+WHAT IS AUTOMATIC AND WHAT NEEDS AN AGENT
+ Automatic (git): commits for a path, the commit itself, branches containing a
+ sha, PR numbers from squash-merge subjects "(#N)".
+ Automatic (gh): PR state / title / head+base branch / url / body, PRs
+ associated with a sha, the PRs whose branch carries a ticket
+ id. Needs `gh auth status` to be healthy.
+ Automatic here: ticket ids, from branch names first (PR descriptions in these
+ repos deliberately omit ticket ids, so the branch is the
+ link), then from commit subjects and PR text as a fallback.
+ NEEDS AN AGENT: everything inside Linear β€” ticket title, status, project,
+ parent, subtickets, relations, and the "AI post-context"
+ handover block in the description. A shell has no Linear MCP.
+ If LINEAR_API_KEY (or LINEAR_TOKEN / LINEAR_API_TOKEN) is
+ exported this script queries the Linear API directly;
+ otherwise it prints the exact ticket ids, URLs and MCP calls
+ for an agent to run. There is no token on this machine today,
+ so the agent hand-off is the normal path.
+
+EXIT CODES
+ 0 something was resolved Β· 1 nothing resolved Β· 2 bad usage
+EOF
+}
+
+die() { printf 'lf-context: %s\n' "$1" >&2; exit "${2:-2}"; }
+hdr() { printf '\n\033[1m%s\033[0m\n' "$*"; }
+note() { printf ' %s\n' "$*"; }
+
+# --- args ---------------------------------------------------------------------
+[ $# -eq 0 ] && { usage; exit 2; }
+while [ $# -gt 0 ]; do
+ case "$1" in
+ -h|--help) usage; exit 0 ;;
+ --path) KIND=path; TARGET="$2"; shift 2 ;;
+ --sha) KIND=sha; TARGET="$2"; shift 2 ;;
+ --pr) KIND=pr; TARGET="$2"; shift 2 ;;
+ --ticket) KIND=ticket; TARGET="$2"; shift 2 ;;
+ --dir) DIR="$2"; shift 2 ;;
+ --repo) REPO="$2"; shift 2 ;;
+ --rev) REV="$2"; shift 2 ;;
+ --limit) LIMIT="$2"; shift 2 ;;
+ --offline) ONLINE=0; shift ;;
+ -*) die "unknown option $1" ;;
+ *) [ -n "$TARGET" ] && die "more than one target given ($TARGET, $1)"
+ TARGET="$1"; shift ;;
+ esac
+done
+[ -z "$TARGET" ] && die "no target given (try --help)"
+
+upper() { printf '%s' "$1" | tr 'a-z' 'A-Z'; }
+lower() { printf '%s' "$1" | tr 'A-Z' 'a-z'; }
+
+# keys longest-first so `lfe-1` never matches as `lf`
+KEYS_RE=$(printf '%s' "$KEYS" | tr ',' '\n' | awk '{print length, $0}' | sort -rn |
+ awk '{print $2}' | paste -sd'|' -)
+[ -z "$KEYS_RE" ] && KEYS_RE='lfe|lf'
+
+# --- detect the target kind ---------------------------------------------------
+if [ -z "$KIND" ]; then
+ T_LOWER=$(lower "$TARGET")
+ case "$T_LOWER" in
+ '#'*) KIND=pr; TARGET="${TARGET#\#}" ;;
+ esac
+ if [ -z "$KIND" ]; then
+ if printf '%s' "$T_LOWER" | grep -qE "^($KEYS_RE|[a-z]{2,5})-[0-9]{1,6}$" && [ ! -e "$TARGET" ]; then
+ KIND=ticket
+ elif printf '%s' "$TARGET" | grep -qE '^[0-9]{1,6}$'; then
+ KIND=pr
+ elif [ -e "$TARGET" ] || printf '%s' "$TARGET" | grep -q '[/.]'; then
+ KIND=path
+ elif printf '%s' "$T_LOWER" | grep -qE '^[0-9a-f]{7,40}$'; then
+ KIND=sha
+ else
+ KIND=sha # let git decide (tags, HEAD~3, …)
+ fi
+ fi
+fi
+
+# --- locate the checkout ------------------------------------------------------
+REL=""
+if [ "$KIND" = path ]; then
+ if [ -e "$TARGET" ]; then
+ ABS=$(cd "$(dirname "$TARGET")" 2>/dev/null && pwd)/$(basename "$TARGET")
+ DIR=${DIR:-$(git -C "$(dirname "$ABS")" rev-parse --show-toplevel 2>/dev/null)}
+ [ -z "$DIR" ] && die "$TARGET is not inside a git repo" 1
+ REL=${ABS#"$DIR"/}
+ else
+ DIR=${DIR:-$APP_DEFAULT}
+ REL=$TARGET
+ case "$REL" in "$DIR"/*) REL=${REL#"$DIR"/} ;; esac
+ fi
+else
+ DIR=${DIR:-$APP_DEFAULT}
+fi
+if [ -z "$DIR" ]; then
+ die "no checkout to read: run this from inside the repo, or pass --dir PATH, or export LANGFUSE_REPO" 1
+fi
+[ -d "$DIR/.git" ] || [ -f "$DIR/.git" ] || die "not a git checkout: $DIR" 1
+TOP=$(git -C "$DIR" rev-parse --show-toplevel 2>/dev/null) || die "not a git checkout: $DIR" 1
+DIR=$TOP
+
+if [ -z "$REPO" ]; then
+ ORIGIN=$(git -C "$DIR" remote get-url origin 2>/dev/null)
+ REPO=$(printf '%s' "$ORIGIN" | sed -e 's#^[email protected]:##' -e 's#^https://github.com/##' -e 's#\.git$##')
+ [ -z "$REPO" ] && REPO=$REPO_DEFAULT
+fi
+
+# --- pick the revision to walk ------------------------------------------------
+if [ -z "$REV" ]; then
+ REV=HEAD
+ DEF=$(git -C "$DIR" symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null)
+ [ -z "$DEF" ] && DEF=origin/main
+ if git -C "$DIR" rev-parse --verify --quiet "$DEF" >/dev/null 2>&1 &&
+ git -C "$DIR" merge-base --is-ancestor HEAD "$DEF" 2>/dev/null &&
+ ! git -C "$DIR" merge-base --is-ancestor "$DEF" HEAD 2>/dev/null; then
+ REV=$DEF
+ REV_NOTE="(HEAD is behind $DEF β€” walking $DEF so recent PRs are visible)"
+ fi
+fi
+
+HAVE_GH=0
+if [ "$ONLINE" -eq 1 ] && command -v gh >/dev/null 2>&1; then HAVE_GH=1; fi
+
+TMP=$(mktemp -d "${TMPDIR:-/tmp}/lf-context.XXXXXX") || die "cannot mktemp" 1
+trap 'rm -rf "$TMP"' EXIT
+: >"$TMP/prs" # one PR number per line
+: >"$TMP/tickets" # "TICKET<TAB>source" per line
+: >"$TMP/shas"
+
+add_tickets() { # $1 text, $2 source label
+ printf '%s\n' "$1" | grep -oiE "($KEYS_RE)-[0-9]{1,6}" | while read -r m; do
+ printf '%s\t%s\n' "$(upper "$m")" "$2" >>"$TMP/tickets"
+ done
+}
+
+printf '\033[1mlf-context\033[0m %s: %s\n' "$KIND" "$TARGET"
+printf ' repo %s Β· checkout %s\n' "$REPO" "$DIR"
+[ "$KIND" = path ] && printf ' rev %s %s\n' "$REV" "${REV_NOTE:-}"
+[ "$HAVE_GH" -eq 0 ] && printf ' (offline: no gh β€” git-only resolution)\n'
+
+# --- step 1: the git side -----------------------------------------------------
+case "$KIND" in
+ path)
+ LOG=$(git -C "$DIR" log --follow --date=short --format='%h|%ad|%an|%s' -n "$LIMIT" "$REV" -- "$REL" 2>/dev/null)
+ if [ -z "$LOG" ]; then
+ hdr "commits"
+ note "no commits touch '$REL' in $REV."
+ note "checks: is the path spelled right? is it new/untracked? deleted upstream?"
+ note "try: another --rev (a feature branch, origin/main), or --dir <the worktree that has it>"
+ note " git -C $DIR log --all --oneline -- '*$(basename "$REL")'"
+ exit 1
+ fi
+ hdr "commits touching $REL (newest $LIMIT of $(git -C "$DIR" rev-list --count "$REV" -- "$REL" 2>/dev/null))"
+ printf '%s\n' "$LOG" | while IFS='|' read -r sh dt an su; do
+ printf ' %s %s %-18s %s\n' "$sh" "$dt" "$(printf '%.18s' "$an")" "$su"
+ done
+ printf '%s\n' "$LOG" | cut -d'|' -f1 >"$TMP/shas"
+ printf '%s\n' "$LOG" | cut -d'|' -f4 | while read -r su; do
+ printf '%s\n' "$su" | grep -oE '\(#[0-9]+\)' | tr -d '(#)' >>"$TMP/prs"
+ add_tickets "$su" "commit subject"
+ done
+ ;;
+ sha)
+ FULL=$(git -C "$DIR" rev-parse --verify --quiet "${TARGET}^{commit}" 2>/dev/null)
+ [ -z "$FULL" ] && die "git cannot resolve '$TARGET' in $DIR (wrong checkout? unfetched branch?)" 1
+ hdr "commit"
+ git -C "$DIR" log -1 --date=short --format=' %h %ad %an%n %s%n' "$FULL" | sed 's/^/ /'
+ printf '%s\n' "$FULL" >"$TMP/shas"
+ SUB=$(git -C "$DIR" log -1 --format='%s%n%b' "$FULL")
+ printf '%s\n' "$SUB" | grep -oE '\(#[0-9]+\)' | tr -d '(#)' >>"$TMP/prs"
+ add_tickets "$SUB" "commit message"
+ BRANCHES=$(git -C "$DIR" branch -a --contains "$FULL" --format='%(refname:short)' 2>/dev/null |
+ grep -v '^origin/HEAD' | head -12)
+ hdr "branches containing it"
+ if [ -z "$BRANCHES" ]; then
+ note "none β€” the commit is unreferenced locally (rewritten, or on a branch this checkout never fetched)"
+ else
+ printf '%s\n' "$BRANCHES" | while read -r b; do note "$b"; done
+ add_tickets "$BRANCHES" "branch containing the sha"
+ fi
+ ;;
+ pr)
+ printf '%s\n' "$TARGET" >"$TMP/prs"
+ ;;
+ ticket)
+ TICKET=$(upper "$TARGET")
+ printf '%s\t%s\n' "$TICKET" "given" >>"$TMP/tickets"
+ hdr "branches for $TICKET"
+ LOCAL=$(git -C "$DIR" branch -a --format='%(refname:short)' 2>/dev/null |
+ grep -i -- "$(lower "$TICKET")" | head -20)
+ if [ -n "$LOCAL" ]; then printf '%s\n' "$LOCAL" | while read -r b; do note "$b"; done
+ else note "none in this checkout (may exist only on the remote, or be deleted after merge)"; fi
+ if [ "$HAVE_GH" -eq 1 ]; then
+ # GitHub search cannot query branch names, so scan the recent PR list and
+ # match the identifier against head branches (the reliable link) + text.
+ gh pr list --repo "$REPO" --state all --limit 300 \
+ --json number,headRefName,title,body \
+ --jq ".[] | select(((.headRefName + \" \" + .title + \" \" + (.body//\"\")) | ascii_downcase) | contains(\"$(lower "$TICKET")\")) | .number" \
+ 2>/dev/null >>"$TMP/prs"
+ fi
+ ;;
+esac
+
+# sha -> PR via the commits API, for anything the squash subject did not name
+if [ "$HAVE_GH" -eq 1 ] && [ -s "$TMP/shas" ] && [ ! -s "$TMP/prs" ]; then
+ while read -r sh; do
+ [ -z "$sh" ] && continue
+ gh api "repos/$REPO/commits/$sh/pulls" --jq '.[].number' 2>/dev/null >>"$TMP/prs"
+ done <"$TMP/shas"
+fi
+
+PRS=$(sort -un "$TMP/prs" | head -"$LIMIT")
+
+# --- step 2: the PR side ------------------------------------------------------
+hdr "pull requests"
+if [ -z "$PRS" ]; then
+ note "none resolved."
+ [ "$HAVE_GH" -eq 0 ] && note "gh is unavailable β€” squash subjects '(#N)' were the only source."
+ [ "$HAVE_GH" -eq 1 ] && note "the commits are probably pre-squash history, or never opened a PR."
+else
+ if [ "$HAVE_GH" -eq 0 ]; then
+ printf '%s\n' "$PRS" | while read -r n; do note "#$n (gh unavailable β€” no detail)"; done
+ else
+ for n in $PRS; do
+ J=$(gh pr view "$n" --repo "$REPO" \
+ --json number,state,title,headRefName,baseRefName,url,body,mergedAt 2>/dev/null)
+ if [ -z "$J" ]; then note "#$n (gh could not read it β€” auth? wrong repo?)"; continue; fi
+ printf '%s' "$J" | jq -r '" #\(.number) \(.state + " "|.[0:7]) \(.headRefName) β†’ \(.baseRefName)\n \(.title)\n \(.url)"'
+ BR=$(printf '%s' "$J" | jq -r '.headRefName')
+ add_tickets "$BR" "branch of #$n"
+ TXT=$(printf '%s' "$J" | jq -r '.title + "\n" + (.body//"")')
+ add_tickets "$TXT" "text of #$n"
+ if printf '%s' "$TXT" | grep -qiE 'AI post-context|πŸ€– AI'; then
+ note " ^ this PR body carries an AI handover block"
+ fi
+ done
+ fi
+fi
+
+# --- step 3: ticket ids -------------------------------------------------------
+hdr "linear tickets"
+IDS=$(cut -f1 "$TMP/tickets" | sort -u)
+if [ -z "$IDS" ]; then
+ note "no ticket id found."
+ note "branch names are the link here (PR descriptions deliberately omit ids),"
+ note "so a branch like 'chore/bump-deps' genuinely has no ticket β€” that is not an error."
+ note "keys searched: $KEYS_RE (override with LINEAR_KEYS=lfe,lf,ch)"
+else
+ for id in $IDS; do
+ SRC=$(grep "^$id " "$TMP/tickets" | cut -f2 | sort -u | tr '\n' '|' | sed -e 's/|$//' -e 's/|/, /g')
+ printf ' %-12s https://linear.app/%s/issue/%s\n' "$id" "$SLUG" "$id"
+ printf ' %-12s via %s\n' "" "$SRC"
+ done
+fi
+
+# --- step 4: Linear itself ----------------------------------------------------
+TOKEN="${LINEAR_API_KEY:-${LINEAR_TOKEN:-${LINEAR_API_TOKEN:-}}}"
+# Personal API keys go in the header raw; OAuth access tokens need "Bearer".
+case "$TOKEN" in
+ ""|"Bearer "*|lin_api_*) AUTH="$TOKEN" ;;
+ *) AUTH="Bearer $TOKEN" ;;
+esac
+
+linear_fetch() { # $1 ticket id
+ local q body
+ q='query($id:String!){issue(id:$id){identifier title url state{name} project{name url}
+ labels(first:20){nodes{name}}
+ parent{identifier title url state{name}}
+ children(first:50){nodes{identifier title url state{name}}}
+ relations(first:30){nodes{type relatedIssue{identifier title url}}}
+ description}}'
+ body=$(jq -nc --arg q "$q" --arg id "$1" '{query:$q,variables:{id:$id}}')
+ curl -sS -X POST https://api.linear.app/graphql \
+ -H "Authorization: $AUTH" -H 'Content-Type: application/json' \
+ -d "$body" 2>/dev/null
+}
+
+if [ -z "$IDS" ]; then
+ :
+elif [ -n "$TOKEN" ] && [ "$ONLINE" -eq 1 ]; then
+ for id in $IDS; do
+ R=$(linear_fetch "$id")
+ ERR=$(printf '%s' "$R" | jq -r '(.errors[0].message // empty)' 2>/dev/null)
+ if [ -n "$ERR" ] || [ -z "$R" ]; then
+ hdr "$id β€” Linear API said no"
+ note "${ERR:-empty response}"
+ note "fall back to an agent: get_issue(id: \"$id\", includeRelations: true)"
+ continue
+ fi
+ hdr "$id β€” from the Linear API"
+ printf '%s' "$R" | jq -r '
+ .data.issue as $i |
+ " \($i.identifier) [\($i.state.name)] \($i.title)",
+ " \($i.url)",
+ (if $i.project then " project: \($i.project.name) \($i.project.url)" else " project: β€”" end),
+ (if ($i.labels.nodes|length)>0 then " labels: " + ([$i.labels.nodes[].name]|join(", ")) else empty end),
+ (if $i.parent then " parent: \($i.parent.identifier) [\($i.parent.state.name)] \($i.parent.title)" else empty end),
+ (if ($i.children.nodes|length)>0 then " subtickets:" , ($i.children.nodes[] | " \(.identifier) [\(.state.name)] \(.title)") else empty end),
+ (if ($i.relations.nodes|length)>0 then " relations:" , ($i.relations.nodes[] | " \(.type) \(.relatedIssue.identifier) \(.relatedIssue.title)") else empty end)
+ '
+ DESC=$(printf '%s' "$R" | jq -r '.data.issue.description // ""')
+ if printf '%s' "$DESC" | grep -qiE 'AI post-context|πŸ€– AI'; then
+ printf ' \033[1mAI handover block:\033[0m\n'
+ printf '%s\n' "$DESC" | sed -n '/AI post-context/,$p' | head -60 | sed 's/^/ /'
+ else
+ note "no AI handover block in the description"
+ fi
+ done
+else
+ hdr "linear β€” needs an agent (no LINEAR_API_KEY in this shell)"
+ note "the ids and URLs above are resolved; the ticket bodies are not. Run, per ticket:"
+ for id in $IDS; do
+ note " get_issue(id: \"$id\", includeRelations: true) # title, status, project, parent, description"
+ note " list_issues(parentId: \"$id\") # the subtickets = the PR stack"
+ done
+ note " list_issues(label: \"AI edited\", project: \"<the project above>\") # where prior agent reasoning lives"
+ note ""
+ note "then read each description's 'πŸ€– AI post-context' block before designing anything:"
+ note "a reversal already litigated once does not need re-litigating."
+ note "practice: the linear-context-handover skill (reconstruct + handover),"
+ note " the linear-planning skill (slicing a feature into a PR stack)."
+fi
+
+printf '\n'
+[ -n "$IDS" ] || [ -n "$PRS" ] || exit 1
+exit 0
diff --git a/.agents/skills/linear-planning/SKILL.md b/.agents/skills/linear-planning/SKILL.md
new file mode 100644
index 0000000000..9aaf815715
--- /dev/null
+++ b/.agents/skills/linear-planning/SKILL.md
@@ -0,0 +1,117 @@
+---
+name: linear-planning
+description: |
+ Plan a feature in Linear as subtickets that map 1:1 to a chained PR stack,
+ with enough context in each ticket that an agent could implement it from the
+ ticket alone. Use before writing code for anything bigger than a one-commit
+ fix β€” "plan this feature", "split this branch into reviewable PRs", "turn this
+ RFC into tickets", "open a PR stack".
+---
+
+# Planning a feature as Linear subtickets
+
+**One idea:** the planning session is where the expensive thinking happens, and
+it evaporates when the session ends. Write it into subtickets *while* you plan,
+one subticket per PR you intend to open, so the implementation can be handed to
+any agent β€” a cloud agent, a colleague, a session next month β€” and nothing is
+lost.
+
+This skill owns the Linear half: whether to plan at all, and what a subticket
+must contain. It does not own the PR mechanics.
+
+- **Where to cut the slices, the stack rules, and how to verify each branch** are
+ [`pr-stack-workflow`](../pr-stack-workflow/SKILL.md). Read it for the slicing;
+ this file does not restate it.
+- **What an agent may write to Linear and how it must be marked** is
+ [`linear-agent-writes`](../linear-agent-writes/SKILL.md). Read it before your
+ first write.
+- **Reconstructing history before you plan, and the handover after you ship**,
+ are [`linear-context-handover`](../linear-context-handover/SKILL.md).
+
+## Step 0 β€” reconstruct before you slice
+
+Run the context CLI on the files you are about to change, then read what it finds:
+[`linear-context-handover`](../linear-context-handover/SKILL.md) β†’ *reconstruct
+its history*. Half the design questions have already been answered somewhere in
+that chain, and a decision that was already reversed once does not need
+proposing again.
+
+## Does it need a plan at all?
+
+The discriminator is in [`pr-stack-workflow`](../pr-stack-workflow/SKILL.md) β†’
+*Decide whether it needs a stack*:
+one sentence without an "and", a default or persisted shape that needs a
+migration decision, a shared component, a click-path verification. Use that
+table; it is the same question.
+
+Two consequences for the tracker specifically:
+
+- **If the fix is one commit, the ticket already is the plan.** Do not manufacture
+ subtickets for it. Hand the ticket to an agent as the whole brief.
+- **If you cannot yet write the acceptance check, you are researching, not
+ planning.** Do the research and put *it* on the parent ticket β€” the numbers, the
+ screenshots, an attached `.md`. The plan is the second document, not the first.
+
+## One subticket per slice, created up front
+
+Create the whole set before any branch exists, so the plan is reviewable as a
+plan. Each is a **subticket of the existing ticket**, which needs no permission.
+If the work has no parent ticket yet, that parent is a top-level ticket β€” show it
+and get a yes before filing it, then plan underneath it.
+
+The worked example is the experiments-UI rebuild: 54 commits on one branch became
+eight subtickets under LFE-15711 and eight chained PRs (#16912–#16919), one to
+one, in landing order. PR #1 merged while #2–#8 were still in review, which is the
+whole point of planning it as a stack rather than discovering the split at review
+time.
+
+## What a subticket must contain
+
+The bar is not "a human can follow this". It is: **hand it to an agent with no
+session history and it can implement it.** Six fields, every time β€” paste-ready
+shape in [`references/subticket-template.md`](references/subticket-template.md):
+
+1. **The change**, in one imperative sentence. "Show the 24 populated score
+ columns by default." If it needs an "and", it is two subtickets.
+2. **The evidence that justifies it** β€” the number, the quote, the screenshot.
+ `98% of column-picker use on this table ends with a score column added (440 of
+ 449 users, 90d)`. Without this, review re-litigates the design.
+3. **Entry-point files** β€” two to five paths, with the line where the behavior
+ lives, and the mechanism if it is not obvious from the file.
+4. **The acceptance check** β€” a click path with a URL and an observable outcome,
+ plus the seeded data it needs. *Expect 24 score columns, all populated, 0
+ blank*, not "looks better".
+5. **Position in the stack** β€” `4/8, branches off #16914, base retargets to main
+ when #16914 lands`.
+6. **Deliberately not in scope**, with where it went instead. This is the field
+ that stops an implementer helpfully widening the slice and breaking the union
+ check.
+
+An empty field is usually a sign the slice is not understood yet, not a sign the
+field is optional. *Not in scope* is the exception β€” it is empty only when nothing
+was tempting.
+
+## Labels and boundaries
+
+Planning this way uses two of the three permitted write shapes: creating
+subtickets, and writing into descriptions. **The policy is not restated here** β€”
+[`linear-agent-writes`](../linear-agent-writes/SKILL.md) is the authority for
+which shapes are allowed, which label stamps each, and what still belongs to a
+human.
+
+The two rules you will hit immediately while planning:
+
+- **Subtickets are free; the top of the tree needs a yes.** Planning under an
+ existing ticket needs no permission. Creating the parent itself does.
+- **Stamp every shape you used.** A subticket you created *and* wrote the plan
+ into carries both `AI created` and `AI edited`.
+
+Estimates, priorities, assignees and cycle stay unset. Suggest them in your reply
+instead.
+
+## When the stack lands
+
+Wrap up with [`linear-context-handover`](../linear-context-handover/SKILL.md): the
+substantial handover on the parent, short pointers on the leaves, `AI edited` on
+each. The parent's subticket list plus those blocks are exactly what the context
+CLI hands the next agent.
diff --git a/.agents/skills/linear-planning/agents/openai.yaml b/.agents/skills/linear-planning/agents/openai.yaml
new file mode 100644
index 0000000000..d293db5e90
--- /dev/null
+++ b/.agents/skills/linear-planning/agents/openai.yaml
@@ -0,0 +1,4 @@
+interface:
+ display_name: "Linear Planning"
+ short_description: "Plan a feature as subtickets mapped to a PR stack"
+ default_prompt: "Use $linear-planning to turn a feature into Linear subtickets that map one-to-one onto a chained PR stack, each carrying enough context to be implemented from the ticket alone."
diff --git a/.agents/skills/linear-planning/references/subticket-template.md b/.agents/skills/linear-planning/references/subticket-template.md
new file mode 100644
index 0000000000..736a2f6305
--- /dev/null
+++ b/.agents/skills/linear-planning/references/subticket-template.md
@@ -0,0 +1,77 @@
+# Planning subticket template
+
+One subticket per PR in the intended stack, created as a **child of the existing
+ticket** β€” which needs no permission β€” and labelled `AI created`. Filing the
+parent itself is a top-level ticket and needs a yes first.
+
+The bar is not "a human can follow this". It is: **an agent with no session
+history can implement it from the ticket alone.** If a field would be empty, that
+is usually a sign the slice is not understood yet β€” not a sign the field is
+optional. The exception is *Not in scope*, which is empty only when nothing was
+tempting.
+
+Title: imperative, names the surface, no ticket-speak.
+`Show the populated score columns by default on the experiments list`
+
+```markdown
+*Created by <agent> on <date> while planning <PARENT-ID>, for whoever implements
+slice N of the stack. Everything here is agent-written.*
+
+## The change
+
+<One imperative sentence. If it needs an "and", it is two subtickets.>
+
+## Why β€” the evidence
+
+<The number, the quote, or the screenshot that justifies it. Name the source and
+the window: "440 of 449 users (98%), 90 days, users not pageviews". A design
+opinion with no evidence line is fine β€” say so explicitly, so review argues about
+the right thing.>
+
+## Where it lives
+
+- `web/src/.../ThisFile.tsx:757` β€” <what is there today>
+- `packages/shared/src/.../thatQuery.ts` β€” <the projection that has to change>
+
+<2–5 entry points. Not a file list of the diff β€” the places an implementer starts
+reading. Include the mechanism if it is not obvious from the file:
+"both families are discovered with the same filter, so each level produces an
+always-empty twin".>
+
+## Acceptance check
+
+1. `http://localhost:3025/project/<id>/experiments`
+2. <click path>
+3. Expect: <observable outcome with a number β€” "24 score columns, all populated,
+ 0 blank" β€” not "looks better">
+
+<Plus the seeded data or scenario the check needs, and the command that produces
+it.>
+
+## Position in the stack
+
+`N/M` Β· branches off #<parent PR> Β· base retargets to `main` when that lands Β·
+must pass the repo's verification bar on its own branch, not only on the stack
+tip.
+
+## Not in scope
+
+- <The tempting adjacent change> β€” stays in <TICKET-ID> / on the parent, because
+ <reason>.
+```
+
+## After the PR merges
+
+Do not rewrite this block. Append the leaf handover pointer below it and add
+`AI edited` alongside `AI created` β€” see
+[`linear-context-handover`](../../linear-context-handover/references/handover-template.md).
+
+## What not to put in a planning subticket
+
+- The whole design doc. Link the parent, or attach an `.md`; eight copies of one
+ essay is noise.
+- A status narrative ("first we tried X"). That belongs in the handover, after.
+- Estimates, priorities, assignees, cycle β€” human-only fields. Leave them unset
+ and mention the suggestion in chat.
+- Anything confidential: no customer names, no support-ticket ids, no vendor
+ references. Same rule as the public PR artifacts.
diff --git a/.agents/skills/skill-creator/SKILL.md b/.agents/skills/skill-creator/SKILL.md
index fb453a41fc..0babbe54dc 100644
--- a/.agents/skills/skill-creator/SKILL.md
+++ b/.agents/skills/skill-creator/SKILL.md
@@ -45,23 +45,43 @@ Match the level of specificity to the task's fragility and variability:
Think of Codex as exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom).
-### Require Human Review for Ticket Writes
-
-For skills that create Linear tickets, update Linear tickets, or add evidence to
-existing tickets, require human review before any write. The skill must present
-all findings in a table, ask the human which findings to create or update in
-Linear, and wait for an explicit selection before making changes.
-
-Use this table structure unless the domain needs additional columns:
-
-| ID | Finding | Evidence | Impact / Scope | Existing Ticket Match | Proposed Linear Action | Confidence | Human Decision |
-| --- | --- | --- | --- | --- | --- | --- | --- |
-| F1 | Concise symptom or bug claim | Measured counts, deltas, links, traces, logs, or "No measurements found" | Affected env, service, route, customer segment, or blast radius supported by evidence | Existing issue key/link, duplicate candidate, or "None found" | Create new ticket, add evidence comment, update status/labels, or no action | High/medium/low plus one short reason | Leave blank for the human to choose |
-
-In the skill instructions, state that Codex must not create tickets, comment on
-tickets, edit ticket fields, or add evidence until the human chooses one or more
-row IDs and actions. If the human asks for an automated sweep, still pause at
-this review table before writing to Linear.
+### Mark Ticket Writes Instead of Gating Them
+
+Skills that write to the issue tracker do not need a human review gate first.
+The guardrail is **marking plus a bounded set of shapes**: three permitted write
+shapes, each stamped with a label and marked as agent-written in the text.
+
+The full policy is [`linear-agent-writes`](../linear-agent-writes/SKILL.md),
+which is the **single authority**.
+Do not restate its rules in a new skill β€” point at it, so there is one text to
+keep correct. In summary, a skill may:
+
+1. **Comment**, only when a human must be told something now.
+2. **Edit a description**, adding a clearly separated agent block that never
+ rewrites the human's prose. This is where durable context belongs.
+3. **Create a ticket** β€” a subticket of an existing ticket needs no permission; a
+ ticket with no parent needs the human's yes first, and then the skill files it
+ itself.
+
+Assigning, moving state, closing, estimating, re-prioritising, deleting,
+projects, and new labels still belong to a human. A skill that wants one of those
+must surface it as a suggestion in its output.
+
+Two consequences worth designing for:
+
+- **A finding with no parent ticket is the one write that asks first.** Design a
+ skill that reviews a whole queue to present its filings as a table and take
+ **one** go-ahead for the set β€” or for named rows β€” then file them and report
+ what it filed. Asking per ticket, or handing back text for someone to paste, is
+ the cost this policy exists to remove.
+- **State that the write happened.** Because the tracker's API authenticates as
+ the human who configured it, an unmarked agent write is indistinguishable from
+ something that person typed. Require the skill to mark authorship in the text,
+ not only with the label.
+
+If the tracker is not reachable in the environment, the skill must **say so and
+return the content it would have written**, ready to paste. It must not skip the
+step silently.
### Protect Validation Integrity
diff --git a/.agents/skills/weekly-production-review/SKILL.md b/.agents/skills/weekly-production-review/SKILL.md
index 030aec1b12..a127282360 100644
--- a/.agents/skills/weekly-production-review/SKILL.md
+++ b/.agents/skills/weekly-production-review/SKILL.md
@@ -18,10 +18,15 @@ audit from the linked source rows.
timezone. State both local and UTC query windows in one short scope line.
- Cover all production environments unless the user narrows scope:
`prod-us`, `prod-eu`, `prod-hipaa`, and `prod-jp`.
-- Keep the first pass read-only. Do not create or update Linear issues,
- comments, incident.io records, follow-ups, alerts, Datadog monitors, files,
- Slack messages, or production systems unless the user explicitly asks after
- reviewing the findings.
+- The review itself changes nothing outside the tracker. Do not touch incident.io
+ records, follow-ups, alerts, monitors, files, Slack messages, or production
+ systems unless the user explicitly asks after reviewing the findings.
+- Linear is the exception: evidence may be commented onto issues that already
+ exist, labelled and marked as agent-written. A new issue has no parent, so it
+ is the one write that asks first β€” show the set, take one go-ahead, then file
+ them. [`linear-agent-writes`](../linear-agent-writes/SKILL.md) is the authority;
+ [`linear-bug-triage`](../linear-bug-triage/SKILL.md) applies it to measured
+ findings.
- For chat-only reviews, avoid creating report artifacts or local analysis
workspaces unless a required tool workflow explicitly does so or the user asks
for a file. If incident.io analysis tooling requires a local playbook
@@ -34,11 +39,12 @@ audit from the linked source rows.
- Use [`datadog-query-recipes`](../datadog-query-recipes/SKILL.md) for
production Datadog query shapes and environment/site routing.
-- Use [`linear-bug-triage`](../linear-bug-triage/SKILL.md) only after a human
- explicitly approves a Linear write-back.
+- Use [`linear-bug-triage`](../linear-bug-triage/SKILL.md) for the Linear
+ write-back: it comments measured evidence onto existing issues, and files new
+ ones once you approve the set.
- Use [`incident-alert-tickets`](../incident-alert-tickets/SKILL.md) to check
- each Datadog alert cluster against the per-monitor knowledge base and, only
- after explicit human approval, record newly root-caused clusters there.
+ each alert cluster against the per-monitor knowledge base and record newly
+ root-caused clusters there as a labelled description edit.
## Workflow