Skip to content

πŸ™Œ OpenHands: AI-Driven Development

docs(codereview): require design docs for deep, high-risk PRs (#17267)

🐾 smolpawsbb24c705572f
diff --git a/.agents/skills/custom-codereview-guide.md b/.agents/skills/custom-codereview-guide.md
index 8d7760d77c..3e13cbece5 100644
--- a/.agents/skills/custom-codereview-guide.md
+++ b/.agents/skills/custom-codereview-guide.md
@@ -184,6 +184,51 @@ data, user actions, lazy initialization, store mirroring, or ordering repairs.
Subscriptions, browser APIs, timers, and network synchronization remain valid
when cleanup and dependencies are explicit.
+## Design Context for Deep PRs
+
+A diff shows each changed line, not the design. Expect durable design context
+when a reviewer cannot judge a PR from the diff in a couple of minutes, for
+example:
+
+- a new or changed Agent Server, Cloud, or automation integration, event
+ contract, or persisted-state shape;
+- a new feature module or subsystem, a cross-cutting refactor, or a migration;
+- a behavior change in backend selection, conversation flow, or settings and
+ profile transitions; or
+- a large change whose intent cannot be reconstructed from the diff, even if no
+ single hunk is complex.
+
+Do not ask for design context on trivial, generated, or self-explanatory
+changes: a typo, a one-line guard, a dependency bump, a copy or style tweak, or a
+small localized fix. Size alone does not make a PR deep.
+
+Adequate design context states:
+
+- **Intent:** the problem and why this approach;
+- **Before and after:** the important behavior, UI flow, or API shape on each
+ side;
+- **Compatibility and risk:** affected Canvas modes, stored state, and supported
+ backends, and what can break; and
+- **Code references:** links to the real code at a commit SHA.
+
+Put it in the PR description, or link a `.pr/` design doc that covers it from
+the `pr-design-doc` skill. Count a `.pr/` doc only when the link is pinned to a
+commit SHA, not the branch name. Approving a same-repository PR runs the
+`PR Artifacts` cleanup, which removes `.pr/` from the branch, so a branch link
+stops resolving before a human maintainer reads it, while a SHA link keeps
+working.
+
+Scale the response to the risk assessment:
+
+- **Deep and πŸ”΄ HIGH risk without adequate context:** submit **COMMENT** and ask
+ for the write-up or a SHA-pinned doc.
+- **Deep and 🟑 MEDIUM risk:** ask for it when the change is hard to reconstruct
+ from the diff; a small, self-evident change does not need it.
+- **🟒 LOW risk:** never withhold approval for missing design context.
+
+Design context is a review aid, not a merge gate by itself. It does not excuse a
+correctness, security, compatibility, or architecture defect.
+
## Dependencies and Releases
- Direct dependencies are exact-pinned. Update `package.json` and
diff --git a/.agents/skills/pr-design-doc/SKILL.md b/.agents/skills/pr-design-doc/SKILL.md
index 62f02c6a67..e5ef5066b0 100644
--- a/.agents/skills/pr-design-doc/SKILL.md
+++ b/.agents/skills/pr-design-doc/SKILL.md
@@ -48,8 +48,10 @@ cleanup, verify that the target repository has an enabled
- Fork PR, or repository without a verified cleanup workflow: remove `.pr/` manually before
merge.
-The design doc is a review aid that lives with the branch while the PR is open. It must not
-ship in the merged tree.
+The design doc is a temporary review aid and must not ship in the merged tree. Automated
+approval can trigger cleanup before human review. Keep the essential design summary in the
+PR description: intent, important before/after behavior or API shape, compatibility, risk,
+and code references. Use commit-pinned document links so cleanup does not break access.
## Workflow
@@ -102,17 +104,21 @@ ship in the merged tree.
git add .pr/design.html
git commit -m "docs(.pr): design doc for <PR topic>"
git push <head-repo-remote> HEAD:<headRefName>
+ git rev-parse HEAD
```
- Query the base repository's visibility before choosing the link:
+ Use the resulting full SHA as `<doc-commit-sha>` in document links. Refresh the document
+ and its link when substantive changes affect the design; a cleanup-only commit does not
+ need a new link. Query the base repository's visibility before choosing the link:
```bash
gh repo view <base-owner>/<base-repo> --json visibility,url
```
- **Public repository:** add an htmlpreview link near the top of the PR description,
- pointing at the **fork and branch the PR is opened from** (it renders before merge):
+ pointing at the **PR head repository and commit containing the document**:
```
- πŸ“„ Design doc: https://htmlpreview.github.io/?https://github.com/<fork-owner>/<repo>/blob/<pr-branch>/.pr/design.html
+ πŸ“„ Design doc: https://htmlpreview.github.io/?https://github.com/<fork-owner>/<repo>/blob/<doc-commit-sha>/.pr/design.html
```
- - **Private or internal repository:** link the access-controlled GitHub blob and include
+ - **Private or internal repository:** link the access-controlled GitHub blob at the same
+ document commit and include
local download/open instructions, or use an existing access-controlled artifact
service. Never send the document through htmlpreview or another public host.
diff --git a/.agents/skills/pr-design-doc/references/html-craft.md b/.agents/skills/pr-design-doc/references/html-craft.md
index 974a9c6490..58cf8c4d84 100644
--- a/.agents/skills/pr-design-doc/references/html-craft.md
+++ b/.agents/skills/pr-design-doc/references/html-craft.md
@@ -290,16 +290,18 @@ directory, then build the link and paste it in the PR description:
```bash
# commit the html under .pr/ on your PR branch (this dir is temporary, see the skill)
git add .pr/design.html && git commit -m "docs(.pr): design doc" && git push <your-fork> <branch>
-# link template - use YOUR fork + PR branch, so it renders before the PR is merged:
-# https://htmlpreview.github.io/?https://github.com/<fork-owner>/<repo>/blob/<pr-branch>/.pr/design.html
+# use the full SHA of the pushed document commit in the link:
+git rev-parse HEAD
+# https://htmlpreview.github.io/?https://github.com/<fork-owner>/<repo>/blob/<doc-commit-sha>/.pr/design.html
```
Example shape:
-`https://htmlpreview.github.io/?https://github.com/FORK_OWNER/REPO/blob/PR_BRANCH/.pr/design.html`
+`https://htmlpreview.github.io/?https://github.com/FORK_OWNER/REPO/blob/DOC_COMMIT_SHA/.pr/design.html`
-`<pr-branch>` can be any branch or commit - `raw.githubusercontent.com` serves it regardless
-of merge state, so the doc renders while the PR is still open. Point the URL at the **fork
-and branch the PR is opened from**, not `main`.
+Point the URL at the **PR head repository and full commit SHA containing the document**.
+A branch-based link breaks when `.pr/` is removed after approval; a commit-pinned link
+continues to reference the document before cleanup. Refresh the document and its link when
+substantive changes affect the design.
For public repositories, anyone can open the rendered page without a download or local server.
This works with self-contained pages containing only inline CSS and SVG.
@@ -310,8 +312,9 @@ This works with self-contained pages containing only inline CSS and SVG.
the design doc to GitHub Pages or another public host. Keep the document free of external
scripts and assets: opening a local file does not make third-party active content private.
-- Link authorized reviewers to the committed GitHub blob and ask them to download and open the
- self-contained HTML file locally; or use an existing access-controlled artifact service.
+- Link authorized reviewers to the GitHub blob at the full document commit SHA and ask them to
+ download and open the self-contained HTML file locally; or use an existing access-controlled
+ artifact service.
- For a local browser preview, open `.pr/design.html` directly. If the browser needs HTTP,
serve only on loopback:
```bash