status: draft as_of: 2026-10-10 since: 2026-10-10
Godspeed for Teams · Labelling guide (v0)
What this is. The rules for labelling the decisions in our team's work by hand, for step 0 of the Teams plan (living with the experience on hand-labelled data). Two readers use it: the model that drafts each day's decisions, which follows it as its instructions, and the people who review those drafts. When the two disagree with this page, this page wins; when this page is wrong, it changes, with a dated line under "Changes".
Provisional. v0 is written before anyone has labelled a day. Wilfried labels alone first; when Dominique and Stef join, Dominique labels about 20 of Wilfried's decisions without seeing Wilfried's labels, and every place they differ changes this guide, not just the label.
Words follow the Godspeed glossary (Linear team document): a decision, a core decision, record (proposed, confirmed, misrecorded), standing (current, superseded, reversed), an issue (never "ticket").
1. What one decision is
We label decisions, not events. A decision is one choice that settles a question and binds later work: the smallest thing someone could later want to undo, or ask "why?" about.
The stand-up test. Could you say it in one sentence at a stand-up, as "we chose X" or "we chose X instead of Y"? Then it is one decision.
It counts only if it is consequential, meaning at least one of these is true (the same test the compile uses today):
- Hard to reverse: undoing it later costs real work, money or trust.
- Binds later work: other steps now depend on it (an approach, a rule everyone follows from now on).
- An explicit trade-off: the words name what was given up ("skip the benchmark to ship today").
Not decisions: reports of state ("the tests pass", "the PR is merged"), test results, questions, explanations, plans restated, a lesson or a gotcha with no choice in it, and a choice so small nothing depends on it (a variable name, a file order). "No decision" is a normal finding: most turns, commits and comments hold none.
Events and decisions are not one to one.
- One event can hold none, one or several decisions.
- One decision can have several sources: said in a session, written in a PR, repeated in an issue comment. It is still one decision, dated at the first moment it was made.
Split or merge.
- Split when two choices could each be undone alone. "The flag is named
teams, and off by default" is two decisions. - Merge when it is the same choice said again, in the same or another source.
Aim for the stand-up sentence, not the code line. Below it (a variable name, the shape of a refactor) is noise. Above it ("we're building Teams") is a goal, not a decision. When unsure whether something is big enough, label it and mark it trivial (section 4): it stays in the log and never interrupts anyone.
2. The fields
The drafting model fills every field it can; the reviewer corrects. Fields marked code are filled from facts by our scripts and are not drafted.
| Field | What to write | Allowed values and rules | Filled by |
|---|---|---|---|
| Title | what was decided, one sentence | 8 to 20 words a bright non-engineer follows; no ids, no issue numbers, no jargon | model, then reviewer |
| Line | the headline | 3 to 10 words, sentence case | model, then reviewer |
| When | the moment it was first made | the time of the first source; never the time of a later edit | code |
| Sources | where it was made or repeated | session turn (<machine>:<session>:t<n>), PR, review, review comment, issue, issue comment or document, each by its link or id |
model; code checks each exists |
| Who decided | the person or people, and how | said it · agreed to the agent's proposal · the agent alone (section 5); plus reported when it was made elsewhere and restated (section 10) | model, then the decider |
| Level | core, or a detail | core, or detail of a named core decision (section 6) | model, then reviewer |
| Links | ties to earlier decisions | supersedes · reverses · duplicate of (section 7) | model, then reviewer |
| How much it matters | for the team as a whole | should know · good to know · trivial (section 4) | the decider (model suggests) |
| Issue | the Linear issue it belongs to | from the folder, the branch and the PR's links; empty when there is none | code; reviewer corrects |
| Files | files touched where it was made | from the session's tool facts and the PR's diff | code |
| Reasons | why, as said | short exact quotes, each with where it is (section 8); empty when no reason was said | model; code checks each quote |
| What to do instead | the allowed path, when it rules something out | one line, only if it was said; else empty | model, then reviewer |
Never guess a field. A field the sources don't give stays empty. An empty field is right; an invented one is wrong.
Not in v0 (they come with the ruler, step 1): rejected options and "until" for temporary decisions. If one is obvious in the source, put it in the reasons as a quote.
3. Who reads what
So the labels serve the screens: the title and reasons show in the Log and in "Why this?"; the line is the digest's headline when zoomed out; level folds details under their core decision; links build chains (only the head of a chain shows by default); how much it matters ranks the digest and sets which decisions may trigger an ask; what to do instead is the first action an ask offers.
4. How much it matters
For the team as a whole, not for the person who decided.
| Level | Meaning | Example from our work |
|---|---|---|
| should know | someone who missed it would likely work against it, redo it, or be surprised | Teams is merged into main; the teams-stage-1 branch is retired (7 Oct): every branch and lane changes |
| good to know | useful context; missing it costs little | the flag is named teams, with teams_why_this beside it (4 Oct) |
| trivial | a real choice, but nobody needs to hear about it | in Admin › Feature flags, the categories start closed and open on a click |
Not labelled: who should know. Which readers a decision matters to is learned from the readers themselves, through their reactions in the digest ("useful", "not for me"), starting from the decision's kind. The rewrite into each reader's language needs only the reader's own expertise, not a label on the decision.
5. Who decided
| Label | When | Example |
|---|---|---|
| said it | the person chose, ruled, ratified or rejected, in their own words | Wilfried: the question put inside a session is called "an ask", never "a question" (4 Oct) |
| agreed to the agent's proposal | the agent proposed the choice and the person said yes to it | illustration: the agent asks "batch these four issues in one PR?", the person answers "yes" |
| the agent alone | the agent chose between ways of doing the work and no person ruled on it | illustration: while fixing a test, the agent swaps the retry library and nobody comments |
- For agreed, point at both: the proposal and the yes. A short "yes", "ok", "go" is evidence; never drop it.
- An agent's choice the person later objects to is still the agent's decision, usually reversed by a person decision.
- On GitHub and Linear, who wrote the item is known from the item itself (a Co-Authored-By trailer, "Generated with", a bot account, "on behalf of"); the draft never overrules that.
6. Core decisions and details
A core decision changes what gets built, the shape of a thing, or a rule of the product or of how the team works. A detail carries a core decision out, applies it to one case, or refines it, and could be changed alone without reopening it.
Label every detail with the core decision it belongs to ("detail of …"). The digest zoomed out shows core decisions only; zooming in unfolds their details beneath them.
| Core decision | Details of it |
|---|---|
| Teams Stage 1 runs on production behind per-person flags, off by default (4 Oct) | the flag is named teams (4 Oct); flags are switched in Admin › Feature flags |
A detail whose core decision isn't in the log yet: label the core decision too, if it was made in the window; otherwise mark the detail core and add a reviewer note.
7. Links between decisions
| Link | Meaning | Example |
|---|---|---|
| supersedes | the same question, decided anew | "Teams is merged into main" (7 Oct) supersedes "all Stage 1 work lands on teams-stage-1, never main" (4 Oct) |
| reverses | it goes back on the earlier decision | illustration: "bring back local mode" after "drop local mode" |
| duplicate of | the same choice, already in the log | the PR description repeating what the session decided: merge instead, adding the source |
| detail of | see section 6 | — |
- Date order decides who replaces whom. A decision made earlier never supersedes a later one, even if it arrived later in our sources.
- Progress is not replacement. Work done on the same subject, a next step, or one case of a rule is a detail, not a supersede.
- When in doubt, no link. A missing link is fixed in a second; a wrong one changes what the log says is standing.
8. Quotes
- A reason is an exact quote from its source: the words as written, with where they are (the session turn, the PR, the comment). Our checker rejects any quote it can't find in that source, character for character after spacing.
- Keep it short: the words that carry the reason, not the paragraph around them.
- Never reconstruct a reason that wasn't said, and never quote the turns before the window as if they were new.
- Quotes stay with the decision in our team's log; transcripts themselves never leave the machine they were written on.
9. Reviewing a draft
Every draft gets exactly one outcome, plus the decider's judgement of how much it matters.
| Action | When |
|---|---|
| Accept | the draft is right |
| Fix | a field is wrong; correct it (the draft's version is kept, to measure drafts) |
| Reject | with one of the four record reasons: not a decision · not worth recording · not theirs (and whose) · bad wording beyond fixing |
| Merge | two drafts are the same choice |
| Split | one draft holds two choices that could be undone separately |
| Hand over | someone else decided it; it goes to their review |
Alongside any outcome: link or unlink, add a decision the drafts missed (it counts as a draft's miss), unsure (it goes to Dominique's pass).
Set on every accepted decision, by the decider: how much it matters.
Ten minutes a day is the aim, not a limit. Review everything, including the doubtful drafts: rescuing a real decision the model doubted is part of the job. The time it took is recorded; a day that runs longer is a finding about the drafts or the tool, raised at the Friday review.
10. Hard cases
- The agent proposes, the person says "ok". Agreed to the agent's proposal. Quote the proposal and the yes.
- A decision made and undone in the same session. Two decisions: the second reverses the first. Both stay; the log shows only the head.
- An issue description that states a plan, or even a decision. Never the origin (the spec's decision 14): the decision is labelled where it was made or restated, in a session or a comment, and the description can be added as a second source.
- A review comment that changes a PR. The reviewer's decision if the comment rules ("use the existing queue instead"); the author's if they chose among the reviewer's options.
- Merging a PR. Not a decision in itself; the choices inside the PR are.
- A lesson learned. Not a decision; the rule drawn from it often is ("read the
production database with
mode=ro" after learning thatimmutable=1hides recent writes). - The same decision in a session, the PR and an issue comment. One decision, three sources, dated at the session.
- A decision made on a branch that was never merged (the work was abandoned, or is still open). Label it like any other. Its standing doesn't change because the branch wasn't merged; if the abandonment was itself a choice ("drop this approach"), label that as a second decision that reverses or supersedes the first. Note "not merged" on it, so the log can show it apart.
- A plan stated in the future ("we'll switch the flag on Friday", "from next week, lanes push one at a time"). It is a decision if the choice is made now: when is the moment it was said, not the future date; the future date goes in the title or line. A deadline is not the end of the decision.
- A decision made elsewhere and restated in a session ("Dom and I agreed to drop
X", "we decided on the call to …"). Decisions made between people, on a call or in a
message, mostly reach our sources this way: restated to an agent to do the work or to
file it in Linear. Label it as a decision, marked reported:
- who decided names everyone the words name ("Dom and I" is two people), with said it; when the words name no one else, the person restating it;
- when is the time stated ("on Tuesday's call"), else the restatement's time, marked as reported, so the date reads "by then", not "at that moment";
- the issue the agent files from it is a second source of the same decision, not a new one.
11. Sources, and how they shape the labels
Our working assumption (Wilfried, 2026-10-10): good product teams of every field work with coding agents like Claude Code, and use Linear as a to-do list. Decisions made elsewhere, on a call or in a message, are restated in a session to do the work or to file it in Linear. So sessions are the main source for every role; Linear and GitHub mostly confirm, date and link.
What step 0 reads
| Source, and the part of it | Can a decision start here? | Used for |
|---|---|---|
| Session: the person's answers to the agent's questions (options offered, one picked) | yes, the strongest | the decision, who decided, reasons |
| Session: the person's directing turns ("use X instead", "let's go with", "don't do Y"), read with the agent turn before and after | yes | the decision, who decided, reasons |
| Session: the agent's turns ("I'll use X because Y") | yes, for decisions the agent made alone; filter hard | agent decisions, reasons |
| Subagent transcripts, tied to the session that started them | yes, for decisions a subagent made alone (they hold no person turn); recorded as a subagent's, but shown to people as coming from the session, like the main agent's | agent decisions, reasons |
| GitHub: review threads that change a PR (requested changes and the author's reply) | yes | the decision, reasons, the options turned down |
| Linear: comments that conclude a discussion; documents with a stated decision | yes | the decision, reasons |
| GitHub: PR descriptions | only when a person wrote an explicit choice with its reason | a second source: dating, linking, wording |
| Linear: issue descriptions | no: never compiled (the spec's decision 14); a decision written there is caught where it was made or restated | the issue's context, linking, a second source |
| Facts: tool calls (files, commands, ids returned), commit messages and trailers, PR and issue metadata (author, branch, merge time, assignee) | no | filled by code: when, files, issue, agent marks |
Not read in step 0: tool output, thinking blocks (almost always empty), compaction summaries and agent wrap-ups (paraphrases that can invent decisions), bot and CI comments, status changes, merges as such.
Conversations outside our tools are not read: they are expected to reach us restated in a session.
Rules: how a source shapes each label
- The origin. A decision's origin is the earliest source where the choice is made. A plan in an issue description, a to-do, or a later restatement is not the origin. Every other source of the same choice is a second source, merged in.
- When is the origin's time; for a reported decision, the time stated, else the restatement's time marked "by then". A later edit of a description never moves it.
- Who decided comes from the origin's words (section 5), with three overrides:
- on GitHub and Linear, the item's own signals win (a Co-Authored-By trailer, "Generated with", a bot account, "on behalf of");
- a PR or issue an agent wrote to carry out a session decision doesn't change who decided: the session origin wins;
- an agent's decision becomes agreed only when a person explicitly approves that choice later (a reply in the session, a review comment on it). Approving or merging the whole PR is not approving each choice in it.
- Wording (title and line) comes from the strongest source: the person's own words, then a review thread, then a Linear comment, then a PR description. An agent-written PR description ranks lowest.
- Reasons attributed to a person must be quoted from that person's words. A reason that only an agent wrote (in a PR description, in a summary) is never given as the person's reason; it can stand as the agent's reason, marked as such, or be left out.
- Issue: the folder or branch at the origin turn, then the PR's links ("closes GOD-…"), then the issue the comment sits on. When they disagree, the origin's wins and the reviewer can correct it.
- Files: the files edited after the origin turn in the same piece of work, plus the diff of the PR that carries the decision.
- Links come from meaning, ordered by origin dates: a later source repeating the same choice is a duplicate (merged as a source); a later source deciding the same question differently supersedes or reverses; a later source carrying it out or adjusting one part is a detail. An earlier origin never supersedes a later one.
- Confidence follows the source. A draft whose only sources are second-rank (a PR or issue description) is drafted as doubtful and sinks in the review queue.
- Level and how much it matters are judgements, never taken from a source. A decision written in a spec or a Linear document is a hint toward core, not a rule.
Changes
- 2026-10-10 · Linear issue descriptions are never the origin of a decision, only context and a second source (Wilfried, keeping the spec's decision 14).
- 2026-10-10 · Hard cases added: a decision on a branch never merged; a plan stated in the future.
- 2026-10-10 · "Who should know" is no longer labelled: it is learned from readers' reactions in the digest; the expertise rewrite needs only the reader's expertise (Wilfried). Subagent transcripts are a source from the start: the plugin collects them (Wilfried).
- 2026-10-10 · Section 11: which sources step 0 reads, and the rules for how a source shapes each label (origin, when, who decided, wording, reasons, issue, files, links, confidence).
- 2026-10-10 · Decisions made between people and restated in a session are labelled as reported (Wilfried: they "will be restated there to do the actual work or file it in Linear").
- 2026-10-10 · v0, written before the first labelled day (Claude, from the Teams plan's step 0 details and the compile's definition of a decision).