Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

chore(agents): aim pr bodies at 150 words, suggest a stack past it (#122773)

Raúl Negrón-Otero8acb28dbed52
diff --git a/.agents/skills/writing-pr-descriptions/SKILL.md b/.agents/skills/writing-pr-descriptions/SKILL.md
index 904c486abde4..a295a059fea5 100644
--- a/.agents/skills/writing-pr-descriptions/SKILL.md
+++ b/.agents/skills/writing-pr-descriptions/SKILL.md
@@ -6,7 +6,7 @@ description: >-
States who is affected and what is wrong for them in Problem, taken from a source and never invented, then the visible effect and mechanism in Changes.
Selects bullets, tables, diagrams, screenshots, or collapsed blocks for each fact.
Removes unnecessary detail and checks one fact per bullet, sentences under 25 words, active voice, and no idioms.
- Keeps the body complete without the diff, scales its length to the change, and links evidence or marks claims as unchecked.
+ Keeps the body complete without the diff, aims for 150 words and suggests a stack when the PR needs more, and links evidence or marks claims as unchecked.
Checks the title and first lines of Problem and Changes.
Not for commit messages (see AGENTS.md, "Commit types") or product copy (see `/writing-user-facing-copy`).
---
@@ -93,19 +93,19 @@ Nothing was added and nothing was cut. The reviewer now knows the stakes before
Prose is the slowest form on the page. Before writing a sentence, ask what carries the fact faster.
-| The fact you have | The form that carries it |
-| ------------------------------------------------------------------------------------ | --------------------------------------------------------- |
-| A visual change (any UI a person sees, including a flow through screens) | Screenshot, before and after. Mandatory, not optional |
-| A new action and its effect, which one screenshot cannot show | A feature reel in place of the "after" screenshot |
-| An architecture or topology change one sentence cannot carry (defined under Mermaid) | Two branded `flowchart` blocks, before first |
-| Several values compared across the same dimensions | A markdown table |
-| A config or setting change | A fenced `diff` block |
-| Existing code a reviewer needs to see | A line-range permalink, which GitHub renders as a snippet |
-| Test output, logs, long command transcripts | A `<details>` block |
-| A behavior change or a risk a reviewer must not miss | `> [!WARNING]` or `> [!NOTE]` |
-| Anything else | Bullets, under the shape rule in pass 4 |
+| The fact you have | The form that carries it |
+| ------------------------------------------------------------------------ | --------------------------------------------------------- |
+| A visual change (any UI a person sees, including a flow through screens) | Screenshot, before and after. Mandatory, not optional |
+| A new action and its effect, which one screenshot cannot show | A feature reel in place of the "after" screenshot |
+| An architecture or topology change (defined under Mermaid) | Two branded `flowchart` blocks, before first |
+| Several values compared across the same dimensions | A markdown table |
+| A config or setting change | A fenced `diff` block |
+| Existing code a reviewer needs to see | A line-range permalink, which GitHub renders as a snippet |
+| Test output, logs, long command transcripts | A `<details>` block |
+| A behavior change or a risk a reviewer must not miss | `> [!WARNING]` or `> [!NOTE]` |
+| Anything else | Bullets, under the shape rule in pass 4 |
-No PR needs every form. Reach for one because it makes review faster, never as decoration. An empty section gets one bullet or "None".
+No PR needs every form. Reach for one because it makes review faster, never as decoration. An empty section gets one bullet: `- None.`
### Screenshots and reels
@@ -129,12 +129,14 @@ Touching UI code without a visible change is common, and the mandate has to be d
### Mermaid
-Draw a diagram only for an architecture or topology change that one sentence cannot carry.
+Draw before-and-after diagrams for every architecture or topology change, under one short sentence that states the change.
Architecture and topology mean CI wiring, pipelines, services and the calls between them, or module and package boundaries.
They also mean a state machine with several states, or a request path across systems.
+This includes a small change, such as one step added to a straight chain or one fallback added to a lookup.
+A reviewer sees a diagram at a glance, and can miss one sentence among the bullets.
+The sentence gives a scanner the point, and the diagrams carry the flow, so the sentence never grows complex to explain it.
A UI flow or a linear sequence of screens is not a topology.
It gets screenshots or a reel, not a diagram.
-When one sentence states the whole change, such as one step added to a straight chain, write the sentence instead.
Keep diagrams simple. A syntax error renders as an error block. Pick `TD` for tall pipelines, `LR` for wide paths. Mermaid cannot read CSS vars, so use the hex directly, and pair every `fill` with a text `color` so nodes stay legible in GitHub light and dark.
@@ -175,15 +177,39 @@ Delete:
- The follow-up sentence in any "here is the reason, and here is why the reason matters" pair.
- Any bullet whose reader you cannot name.
-### Size tracks the change
+❌ Three bullets from a real draft, each true:
+
+> - The script prints 145 for this body and 199 for example 2.
+> - `hogli lint:skills` passes.
+> - The author decides whether to stack.
+
+✅ Delete all three.
+The first is a number the reviewer cannot use. CI already reports the second. The third tells the reviewer nothing to check or decide.
+
+### 150 words
A body that would fit any PR tells a reader nothing about this one. A reader who meets a few learns to skip them all.
When the diff is six lines, the body has to read as the body of a six-line change.
-- A one-file fix: 3 to 6 bullets across the whole body.
-- A typical PR: Problem and Changes together fit in about 10 bullets.
-- One line or "None" under every heading that does not apply. That is a complete answer, not a gap.
-- Numbers, file paths and identifiers survive cutting. Adjectives and second explanations do not.
+- Aim for 150 words or fewer across the whole body, table cells included. A reviewer reads a table as closely as a bullet, so moving a sentence into one shortens nothing.
+- Headings, diagrams, code blocks, images, HTML tags and `<details>` blocks do not count. Inline code counts.
+- Moving evidence and transcripts into `<details>` is the first cut. Problem and Changes never move there: a reviewer skips collapsed text, so a fact they need stays visible and counts.
+- The template's fixed lines, such as the release status and agent context labels, use about 25 of the 150 words.
+- Give a one-file fix 3 to 6 bullets across the whole body.
+- Write `- None.` under every heading that does not apply. That is a complete answer, not a gap. It is a bullet, like the release status line the changelog bot reads, so empty sections look the same.
+- Keep numbers, file paths and identifiers when you cut. Cut adjectives and second explanations.
+
+Run the counter on the body as GitHub stores it, after every `gh pr create` or `gh pr edit`, so you never paste the body twice. A new PR is a draft, so fix an over-count with `gh pr edit`:
+
+```sh
+gh pr view <number> --json body --jq .body | uv run .agents/skills/writing-pr-descriptions/scripts/count_words.py -
+```
+
+`uv run` installs the script's one dependency in its own environment and leaves the repo's virtualenv alone.
+
+When the count is still over 150 after cutting, the PR is probably too big to review in one pass.
+Suggest a stack to the PR author, name the layers you would split it into, and point to `/stacking-prs`.
+The author decides. If they keep one PR, ship the shortest body that still carries the change.
Small does not mean partial. Three bullets still have to carry why the change is necessary and what it does.
@@ -207,7 +233,8 @@ Everything under them is evidence and provenance, and a reviewer reaches it last
When the lower half outgrows the upper half, cut the lower half.
- Testing: name the regression each new test catches, under the claim rules above. Transcripts go in a `<details>` block.
-- Agent context: autonomy, tool and exact model, skills invoked, and what changed across the session.
+- Agent context: autonomy, the tool with its exact model, and the skills invoked stay visible. Session notes, decisions and the rest go in the collapsed "More context for AI agents" block, in the template's field order.
+- Rewrite that block on every push so it describes the PR at that commit. A stale block misleads the next agent more than an empty one.
- The reason your design beats the obvious alternative belongs in Changes. A reviewer needs it to review, and nobody scrolls past the release status section to find it.
The test: **the body must come out shorter than your first draft.** Pass 5 checks it.
@@ -277,8 +304,8 @@ A "no" anywhere means the body is ordered for the writer, not the reader. Go bac
### The line check
1. Is the body shorter than your first draft? If it is longer, you split without cutting. Go back to pass 3.
-2. Does the size of the body track the size of the diff? A six-line change under a full-length body reads as filler.
-3. Are Problem and Changes together longer than the sections under them? If not, cut the lower ones.
+2. Does the size of the body track the size of the diff, and does `scripts/count_words.py` print 150 or less? If not, cut, or suggest a stack as "150 words" says.
+3. Are Problem and Changes together longer than the sections under them, with nothing of theirs inside `<details>`? If not, cut the lower ones.
4. Read the body with the diff closed. Can you say why the PR exists and what it does? If not, you cut something a reader needs.
5. Does Problem state a need that no source in the request, an issue, or a thread gave? Delete it, and say the reason was not given.
6. Read Changes alone. Can you say what a person will now see or do differently, or that nothing user-visible changed? If neither, go back to pass 1.
@@ -289,11 +316,11 @@ A "no" anywhere means the body is ordered for the writer, not the reader. Go bac
11. Does any sentence take its author as the subject? Rewrite it around the change. "I", "me" and "my" appear nowhere.
12. Does the PR change anything a person sees? Include before-and-after screenshots, or say why nothing looks different.
13. Did you rewrite an existing body? Every image, video, link and ticked box a person put there still appears.
-14. Does the PR change architecture or topology in a way one sentence cannot carry, as defined under Mermaid? Include branded before-and-after diagrams. Delete any diagram of a UI flow or of what one sentence says.
+14. Does the PR change architecture or topology, as defined under Mermaid? Include branded before-and-after diagrams under one short sentence, also for a one-step change. Delete any diagram of a UI flow.
15. Does prose compare several values across the same dimensions? Replace it with a table.
16. Does every claim about what you ran, measured or saw link its evidence, or say it went unchecked? Descriptions of behavior need no link.
-17. Did a `<!-- -->` template comment survive anywhere? That section is unfilled. Fill it or delete it.
-18. Is the `## 🤖 Agent context` section filled, naming the exact model and listing the skills invoked?
+17. Did a `<!-- -->` template comment or any template placeholder text, such as `tool, model` or the bracketed test rationale, survive anywhere, collapsed blocks included? That field is unfilled. Fill it or delete it.
+18. Is the `## 🤖 Agent context` section filled, naming the exact model and listing the skills invoked? Does the collapsed block still describe the PR as pushed?
19. Does the body claim manual testing that did not happen? Delete it.
20. Does the body name an internal customer, incident, Slack quote, or operational metric? This repo is public. Delete it.
diff --git a/.agents/skills/writing-pr-descriptions/references/examples.md b/.agents/skills/writing-pr-descriptions/references/examples.md
index 59e4b000e4aa..2e1ab82d565e 100644
--- a/.agents/skills/writing-pr-descriptions/references/examples.md
+++ b/.agents/skills/writing-pr-descriptions/references/examples.md
@@ -14,7 +14,7 @@ The measurements behind these rules live in the PR that introduced them, reachab
[fix(dashboards): tolerate legacy keys in persisted dashboard filters](https://github.com/PostHog/posthog/pull/78235).
-### Problem as shipped, 82 words
+### Problem as shipped, 78 words
```markdown
- `Dashboard.filters` persists opaquely, and readers rebuild the `extra="forbid"` `DashboardFilter` from it on every tile refresh.
@@ -23,7 +23,7 @@ The measurements behind these rules live in the PR that introduced them, reachab
- A support ticket hit exactly this: a REST client wrote the legacy insight-format key `filter_test_accounts`, and the dashboards stayed broken until the blob is rewritten by hand.
```
-### After pass 1, 71 words
+### After pass 1, 67 words
```markdown
- One legacy key in a dashboard's saved filters errors every tile on that dashboard.
@@ -52,7 +52,7 @@ The rejected alternative is the one line a reviewer needs to judge the design. I
[fix(data-warehouse): recognize Neon's pooler rejection of libpq options](https://github.com/PostHog/posthog/pull/77899). Problem and Changes only.
-### As shipped, 297 words
+### As shipped, 296 words
```markdown
## Problem
@@ -79,62 +79,58 @@ Match on the prefix `unsupported startup parameter in options` so any setting Ne
The stale comment on the CDC stream reader claimed CDC sources never sit behind a pooler that rejects `options`. They do. Neon's pooler serves the `pg_logical_slot_peek_binary_changes` calls the reader uses just fine, so dropping the two server-side timeouts is the difference between working change capture and none at all. Updated it to say so, and to note that the activity's start-to-close and heartbeat timeouts still bound a stalled peek once the server-side ceiling is gone.
```
-### After the remaining passes, 197 words
+### After the remaining passes, 124 words
````markdown
## Problem
-- Transaction-mode connection poolers reject the libpq `options` startup parameter.
-- `_connect_with_options_fallback` drops `options` and reconnects when it sees the exact wording those poolers use:
+- Data warehouse syncs from a Neon pooled endpoint fail on every extraction run.
+- The user is told to check a database that is reachable and healthy, because the failure classifies as a retryable `connection_failed`.
+- Transaction-mode poolers reject the libpq `options` startup parameter.
+- `_connect_with_options_fallback` reconnects without `options` when it sees this wording:
```
FATAL: unsupported startup parameter: options
```
-- Neon's pooled endpoint names the setting instead of the parameter:
+- Neon's pooler names the setting instead:
```
ERROR: unsupported startup parameter in options: statement_timeout.
```
-- That is not a substring of the match, so the fallback never fires.
-- The CDC stream reader always sends `options`, and that connect is the first thing `cdc_extract_activity` does.
-- Every extraction run against a Neon pooled endpoint therefore fails at `stream_reader.connect()`, forever.
-- It classifies as a retryable `connection_failed`, so the user is told to check a database that is reachable and healthy.
-- One source has never had a successful extraction run since the day it was created.
+- That wording misses the match, so the fallback never fires.
+- The CDC stream reader always sends `options` on its first connect.
## Changes
- The match now uses the prefix `unsupported startup parameter in options`, so any setting Neon names is covered.
-- The stream reader's comment claimed CDC sources never sit behind a pooler that rejects `options`. They do, and the comment now says so.
-- Dropping the two server-side timeouts is the difference between working change capture and none.
+- The stream reader's comment claimed CDC sources never sit behind a pooler that rejects `options`. It now says they do.
> [!NOTE]
-> Retry and classification behavior do not change. This makes the connection succeed where it currently cannot be opened at all.
+> Retry and classification behavior do not change.
````
### What the passes did
-Pass 3 cut 100 words:
+Pass 1 moved the effect to the top. The shipped body led with a fact about libpq and stated the effect last.
-| Cut | Why |
-| ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
-| The second line of Neon's error, and the full quoted user-facing message | The reader needs the phrasing that breaks the match, not the whole string |
-| `statement_timeout=1800000 -c idle_in_transaction_session_timeout=0` | "Always sends `options`" is the fact. The values themselves change nothing for the reader |
-| "There is nothing they can do to make that message go away, because it isn't describing their problem" | Second half of a reason pair. The bullet above it already says the database is healthy |
-| "Neon's pooler serves the `pg_logical_slot_peek_binary_changes` calls the reader uses just fine" | Supports a claim nobody will dispute |
-| The start-to-close and heartbeat timeout note | Belongs in the code comment it describes, and is there |
+Pass 3 cut 172 words:
-Pass 4 split the 76-word failure chain, which was the densest sentence in the description, into the five links a reviewer checks one at a time.
+| Cut | Why |
+| ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| The second line of Neon's error, and the full quoted user-facing message | The reader needs the phrasing that breaks the match, not the whole string |
+| `statement_timeout=1800000 -c idle_in_transaction_session_timeout=0` | "Always sends `options`" is the fact. The values themselves change nothing for the reader |
+| "There is nothing they can do to make that message go away, because it isn't describing their problem" | Second half of a reason pair. The bullet above it already says the database is healthy |
+| "Neon's pooler serves the `pg_logical_slot_peek_binary_changes` calls the reader uses just fine" | Supports a claim nobody will dispute |
+| The start-to-close and heartbeat timeout note | Belongs in the code comment it describes, and is there |
+| "One source has never had a successful extraction run since the day it was created" | An observation with no link to the run. "Fail on every extraction run" carries the same stakes as behavior a reader can check against the code |
+| "Dropping the two server-side timeouts is the difference between working change capture and none" | The reason for the comment change, and the comment already says it |
+| `cdc_extract_activity`, `stream_reader.connect()`, "forever" | "On its first connect" is the fact. The names are one level below what a reviewer checks |
-Both fenced blocks survived untouched. Pass 4 governs prose only.
-
-Pass 1 came later than this rewrite, and the rewrite fails it. The lead is a fact about libpq, while the effect sits in bullets 6 and 8. Cutting did not fix that, and no amount of it would. Open with them instead:
+Pass 4 split the 76-word failure chain, which was the densest sentence in the description, into the links a reviewer checks one at a time.
-> - Data warehouse syncs from a Neon pooled endpoint have never worked. One source has failed every extraction run since the day it was created.
-> - The user is told to check a database that is reachable and healthy, because the failure classifies as a retryable `connection_failed`.
-
-That first bullet is also the one claim here the claim rules in pass 3 reach. "Never worked" and "every run" are things the author saw, not behavior a reader can check against the code. The bullet owes a link to the run or the error tracking issue behind it. Every other bullet in this example describes behavior and needs none.
+Both fenced blocks survived untouched. Pass 4 governs prose only.
---
@@ -142,7 +138,7 @@ That first bullet is also the one claim here the claim rules in pass 3 reach. "N
[fix(flags): drop custom codecs from flag_evaluations columns](https://github.com/PostHog/posthog/pull/77910). Problem and Changes only.
-### As shipped, 190 words
+### As shipped, 191 words
```markdown
## Problem
@@ -156,7 +152,7 @@ Migration 0293 sets the codecs 0292 declared and then removes them with `MODIFY
`posthog/models/flag_evaluations/sql.py` is the shared column template other DDL reads from, so the per-column `CODEC(...)` clauses are stripped there too. The HCL golden/SQL mirrors and the `test_schema.ambr` snapshot are regenerated to match.
```
-### After the remaining passes, 111 words
+### After the remaining passes, 112 words
```markdown
## Problem
@@ -190,4 +186,4 @@ Nobody sees this change, which is the case pass 1 is easiest to skip on. There i
> - The codecs on `flag_evaluations` take those columns out of the cluster's central compression tuning and buy nothing back.
-The line check's first item is what makes this a rewrite rather than a reformat: the body has to come out shorter. Both cut examples do, 297 words to 197 and 190 to 111, and the reorder in example 1 came out shorter too.
+The line check's first item is what makes this a rewrite rather than a reformat: the body has to come out shorter. Both cut examples do, 296 words to 124 and 191 to 112, and the reorder in example 1 came out shorter too.
diff --git a/.agents/skills/writing-pr-descriptions/scripts/count_words.py b/.agents/skills/writing-pr-descriptions/scripts/count_words.py
new file mode 100644
index 000000000000..0f2c1a6edfe1
--- /dev/null
+++ b/.agents/skills/writing-pr-descriptions/scripts/count_words.py
@@ -0,0 +1,90 @@
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.12"
+# dependencies = [
+# "markdown-it-py~=3.0.0",
+# ]
+# ///
+# ruff: noqa: T201 allow print statements
+"""
+Print the number of words a reviewer reads in a PR body, table cells and inline code included.
+
+Headings, code blocks, HTML tags, images, task list checkboxes, and everything inside <details> do not count.
+List markers and other words without a letter or digit do not count.
+
+Usage:
+ uv run count_words.py pr-body.md
+ gh pr view 123 --json body --jq .body | uv run count_words.py -
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+import argparse
+from html.parser import HTMLParser
+from pathlib import Path
+
+from markdown_it import MarkdownIt
+from markdown_it.rules_core import StateCore
+
+UNCOUNTED_TAGS = {"h1", "h2", "h3", "h4", "h5", "h6", "pre", "details"}
+TASK_MARKER = re.compile(r"^\[[ xX]\](?=\s|$)")
+
+
+class WordCounter(HTMLParser):
+ def __init__(self) -> None:
+ super().__init__()
+ self.open_uncounted_tags: list[str] = []
+ self.words = 0
+
+ def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+ if tag in UNCOUNTED_TAGS:
+ self.open_uncounted_tags.append(tag)
+
+ def handle_endtag(self, tag: str) -> None:
+ if tag in self.open_uncounted_tags:
+ while self.open_uncounted_tags.pop() != tag:
+ pass
+
+ def handle_data(self, data: str) -> None:
+ if not self.open_uncounted_tags:
+ self.words += sum(1 for word in data.split() if any(char.isalnum() for char in word))
+
+ def close(self) -> None:
+ super().close()
+ if self.open_uncounted_tags:
+ raise ValueError(
+ f"<{self.open_uncounted_tags[0]}> is never closed, so GitHub hides everything after it. Close it and run again."
+ )
+
+
+def render_task_markers_as_checkboxes(state: StateCore) -> None:
+ """Render GitHub task list markers as checkbox tags, as GitHub does, so they parse as markup."""
+ for list_item, inline in zip(state.tokens, state.tokens[2:]):
+ if list_item.type == "list_item_open" and inline.type == "inline":
+ inline.content = TASK_MARKER.sub('<input type="checkbox">', inline.content, count=1)
+
+
+def count_words(markdown: str) -> int:
+ parser = MarkdownIt("commonmark").enable("table")
+ parser.core.ruler.before("inline", "task_markers", render_task_markers_as_checkboxes)
+ counter = WordCounter()
+ counter.feed(parser.render(markdown))
+ counter.close()
+ return counter.words
+
+
+def main() -> None:
+ parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ parser.add_argument("body", help="PR body markdown file, or - to read stdin")
+ args = parser.parse_args()
+ try:
+ body = sys.stdin.buffer.read() if args.body == "-" else Path(args.body).read_bytes()
+ print(count_words(body.decode("utf-8-sig")))
+ except (OSError, ValueError) as error:
+ parser.error(str(error))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 4c405c47bde7..4e2fe5d7ccb2 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -1,4 +1,4 @@
-<!-- This has to stand on its own: a reader who opens no files should still know why the PR is necessary and what it does. Length tracks the change, so a small diff gets a few bullets rather than a full-length body, and a section you have nothing for gets one line or "None". -->
+<!-- This has to stand on its own: a reader who opens no files should still know why the PR is necessary and what it does. Aim for 150 words or fewer, table cells included. Diagrams, code blocks and <details> blocks do not count. A section you have nothing for gets one bullet: "- None." -->
## Problem
@@ -57,6 +57,10 @@
**Agent:** tool, model
+<!-- List every repo-provided or public skill invoked (e.g. /django-migrations, /improving-drf-endpoints), so reviewers can see where an agent shaped the code. Write "None" when no skill ran. -->
+
+**Skills:** `/skill`
+
<!-- Definition of done (agents): not done until each gate below holds. Verify against the named artifact or skill — don't assume. Add gates as the PR touches more areas.
- No duplicate: when this PR fixes something believed to be live on master, no open PR already fixes it. A broken master attracts parallel agents, so search before opening — `gh pr list --state open --search "<keywords>" --limit 20`, which lists drafts too, and most agent PRs start as drafts. Say here which PR you found and why this one is still needed, or that the search found nothing.
- Patch coverage: the lines this PR changed are covered, or the uncovered ones are justified under "How did you test this code?". Don't pad untouched code to lift the number. Check the "🧪 Backend test coverage" PR comment (and its patch-coverage artifact).
@@ -64,16 +68,23 @@
- Public artifact: nothing in this PR — code, fixtures and sample data, comments, commit messages, or this description — carries material from the agent session that isn't already public. If the work drew on a customer conversation, ticket, or log, say so here and state that the committed data is invented. Renaming people, hosts, and identifiers does not clear real material; see AGENTS.md "Public open source repo guidance".
-->
-<!-- Keep this short: 1-3 short paragraphs or a handful of bullets — not an exhaustive log. Include:
- - link to session and the tool names used, but do not include tool call results.
- - skills invoked: always explicitly call out any repo-provided or public skills (e.g. /django-migrations, /improving-drf-endpoints) that were invoked while producing this PR. This helps reviewers judge where and how the code was shaped by an agent.
- - decisions made along the way: what changed across the session. The reason the shipped design beats the obvious alternative goes in Changes instead, where a reviewer will actually see it.
- - anything else that helps reviewers
- Write reviewer-facing prose. Do not paste user prompts verbatim — paraphrase the intent in your own words.
- This is the ONLY section that should contain descriptions of what this PR might have looked like before its present final state.
- Don't duplicate info already present in preceding sections.
- DO NOT INCLUDE sensitive data that may have been shared in an agent session — that applies to every part of this PR, not just this section.
--->
+<details>
+<summary>More context for AI agents</summary>
+
+<!-- Agents: this block is collapsed by default and does not count toward the 150 words.
+ Keep it current: on every push, rewrite it to describe the PR at that commit. Replace stale bullets, never append a log.
+ Keep the fields below in this order. One line per bullet, under 25 words, 10 bullets at most. Delete a field you have nothing for.
+ - Decisions: what changed across the session. The reason the shipped design beats the obvious alternative goes in Changes, where a reviewer will see it.
+ This is the ONLY place that may describe what this PR looked like before its present state. Don't repeat facts from the sections above.
+ Paraphrase the intent of user prompts, never paste them. Link the session, name the tools, but leave out tool call results.
+ DO NOT INCLUDE sensitive data that may have been shared in an agent session — that applies to every part of this PR, not just this block. -->
+
+- **Session:** link, tools used
+- **Decisions:** one bullet per decision
+- **Follow-ups:** work left for a later PR
+- **Read closely:** files or lines that need a careful review
+
+</details>
<!-- Overall PR authoring rules for agents:
- Title: <type>(<scope>): <description> — type=feat|fix|chore, scope required, lowercase, no period, <72 chars.
@@ -82,9 +93,9 @@
- Description: high-level rationale, not a step-by-step replay.
- Voice: the subject of every sentence is the change, never its author. No "I", "me" or "my" anywhere in the body. "I (actually Claude)" is worse than either half: it hands the assignee an account of work they did not do. Authorship is one stated fact in the Agent context section below.
- Body: pass it straight to the creation tool's `body` arg (GitHub MCP `create_pull_request` body, or `gh pr create --body-file -` via stdin) — don't write it to a temp file first; the arg preserves markdown and newlines verbatim.
-- Architecture and topology changes: when one sentence cannot carry the change, include separate before-and-after Mermaid `flowchart` blocks with PostHog colors. This covers CI wiring, pipelines, services and their calls, module or package boundaries, state machines with several states, and request paths across systems. A UI flow or a linear sequence of screens gets screenshots or a reel, not a diagram. Use `/writing-pr-descriptions` for the palette and role mapping.
+- Architecture and topology changes: include separate before-and-after Mermaid `flowchart` blocks with PostHog colors under one short sentence that states the change, also for a one-step change. This covers CI wiring, pipelines, services and their calls, module or package boundaries, state machines with several states, and request paths across systems. A UI flow or a linear sequence of screens gets screenshots or a reel, not a diagram. Use `/writing-pr-descriptions` for the palette and role mapping.
- Public OSS repo: no internal customers, incidents, or operational metrics.
-- Stack instead of stuffing: if the diff holds two or more separable steps (migration then behavior, rename then rewrite), open a stack rather than one big PR. See AGENTS.md, "Stacked PRs" and /stacking-prs.
+- Stack instead of stuffing: if the diff holds two or more separable steps (migration then behavior, rename then rewrite), open a stack rather than one big PR. If the body needs more than 150 words, suggest a stack to the person who directed the work. See AGENTS.md, "Stacked PRs" and /stacking-prs.
- Simplify before opening: if your agent has a behavior-preserving cleanup pass (Claude Code: `/simplify`), run it on a non-trivial diff before final tests and preflight, since it edits the tree. Skip it for small mechanical changes.
- Draft by default: open new PRs as drafts (`gh pr create --draft`) — drafts run only a narrow CI subset and save runner credits. Fix CI and run affected tests locally before marking ready for review.
- Labels: apply `skip-agent-review` for trivial/chore PRs that don't need an automatic review.
@@ -94,5 +105,5 @@
- Do not add a human Co-authored-by just for the sake of attribution — if no human was involved in the changes, own it as agent-authored.
- Agent-authored PRs always require human review — do not self-merge or auto-approve.
- Do NOT claim manual testing you haven't done.
-- Shape and style: invoke the `/writing-pr-descriptions` skill before writing this body. In short: lead Problem with who is affected and what is wrong for them, taken from a source and true under any solution, then lead Changes with the effect a person sees rather than the code path behind it. Make the body stand alone for a reader who opens no files, size it to the change, link evidence rather than asserting what CI already reports, then hold what's left to one fact per bullet in under 25 words. A body that got longer as bullets was not cut.
+- Shape and style: invoke the `/writing-pr-descriptions` skill before writing this body. In short: lead Problem with who is affected and what is wrong for them, taken from a source and true under any solution, then lead Changes with the effect a person sees rather than the code path behind it. Make the body stand alone for a reader who opens no files, aim for 150 words, link evidence rather than asserting what CI already reports, then hold what's left to one fact per bullet in under 25 words. A body that got longer as bullets was not cut.
-->
diff --git a/.github/workflows/publish-symbol-data-crate.yml b/.github/workflows/publish-symbol-data-crate.yml
index 9acdddb601fe..1caa371fdcd6 100644
--- a/.github/workflows/publish-symbol-data-crate.yml
+++ b/.github/workflows/publish-symbol-data-crate.yml
@@ -298,7 +298,7 @@ jobs:
## Docs update
- None.
+ - None.
## 🤖 Agent context
diff --git a/.github/workflows/release-cli.yml b/.github/workflows/release-cli.yml
index f230bd4e8204..263756427593 100644
--- a/.github/workflows/release-cli.yml
+++ b/.github/workflows/release-cli.yml
@@ -381,7 +381,7 @@ jobs:
## Docs update
- None.
+ - None.
## 🤖 Agent context