Skip to content

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

docs(agents): rank by the handbook, and stop inventing staleness (#17075)

Nikita Kabardin51e2bfe99c74
diff --git a/.agents/skills/langfuse-onboarding/SKILL.md b/.agents/skills/langfuse-onboarding/SKILL.md
index 55e2a0d6ab..7af212cdff 100644
--- a/.agents/skills/langfuse-onboarding/SKILL.md
+++ b/.agents/skills/langfuse-onboarding/SKILL.md
@@ -121,11 +121,11 @@ Start with:
| Page | What it answers |
| --- | --- |
-| `product-engineering/how-we-work/onboarding.mdx` | Day 1, Week 1, months 1–3, month 6 β€” the timeline and its outcomes |
-| `product-engineering/how-we-work/how-we-ship.mdx` | Prioritisation, specification, releases, issue states |
-| `tools-and-processes/using-linear.mdx` | How the tracker is used, and the working agreement |
-| `how-we-work/productivity-and-ai.mdx` | Agent tooling, and keeping `AGENTS.md` current |
-| `product-engineering/how-we-work/code-review.mdx` | What review is for here |
+| `content/handbook/product-engineering/how-we-work/onboarding.mdx` | Day 1, Week 1, months 1–3, month 6 β€” the timeline and its outcomes |
+| `content/handbook/product-engineering/how-we-work/how-we-ship.mdx` | Prioritisation, specification, releases, issue states |
+| `content/handbook/tools-and-processes/using-linear.mdx` | How the tracker is used, and the working agreement |
+| `content/handbook/how-we-work/productivity-and-ai.mdx` | Agent tooling, and keeping `AGENTS.md` current |
+| `content/handbook/product-engineering/how-we-work/code-review.mdx` | What review is for here |
Then, in the repos:
diff --git a/.agents/skills/linear-work-rhythm/SKILL.md b/.agents/skills/linear-work-rhythm/SKILL.md
index 0fe563a2d2..80b379ec8f 100644
--- a/.agents/skills/linear-work-rhythm/SKILL.md
+++ b/.agents/skills/linear-work-rhythm/SKILL.md
@@ -3,8 +3,8 @@ name: linear-work-rhythm
description: |
Answer "what should I do today" for a Langfuse maintainer, from the tracker
rather than from memory: which projects you lead, which owe an update before
- Monday planning, what shipped but is not finished, what is waiting on your
- decision, and what colleagues are working on that overlaps. Use on "what
+ the Monday engineering weekly, what shipped but is not finished, what waits
+ on your decision, and what colleagues are working on that overlaps. Use on "what
should I do today", "what's on my plate", "what should I work on next", "prep
my Monday update", "what did I say last week", "who else is working on this",
"who should review this", and whenever someone hands over a bare link β€” a
@@ -34,6 +34,18 @@ Read it from `origin/main` β€” `git fetch -q origin main` then
`git show origin/main:<path>` β€” because a docs checkout is usually parked on an
old branch, and quoting a stale agreement is worse than not quoting one.
+**Read these before ranking anything.** They say how the team decides what to
+work on, and this file deliberately does not restate them:
+
+| Page | What you need from it |
+| --- | --- |
+| `content/handbook/product-engineering/how-we-work/how-we-ship.mdx` | Prioritisation, the P0–P3 levels and their timelines, daily response times, the project-update rhythm |
+| `content/handbook/product-engineering/principles.mdx` | What product engineers do and explicitly do not do |
+| `content/handbook/how-we-work/ownership.mdx` | That product areas are split between engineers by direct ownership |
+| `content/handbook/tools-and-processes/using-linear.mdx` | The working agreement: primitives, project lifecycle, definition of done |
+
+If what you are about to say contradicts one of them, the handbook wins.
+
## Do not hand-maintain the responsibility zone
Derive it. What someone owns is exactly "the projects where they are lead", and
@@ -48,16 +60,48 @@ A local list of someone's projects is stale within a week β€” this repo has been
burned by exactly that. `me.md` holds only the durable half: name, role, and the
focus they described in their own words.
+## What ranking actually means here
+
+Product engineers set their own priorities. The handbook is explicit β€” *"everyone
+manages their own priorities and escalates to their lead when work piles up"* β€”
+so you are not issuing a to-do list. You are making the state of the week
+visible so somebody else can decide.
+
+**A P0 outranks everything, including this ordering.** The handbook defines it
+as drop-everything β€” a security incident, ingestion delay, the traces table not
+loading. If one exists, it is the answer and the rest of the list can wait; do
+not bury it under a blocked review.
+
+With no P0 open, rank by the handbook's own balance: *"we balance busy work with
+making progress on the most important project we're driving forward."*
+
+1. **What moves the project they are driving.** A blocked review, a decision
+ waiting on someone else, work sitting one approval away from shipping.
+2. **P1** β€” same-week by definition, so it competes with the project rather than
+ deferring behind it. Use the handbook's levels, not adjectives you invent.
+3. **Busy work, bounded.** Bug fixes and support are capped at roughly two hours
+ a day by the same page. Reviews turn around inside 24 hours. Present these as
+ the budget they are, not as the plan.
+
+**Never present admin as the work.** Drafting an update, merging `main` into a
+stale branch, clearing a queue: those are chores you can offer to take off
+someone, and offering is useful. Ranking them as what to do today is not β€” it
+reads as though you did not find the real work. If the honest answer is that
+nothing is blocked and the week is clear, say that in one line.
+
## The six checks
-Run them, then report as **a short ranked list with the reason attached**, not a
-status dump. Ranking beats completeness: the point is what to do next, and a
-40-row table answers nothing.
+### 1. Updates the engineering weekly will read
-### 1. Updates owed before Monday planning
+**Monday is the engineering weekly**, and the team reads project updates
+together in it and plans the week from them. So an update has to exist *before*
+Monday β€” written Friday or Monday morning, it does not matter which. An
+out-of-date project is a gap in that plan, which is why this is the heaviest
+recurring obligation and the easiest to miss: nothing notifies you.
-The heaviest recurring obligation and the easiest to miss, because nothing
-notifies you.
+Today's date decides how you say it. Before Monday, this is a deadline
+approaching. On Monday, it is late. Mid-week, it is a commitment nobody has
+closed out β€” see below.
```
get_status_updates(type: "project", user: "me")
@@ -69,15 +113,32 @@ say only "older than the window" β€” not how stale it is, and not what its last
"next step" was. Take the newest update per project from an unbounded query
instead, and page if you have to.
-Compare against the in-progress projects from above. Any project with no update
-since the last Monday owes one, and a project with **no update at all** is the
-worst case, not an absent row. Say how stale each is in days β€” "last update 11
-days ago" lands, "stale" does not.
+**Which projects owe one:** every in-progress project they lead whose newest
+update predates the last Monday. That is the cutoff β€” the weekly reads what is
+there, so anything that missed the previous round is still outstanding. A project
+with **no update at all** is the worst case, not an absent row.
+
+Use the cutoff to *select*, then use the framing below to *say it*. The two are
+not in tension: which projects are outstanding is a date question, and what to
+say about each one is not.
+
+**Do not report this as staleness.** "Five updates are 11 days stale" is a
+number nobody committed to and a word that means nothing β€” it sounds like a
+metric and carries no information about the work. What is real is the *last thing
+they said they would do*. Every update ends with a next step, so quote it back
+and ask about that:
+
+> On 24 Aug you said Front End Perf's next step was checking whether we should
+> use react-compiler. Did that happen, or has it been overtaken?
+
+That is a question they can answer in five seconds, and the answer *is* the new
+update. An age in days is not. If several projects are in the same position,
+give one line each in that shape β€” the commitment, then the question β€” rather
+than a list of dates.
An update carries health, progress since the last one, next step, blockers or
-decisions needed, and any target-date change. **The previous update's "next step"
-is where this week's goal already is** β€” read it before writing the new one, and
-say whether it happened. That is the whole value of the sequence.
+decisions needed, and any target-date change. The previous next step is where
+this week's goal already is, so read it before writing anything new.
### 2. Shipped but not finished
@@ -159,7 +220,10 @@ not moved, and requests routed to you as a feature owner.
### 5. Your open bugs
-A weekly look at your own bugs, to catch what is slipping.
+A weekly look at your own bugs, to catch what is slipping. **Bounded**: bug
+fixes and support are capped at roughly two hours a day, so this is a budget
+check, not a backlog to work through. If it consistently needs more than that,
+the handbook says to escalate rather than absorb it β€” say so.
```
list_issues(assignee: "me", label: "bug", state: "started")