docs(governance): frame PRs as "push requests" — problem-first evaluation (#62)

Refines the OSS contribution docs around the mindset that a pull request is a
request to push a change, evaluated by "what problem does this solve?" before
the diff.

- PR template: leads with "What problem does this solve?" (was "what does this
  PR do?"); adds a DCO sign-off checklist item.
- CONTRIBUTING.md: new "How we evaluate a PR" section — the 5-rung ladder
  (problem -> scope -> solution -> verifiable -> governance); line-by-line
  review comes after the top three.
- ADR 010: adds decision 9 (Problem-First PR Triage) codifying the ladder as the
  governance evaluation procedure, so review is consistent and delegable.

Docs-only; no code or product change.


Claude-Session: https://claude.ai/code/session_012wU47GVzskAummZqgH6FgF

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: ccross2

.github/pull_request_template.md

@@ -1,3 +1,9 @@
+## What problem does this solve?
+
+<!-- The motivation, not the diff — what's broken, missing, or needed, and for whom.
+     Link the issue if there is one ("Closes #123"). No clear problem yet? Open an
+     issue first (see CONTRIBUTING.md). -->
+
 ## Type
 
 <!-- Check one: -->
@@ -7,23 +13,23 @@
 - [ ] Documentation
 - [ ] Other: <!-- describe -->
 
-## Description
+## What this changes
 
-<!-- What does this PR do? Link related issues with "Closes #123" or "Fixes #456". -->
+<!-- How this PR solves the problem above — the approach, not a line-by-line list. -->
 
 ## Testing
 
-<!-- How did you verify this works?
-     - For quirks: paste `visage discover` output showing the device
-     - For bug fixes: describe the repro and how this fixes it
-     - For packaging: which distro/version did you test on? -->
+<!-- How you verified it works:
+     - Quirks: paste `visage discover` output showing the device
+     - Bug fixes: the repro, and how this fixes it
+     - Packaging: which distro/version you tested on -->
 
 ## Checklist
 
 - [ ] `cargo fmt --all -- --check` passes
 - [ ] `cargo clippy --workspace -- -D warnings` passes
 - [ ] `cargo test --workspace` passes
-- [ ] No new warnings introduced
+- [ ] Commits are signed off (`git commit -s`) per the DCO
 - [ ] I have read [CONTRIBUTING.md](../CONTRIBUTING.md)
 
 ## Breaking changes

CONTRIBUTING.md

@@ -174,6 +174,20 @@ ideas are bad. If you want gestures or voice on Linux, watch the [Esver OS](http
 
 ---
 
+## How we evaluate a PR
+
+A pull request is a request to push a change — we read it from the problem down, not the diff up. In order:
+
+1. **What problem does it solve?** No stated problem, or a solution hunting for one, gets "what's the problem here?" before any code review.
+2. **Is the problem in scope?** See [what we will NOT merge](#what-we-will-not-merge). Out of scope → we decline with the boundary, not the code.
+3. **Is it the right solution?** A real, in-scope problem can still have the wrong fix — we look for the simplest approach that fits the architecture.
+4. **Is it verifiable?** Evidence it works (tests, `visage discover` output, a repro) and green CI.
+5. **Governance** — DCO sign-off, extra review for the auth path, attribution.
+
+Line-by-line review comes after 1–3. So the fastest path to merge is a clear problem statement — and a well-scoped PR gets a fast yes or a fast, kind no, never silence.
+
+---
+
 ## PR guidelines
 
 All PRs are filed against `main`. Use the [PR template](.github/pull_request_template.md)

docs/decisions/010-open-source-contribution-governance.md

@@ -3,6 +3,7 @@
 **Date:** 2026-02-24
 **Status:** Accepted
 **Deciders:** Sovren Software core team
+**Amended:** 2026-07-07 — added §9 (Problem-First PR Triage)
 
 ---
 
@@ -113,7 +114,7 @@ Three issue templates and one PR template standardize contribution quality:
 | Bug report | Structured: environment, repro steps, expected/actual, logs |
 | Hardware report | Mirrors Adopt-a-Laptop format — device info, test results, discovery output |
 | Feature request | Includes scope-check reminder linking the out-of-scope table |
-| PR template | Type checkbox, description, testing evidence, quality gate checklist |
+| PR template | Leads with "What problem does this solve?"; then type, change, testing evidence, DCO + quality-gate checklist |
 
 **Rationale:** The highest-value contributions (hardware quirks) come from users who may
 not be experienced OSS contributors. Templates reduce the back-and-forth from "please add
@@ -140,6 +141,32 @@ and CI-tested before merge.
 looking at this?" pings. Hardware quirks are fast-tracked because each one unlocks support
 for an entire laptop model.
 
+### 9. PR Evaluation: Problem-First Triage
+
+*(Amendment, 2026-07-07.)* A pull request is treated as a **request to push a change** —
+evaluated from the problem down, not the diff up. Every PR (external, dependabot, or
+maintainer) is read through this ladder **before** line-by-line code review:
+
+1. **What problem does it solve?** No stated problem — or a solution hunting for one — is
+   asked "what's the problem here?" before its code is reviewed.
+2. **Is that problem in scope?** Measured against the out-of-scope boundaries in
+   `CONTRIBUTING.md`. Out-of-scope PRs are declined with the boundary, not the code.
+3. **Is it the right solution?** A real, in-scope problem can still have the wrong fix —
+   the bar is the simplest approach that fits the architecture and does not widen the
+   auth/attack surface.
+4. **Is it verifiable?** Evidence (tests, a repro, `visage discover` output) plus green CI.
+5. **Governance** — DCO, security-path review, merge strategy, attribution (§§3–5 above).
+
+**Rationale:** The other decisions here govern *how* a PR is handled (branch protection,
+DCO, CI, timelines); they do not say *how it is judged*. Codifying the problem-first ladder
+makes evaluation consistent and delegable — a maintainer, or an automated agent handling
+routine PRs, applies the same lens, rejects/redirects early on the upper rungs (cheaper for
+us, kinder and faster for the contributor), and escalates only genuine judgment calls:
+scope-edge decisions, anything on the security/auth path, governance waivers, and
+breaking/release-version calls. Surfaced to contributors in `CONTRIBUTING.md`
+("How we evaluate a PR") and in the PR template, which now leads with
+"What problem does this solve?".
+
 ---
 
 ## Consequences