Importance-weight the review/ticket/epic rubric (arch/placement #1)

Context

Directed by @tobiu after the #14298 review: I (cross-family) approved a Chroma-freeze fix that dropped ~90 LOC of probe logic into taskDefinitions.mjs (a definitions file) and scored [ARCH_ALIGNMENT] 94 (−6 for a debounce nit). The placement violation — logic in a definitions file — never entered the score. It passed because the file already held probe/build logic (probeTcpPort, buildOllamaServeEnv): "matches local precedent" → LGTM. That is the generating function of the ai/-folder debt (now ~2/10): reviewers match local (bad) precedent, debt compounds, nothing is weighed against an architecture.

The root issue is the rubric, not just my application of it. pr-review-guide §3 scores 7 flat, unweighted metrics and surrounds them with heavy AC / Contract-Ledger / Evidence / CI audit machinery — optimizing reviewer attention toward AC/evidence theater while the most-important axis (does this belong here?) gets rubber-stamped.

The Problem

Three coupled defects in the review/ticket/epic substrate:

1. No importance weighting. The 7 metrics are flat. @tobiu's correction: weight by importance to the merge verdict, NOT by effort (a diff review can be effortful yet still only 30% of what decides the merge). Target importance split:

   • 30% — "right thing to build?" (premise / §0 patch-blind snapshot — today a preamble, not a weighted axis)
   • 30% — "what belongs where?" ([ARCH_ALIGNMENT], explicitly including placement / cohesion / folder-fit / boundaries)
   • 30% — the diff (correctness)
   • 10% — ACs (a light scope-dilution sanity check)

2. [ARCH_ALIGNMENT] omits placement. Today it reads "follows Neo paradigms (worker delegation, reactivity, config-driven)" — it never asks does this code belong in this file/folder? So #14298 scored 94 on a placement violation. Under the corrected definition it is ~45.

3. A+FU is treated as merely "least-desirable" when it is the WORST outcome. Approve+Follow-Up spawns the micro-ticket flood → a ~7-min CI wait per iteration → reviews-of-PR-body-updates-as-rejections → hardcore negative ROI (established 2026-06-27, around #14263). The AC/Contract-Ledger machinery is team-built, not operator-mandated, and is abused for rubber-stamp review theater.

Underlying bar @tobiu set: we strive for outstanding quality + architecture, and we do not increase DEBT. Debt = a "quick win" that needs 2–3× more tickets to fix later — hardcore negative ROI. A debt-creating quick-win is a Request-Changes / reject, not an Approve(+FU).

The Architectural Reality

• [ARCH_ALIGNMENT] definition + the flat 7-metric rubric + decile anchors: .agents/skills/pr-review/references/pr-review-guide.md §3.
• Metric-scoring surfaces in the templates: .agents/skills/pr-review/assets/pr-review-template.md (full) + the follow-up template (§3.3 Metrics Delta).
• A+FU framing: pr-review-guide §9 Strategic-Fit Step-Back (currently "least-desirable").
• The AC/Evidence/Contract-Ledger weight: pr-review-guide §5.2 (Close-Target), §5.4 (Contract Completeness), §7.5/§7.6 (Test/CI audits), the Evidence-Audit template section.
• Ticket/epic mirror: ticket-create-workflow.md §2 (six-stage chain — premise/prescription/substrate already lead) + .agents/skills/epic-create/.
• Progressive Disclosure (ticket-create §1b): the weighting rule body lands in these references/ payloads + assets/ templates (Atlas), NOT the top-level SKILL.md routers (Map). Net always-loaded bytes stay flat-or-lower (the weighting replaces the implicit flat rubric; the A+FU strengthening is a few words).

The Fix

1. pr-review-guide §3: add an explicit Importance Weighting — premise 30 / arch-incl-placement 30 / diff 30 / ACs 10 — with a one-line caveat: weights are importance-to-the-verdict, not an effort budget.
2. [ARCH_ALIGNMENT] definition: extend to "…and does this code belong here? — placement, cohesion, single-responsibility, folder-fit, and boundary discipline (logic out of definitions/config files; no provider-specifics outside the provider layer; no subsystem leaking into shared surfaces like the root package.json)." Add a decile note: a placement violation caps [ARCH_ALIGNMENT] regardless of correctness.
3. pr-review-guide §9: re-rank A+FU as the WORST outcome with the negative-ROI rationale; add the corollary — a debt-creating quick-win is Request-Changes/reject, not A+FU; prefer in-PR fix or clean Approve.
4. Demote the AC machinery to ~10%: keep the scope-dilution/over-claim sliver (the genuine catch — e.g. the #14296 dataDir reconciliation), trim the Close-Target/Contract-Ledger/Evidence sections from "effort sinks" to "fast sanity checks," explicitly marked low-importance.
5. Mirror into ticket-create §2 + epic-create: a ticket's "right thing + right place" is the same 60% — make premise + substrate/placement the dominant gate, ACs a checklist not the point.
6. Templates: update the metrics section (full / follow-up / cycle-1) to render the weights + the placement-inclusive [ARCH_ALIGNMENT].

Decision Record impact

none — skill-discipline substrate (the review/ticket/epic rubrics), not ADR-governed. Aligned with AGENTS.md §self_evolving_systems (friction→gold) + §contributions_over_commits (quality over commit-velocity).

Acceptance Criteria

• pr-review-guide §3 states the importance weighting (30/30/30/10) and that weights = importance-to-verdict, not effort.
• [ARCH_ALIGNMENT] explicitly includes placement / cohesion / folder-fit / boundaries; a placement violation demonstrably caps the score (worked example: #14298 would be ~45, not 94).
• pr-review-guide §9 ranks A+FU as the worst outcome with the negative-ROI rationale + the debt-quick-win → Request-Changes corollary.
• The AC/Contract-Ledger/Evidence sections are explicitly marked ~10%-importance (sanity-check, not effort-sink); the scope-dilution sliver is preserved.
• ticket-create §2 + epic-create mirror the premise+placement-dominant weighting.
• The review templates (full / follow-up / cycle-1) render the weights + placement-inclusive [ARCH_ALIGNMENT].
• Net always-loaded SKILL.md router bytes do not increase (rule body in references//assets/ per Progressive Disclosure).

Out of Scope

• The ai/ folder-architecture SSOT + placement-lint tooling — that's the folder-architecture Discussion/epic (forthcoming). This ticket is the review-philosophy substrate; the SSOT/lint is the enforcement substrate (the placement-vs-SSOT review rule forward-references it).
• Deleting the AC/Contract-Ledger machinery — we demote + slim, not delete.
• Decomposing any beast file or relocating any ai/ code.

Avoided Traps

• Effort-as-weight: the weights are importance, not a time budget — state it, or reviewers mis-read a heavy diff as "deserving" a high arch score.
• SKILL.md router bloat: rule body goes in references//assets/ (Progressive Disclosure); routers get at most a trigger-line delta.
• AC-nihilism: ACs aren't worthless — the scope-dilution sliver is a real catch; demote, don't delete.

Related

• #14298 (the worked example — [ARCH_ALIGNMENT] 94 that should've been ~45)
• #14263 (right-sized PR review / micro-ticket-flood — CLOSED prior; this is the rubric-level evolution)
• #14039 (v13.1 immune system — quality-bar context)
• The ai/ folder-architecture Discussion (forthcoming sibling — the enforcement-SSOT half)

Live latest-open sweep: checked latest 20 open issues at creation; no equivalent found (closest #14263, CLOSED).

Origin Session ID: f4454a29-afc5-4897-a66c-a8c2c9460d55

Handoff Retrieval Hints: "review rubric importance weighting premise placement"; "ARCH_ALIGNMENT what-belongs-where placement"; "A+FU worst outcome micro-ticket flood negative ROI".

Authored by Grace (@neo-opus-grace, Claude Opus 4.8) as the architecture lane; implementation open — I'll cross-family review the PR.