docs(agents): add PR description standard + /pr-describe command#458
Conversation
Establish a default PR-description format so reviewers can judge the architecture and technical decisions without reading low-level code: high-level mechanism narrative, GitHub-rendered mermaid diagrams, a code-area map, and explicit technical trade-offs. - AGENTS.md: new "PR descriptions" section (cross-harness; followed by any agent that reads AGENTS.md), linked from the Claude Code commands list - .claude/commands/pr-describe.md: /pr-describe slash command that operationalizes the standard against the current branch's diff Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
github-actions
Bot
added
the
documentation
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 4686dd5b90
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
🔐 Codex Security Review
Review SummaryOverall Risk: HIGH Findings[HIGH] Branch refs can be interpolated into shell commands unsafely
NotesThe reviewed diff only changes repository guidance and Claude command files: Generated by Codex Security Review | |
There was a problem hiding this comment.
Pull request overview
This PR adds repo-wide guidance for writing PR descriptions that communicate architecture and technical decisions at a high level, and introduces a Claude Code /pr-describe command to generate/update descriptions in that standard.
Changes:
- Adds a new “PR descriptions” section to
AGENTS.mddefining a 6-part PR body structure (summary, mechanism, diagrams, code-area map, decisions, testing). - Adds
.claude/commands/pr-describe.mdto operationalize the standard via a slash command and optional PR targeting.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
AGENTS.md |
Defines the canonical PR description structure and links to /pr-describe in the command list. |
.claude/commands/pr-describe.md |
Adds a Claude Code command for generating/updating PR descriptions from the current branch diff or a specified PR. |
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Ankit Goswami <ankit.goswami@gmail.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Ankit Goswami <ankit.goswami@gmail.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Ankit Goswami <ankit.goswami@gmail.com>
The numbered-PR path resolved the PR in step 1 but then read the change via local git (HEAD), so running `/pr-describe <n>` from any other branch drafted from an unrelated checkout and could overwrite the requested PR with the wrong description. Split the steps into two explicit paths that never mix: the numbered-PR path reads exclusively via `gh pr diff <n>` / `gh pr view <n> --json commits` and edits by the metadata-derived `number`; the current-branch path keeps using local `git diff <base>...HEAD`. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: dddab134ca
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
Both /pr-ready step 5 and CONTRIBUTING.md still drafted the old "Summary + Test Plan" body, diverging from the six-part PR descriptions standard added to AGENTS.md. Point both at that standard (the same structure /pr-describe produces) so the three stay consistent; /pr-ready folds its lint/test results into Testing & validation. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The argument-hint contained "optional: PR" — a colon followed by a space inside an unquoted YAML scalar, which strict parsers (e.g. Psych) reject as a nested mapping. Claude Code reads slash-command metadata from this frontmatter, so the command could fail to load. Quote the value. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 7c75535d81
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
On the numbered-PR path the argument may be a URL for a different repo, but the read/edit calls used a bare PR number, which gh resolves in the current repo. A cross-repo URL could read one PR and then edit a same-numbered PR locally. Parse owner/repo from the resolved url and pass -R <owner>/<repo> on every gh pr call (diff, view, edit) for that path. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Resolve the diff base from the PR's baseRefName against origin (not the bare local ref) so a moved parent branch can't produce a stale diff, detect when a PR is stacked (base is not the default branch), walk the ancestor chain, and require the description to carry the load-bearing context from upstream PRs a reviewer needs to judge the change. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Walk the stack downward as well as upward: find child PRs (whose base is this PR's head) so the Stack note can show the full chain and tell the reviewer what is deferred to descendant PRs. A reviewer of a deliberately scoped PR needs to know what remains and where it lands, not just what the PR builds on. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Deferred work is often not an open PR yet. Treat the effort's plan docs (docs/plans/) and the interactive conversation as first-class sources for what is out of scope and where it lands, alongside descendant PRs, and record the tracking references even when no PR exists. Keep it to scope facts, not a narration of how the work was planned. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: dbef14b3d0
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
…d PRs A foundation PR that targets the default branch but has descendants (or a title marked N/M) is still part of a series and needs the Stack note. Detect a series from any of three signals (base is not the default branch, has descendant PRs, or an N/M / part-N title) instead of the base ref alone. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: f962769b51
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
- pr-describe: quote JSON-derived branch refs (headRefName/baseRefName) in the shell examples and add a rule, so a branch name with shell metacharacters can't run unintended commands. - pr-ready: only reuse the step-1 main...HEAD diff for the description when the branch targets the default branch; for a stacked/series branch, delegate to /pr-describe so the description is scoped to the real base instead of folding in ancestor changes. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 28c0b8998a
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
Summary
Establishes a default PR-description format across the repo so reviewers can judge the architecture and technical decisions without reading low-level code. Modeled on the well-received description for #235 (high-level mechanism + mermaid diagrams), generalized into a reusable standard.
How it works
CLAUDE.mdalready defers to it. Adding the standard there makes it the default any agent follows when opening a PR — no per-tool configuration./pr-describegives Claude Code users a one-command way to generate a conforming description from the current branch's diff.Areas of the code involved
AGENTS.md## PR descriptionssection (6-part structure: Summary, How it works, Diagrams, Areas of code, Technical decisions, Testing); linked/pr-describefrom the Claude Code command list.claude/commands/pr-describe.md/pr-describeslash command operationalizing the standard against the branch diff.claude/gitignore); matches the existing tracked commands in that dirKey technical decisions & trade-offs
gh pr create. Apull_request: openedAction could be a tool-agnostic backstop later if we want one.Testing & validation
Docs/tooling only — no code paths change. Verified the
/pr-describecommand is picked up by Claude Code (appears in the command catalog) and that AGENTS.md matchedorigin/mainbefore the edit (clean, isolated diff). Not covered: behavior of non-Claude agents reading the new section (relies on each harness honoring AGENTS.md).🤖 Generated with Claude Code