From b6e57326f4638c21a9de1e4f790b70f072b77060 Mon Sep 17 00:00:00 2001 From: Engel Nyst Date: Fri, 11 Sep 2026 01:47:36 +0200 Subject: [PATCH 1/2] docs(codereview): require design docs for deep, high-risk PRs Add a "Design Docs for Deep PRs" section to the custom code-review guide. It describes the changes a design doc is expected for (new/changed automation contract or webhook/dispatch API, new module/subsystem, cross-cutting refactor or migration, core-behavior changes) and skips trivial PRs. Instructs the reviewer to withhold approval for a deep HIGH-risk PR with no design doc, and to use judgment (prefer withholding) for a deep MEDIUM-risk PR without one. LOW risk never blocks. Ties into the pr-design-doc skill. Co-authored-by: smolpaws Co-authored-by: openhands --- .agents/skills/custom-codereview-guide.md | 34 +++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/.agents/skills/custom-codereview-guide.md b/.agents/skills/custom-codereview-guide.md index 38b36895..e5a37259 100644 --- a/.agents/skills/custom-codereview-guide.md +++ b/.agents/skills/custom-codereview-guide.md @@ -20,6 +20,40 @@ A review that says "Worth merging" but is submitted as COMMENTED does not satisfy the repository's required review gate and leaves the PR blocked indefinitely. Always match your submission action to your verdict. +## Design Docs for Deep PRs + +A diff shows what changed line by line, not the design: the shape of the +change, the API before and after, and why this approach. For a *deep* PR, +expect a short design doc. The `pr-design-doc` skill in +`.agents/skills/pr-design-doc/` produces a self-contained `.pr/` HTML page +(big picture plus before/after, grounded to real code) linked from the PR +description. + +A PR is "deep" when a reviewer cannot fully judge it from the diff in a couple +of minutes, for example: + +- a new or changed automation contract, webhook/event payload, or dispatch API; +- a new module or subsystem, or a cross-cutting refactor or migration; +- a behavior change in core logic (scheduling, run history, dispatch flow). + +Skip it for trivial PRs — a typo, a one-line guard, a config or dependency +bump, a docs tweak, a small localized bug fix. If the diff is its own +explanation, do not ask for a page. + +When a deep PR ships without a design doc, weigh the omission against the +change's risk assessment: + +- **🔴 HIGH risk and deep, no design doc:** withhold approval. Submit the + review as COMMENTED and ask for a design doc (or an equivalent write-up in + the PR description) so a human can judge the proposal before merge. +- **🟡 MEDIUM risk and deep, no design doc:** use judgment. Prefer to withhold + approval and request one when the change is hard to reconstruct from the + diff; a MEDIUM change that is small and self-evident does not need a page. +- **🟢 LOW risk:** never block on a missing design doc. + +A design doc is a review aid, not a merge gate by itself. A well-written doc +does not excuse real correctness, security, or architecture problems. + ## Repository Context This repository uses GitHub branch protection rules that require at least one From 2529f6f178bd38b95841b95c33bd8220a1548cf5 Mon Sep 17 00:00:00 2001 From: Engel Nyst Date: Fri, 11 Sep 2026 01:49:59 +0200 Subject: [PATCH 2/2] docs(codereview): add ~500+ line diff as a deep-PR signal A large diff whose intent a reviewer cannot hold in their head at once is also a case where a design doc helps, even if no single hunk is complex. Co-authored-by: smolpaws Co-authored-by: openhands --- .agents/skills/custom-codereview-guide.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.agents/skills/custom-codereview-guide.md b/.agents/skills/custom-codereview-guide.md index e5a37259..d1da68fe 100644 --- a/.agents/skills/custom-codereview-guide.md +++ b/.agents/skills/custom-codereview-guide.md @@ -34,7 +34,9 @@ of minutes, for example: - a new or changed automation contract, webhook/event payload, or dispatch API; - a new module or subsystem, or a cross-cutting refactor or migration; -- a behavior change in core logic (scheduling, run history, dispatch flow). +- a behavior change in core logic (scheduling, run history, dispatch flow); or +- a large diff (roughly 500+ lines changed) whose intent a reviewer cannot hold + in their head at once, even if no single hunk is complex. Skip it for trivial PRs — a typo, a one-line guard, a config or dependency bump, a docs tweak, a small localized bug fix. If the diff is its own