diff --git a/docs/src/content/docs/pt-br/studies/sentry-pr-review-friction-and-adr-pack.mdx b/docs/src/content/docs/pt-br/studies/sentry-pr-review-friction-and-adr-pack.mdx new file mode 100644 index 00000000..09765ac8 --- /dev/null +++ b/docs/src/content/docs/pt-br/studies/sentry-pr-review-friction-and-adr-pack.mdx @@ -0,0 +1,251 @@ +--- +title: "Estudo: atrito em PRs do Sentry e padronização de ADRs" +description: "Estudo de 90 dias sobre pull requests em getsentry/sentry: onde o vai-e-volta de review se concentra e quais ADRs/regras podem reduzir discussões repetidas." +--- + +# Estudo: atrito em PRs do Sentry e padronização de ADRs + +## Objetivo + +Este estudo avalia onde o vai-e-volta de review se concentra em [`getsentry/sentry`](https://github.com/getsentry/sentry) e identifica quais Architecture Decision Records (ADRs) e regras aplicáveis podem reduzir ciclos de discussão repetidos. + +O objetivo não é eliminar revisão humana, e sim levar debates repetitivos e previsíveis para decisões explícitas e política verificável por máquina. + +## Estudo completo + +Leia a publicação canônica (metodologia, métricas, índice de ADRs) em: + +- [**Visão geral — atrito em PRs do Sentry**](https://studies.archgate.dev/studies/sentry-pr-review-friction/) — mesmo conteúdo que as páginas narrativas em [`archgate/studies`](https://github.com/archgate/studies) + +## Escopo e método + +Alinhado à [metodologia](https://studies.archgate.dev/studies/sentry-pr-review-friction/methodology/) do estudo publicado: + +| Conjunto de dados | Contagem | +| -------------------------- | -------------------------------------------------- | +| PRs mesclados | 500 | +| PRs fechados sem merge | 500 | +| PRs abertos amostrados | 251 | +| Análise profunda de coment | 60 PRs de alto atrito (50 mesclados + 10 fechados) | +| Comentários coletados | 965 no total (604 não-bot) | + +Os dados vêm da API do GitHub (veja a página de metodologia para comandos `gh` exatos, pontuação de atrito e limitações). + +### Reprodutibilidade e revisão por pares + +Tudo abaixo está auditado em **[`archgate/studies`](https://github.com/archgate/studies)**: + +| O quê | Onde no GitHub | +| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Script e artefatos gerados | [`studies/sentry-pr-review-friction/`](https://github.com/archgate/studies/tree/main/studies/sentry-pr-review-friction) (ex.: [`analyze_sentry_prs.py`](https://github.com/archgate/studies/blob/main/studies/sentry-pr-review-friction/analyze_sentry_prs.py), [`output/`](https://github.com/archgate/studies/tree/main/studies/sentry-pr-review-friction/output)) | +| Dicionário de temas (codificação) | [`theme_dictionary.json`](https://github.com/archgate/studies/blob/main/studies/sentry-pr-review-friction/theme_dictionary.json) | +| Fonte do site publicado (MDX) | [`src/content/docs/studies/sentry-pr-review-friction/`](https://github.com/archgate/studies/tree/main/src/content/docs/studies/sentry-pr-review-friction) | +| Propostas de ADR e regras complementares | [`proposed-adrs/`](https://github.com/archgate/studies/tree/main/studies/sentry-pr-review-friction/proposed-adrs) e [`proposed-lint-rules/`](https://github.com/archgate/studies/tree/main/studies/sentry-pr-review-friction/proposed-lint-rules) | + +### Métricas usadas + +- Eventos de review por PR +- Parcela de PRs com pedidos formais repetidos de alteração +- Mediana/p75/p90 de tempo até merge +- Diferença de atrito entre PRs grandes e pequenos +- Frequência de temas em threads de alto atrito + +## Achados de linha de base (resumo) + +Os números acompanham a **[visão geral publicada](https://studies.archgate.dev/studies/sentry-pr-review-friction/)** (janela de 90 dias terminando em abril de 2026). Tabelas completas em [métricas de linha de base](https://studies.archgate.dev/studies/sentry-pr-review-friction/baseline/). + +### Ressalva de cobertura + +Só PRs mesclados podem omitir **ambiguidade de decisão**: PRs com muita discussão fechados sem merge e PRs abertos **estagnados**. O estudo publicado inclui coortes fechadas e abertas; veja [PRs abandonados](https://studies.archgate.dev/studies/sentry-pr-review-friction/abandoned/). + +### Perfil de atrito no repositório + +- **Tempo mediano até merge:** ~`4.98h`; **P90** ~`70.54h` (~14× a mediana) +- **Tamanho do PR é o principal preditor de atrito:** PRs grandes (≥10 arquivos ou ≥400 de churn) entram no quartil de alto atrito em **~57%** dos casos vs **~10%** para PRs minúsculos + +Uma taxa baixa de `CHANGES_REQUESTED` formal não significa pouco retrabalho—muitos ciclos ficam nos comentários. + +### Tamanho importa (PRs mesclados) + +- **PRs grandes** (limiar acima): TTM mediano **~22.5h** +- **PRs minúsculos:** TTM mediano **~1.7h** + +PRs grandes são minoria, mas dominam o custo de review. + +### Domínios, escopo e temas + +O estudo detalha atrito por domínio, escopo do título do commit (`feat` vs `fix`, etc.) e temas de discussão a partir de **604 comentários não-bot** em **60** PRs de alto atrito—veja [temas](https://studies.archgate.dev/studies/sentry-pr-review-friction/themes/) e [mapa de atrito](https://studies.archgate.dev/studies/sentry-pr-review-friction/friction-map/). + +## PRs abandonados e estagnados + +A análise inclui **500** PRs fechados sem merge e **251** PRs abertos (estagnação 14+ / 30+ dias), conforme a [metodologia](https://studies.archgate.dev/studies/sentry-pr-review-friction/methodology/). + +Na visão geral publicada: + +- **12** PRs fechados sem merge (**2.4%**) tinham **≥10** itens de discussão; esses casos **abandonados** mostram **~2×** TTM mediano e **~2.5×** eventos de review vs PRs mesclados de alto atrito +- **92** PRs abertos estagnados há **14+** dias; **33** há **30+** dias (exemplo estagnado mais discutido: **55** eventos de review) + +Se você mede só PRs mesclados, a governança pode parecer mais saudável do que é. Trate coortes fechadas sem merge e abertas estagnadas como métricas de primeira classe—detalhes em [**PRs abandonados**](https://studies.archgate.dev/studies/sentry-pr-review-friction/abandoned/). + +## Exemplos de PRs de alto atrito + +Estes exemplos ilustram onde os ciclos de discussão tendem a se repetir: + +- [#111160](https://github.com/getsentry/sentry/pull/111160) + `43` eventos de review, `114.8h` até merge +- [#111192](https://github.com/getsentry/sentry/pull/111192) + `25` eventos de review, `144.2h` até merge +- [#111306](https://github.com/getsentry/sentry/pull/111306) + `23` eventos de review, `75.2h` até merge +- [#111454](https://github.com/getsentry/sentry/pull/111454) + `20` eventos de review +- [#110956](https://github.com/getsentry/sentry/pull/110956) + `18` eventos de review, `187.1h` até merge + +## O que se repete no review + +Na análise profunda de alto atrito, discussões repetidas se concentraram em: + +- **Semântica de API/contrato** (`13/15` PRs de alto atrito) +- **Tipo/nullabilidade e tratamento de erro** (`13/15`) +- **Invariantes de UX/fluxo** (`10/15`) +- **Expectativas de evidência de teste** (`9/15`) +- **Casos extremos de desempenho/confiabilidade** (`5/15`) +- **Barreiras de permissão/segurança** (`3/15`) +- **Divisão de escopo e limites de follow-up** (`4/15`) + +São exatamente decisões de equipe que ADRs podem codificar e regras podem fazer cumprir. + +## Pacote de ADRs proposto para o Sentry + +O conjunto fundamentado em evidências—com ADRs em Markdown, arquivos `.rules.ts` e artefatos de lint—está indexado no site do estudo em [**Propostas de ADR**](https://studies.archgate.dev/studies/sentry-pr-review-friction/adr-proposals/) e em [`archgate/studies` em `proposed-adrs/`](https://github.com/archgate/studies/tree/main/studies/sentry-pr-review-friction/proposed-adrs). + +A narrativa abaixo está priorizada pela redução esperada de atrito em review. + +## 1) ADR: limites de fatia de PR e orçamento de risco + +**Problema:** PRs grandes ou de escopo misto geram threads longas e ciclos de merge lentos. +**Decisão:** Impor gatilhos de decomposição antes do review começar. + +### Regras candidatas + +- Falhar ou avisar quando o PR cruza frontend e backend sem justificativa explícita de exceção. +- Avisar/falhar se churn ou contagem de arquivos exceder limiar, salvo exceção aprovada. +- Exigir issue de follow-up vinculada para trabalho adiado de propósito. + +### Por que ajuda + +Move “por favor divida este PR” de negociação no review para política pré-review. + +## 2) ADR: protocolo de evolução de contrato de API + +**Problema:** Vai-e-volta repetido sobre formato de resposta, mudanças de comportamento e compatibilidade. +**Decisão:** Mudanças com impacto em contrato devem declarar compatibilidade e plano de rollout. + +### Regras candidatas + +- Se a superfície de API for tocada, o corpo do PR deve incluir seção **impacto na API**. +- Exigir tipo de compatibilidade: `none`, `backward-compatible` ou `breaking`. +- Exigir notas de migração quando compatibilidade não for `none`. + +### Por que ajuda + +Remove ambiguidade sobre “isso muda contrato?” e “qual é o raio de explosão?”. + +## 3) ADR: matriz de evidência de teste por tipo de mudança + +**Problema:** Revisores pedem repetidamente profundidade de teste e prova de risco. +**Decisão:** Definir evidência obrigatória por classe de mudança. + +### Regras candidatas + +- Mudanças de feature que tocam API + UI exigem evidência backend e frontend. +- Mudanças de segurança/permissão exigem testes de autorização positivos e negativos. +- Mudanças de fluxo de comportamento exigem teste de fluxo ou nota de exceção explícita. + +### Por que ajuda + +Padroniza requisitos de prova antes de o revisor precisar pedir. + +## 4) ADR: invariantes comportamentais de UI/fluxo + +**Problema:** Muitos comentários giram em torno de navegação, transições de estado e correção de fluxo do usuário. +**Decisão:** PRs que mudam fluxo devem declarar e validar invariantes comportamentais. + +### Regras candidatas + +- Exigir seção “comportamento antes/depois” para componentes relacionados a fluxo. +- Exigir screenshot/vídeo para mudanças significativas de UX. +- Exigir declaração explícita de tratamento de estado vazio/erro. + +### Por que ajuda + +Converte loops subjetivos de review de UX em contratos de comportamento explícitos. + +## 5) ADR: barreiras de permissão e confiabilidade + +**Problema:** Review tardio pega checagens de auth, segurança de memória e bordas de confiabilidade. +**Decisão:** Codificar proteções inegociáveis para caminhos sensíveis. + +### Regras candidatas + +- Mudanças de endpoint em domínios sensíveis exigem declaração explícita de checagem de permissão. +- Detectar antipadrões conhecidos em lógica de auth em curto-circuito. +- Sinalizar operações de risco de memória em código de provider/integração. + +### Por que ajuda + +Reduz comentários de risco evitáveis em estágio tardio e correções críticas. + +## Matriz de priorização (impacto vs esforço) + +| ADR | Impacto esperado no atrito de review | Esforço de implementação | Prioridade | +| ------------------------------------------- | ------------------------------------ | ------------------------ | ---------- | +| Limites de fatia de PR e orçamento de risco | Alto | Baixo–médio | P0 | +| Protocolo de evolução de contrato de API | Alto | Médio | P0 | +| Matriz de evidência de teste | Alto | Baixo | P0 | +| Invariantes comportamentais de UI/fluxo | Médio–alto | Médio | P1 | +| Barreiras de permissão e confiabilidade | Médio–alto | Médio–alto | P1 | + +## Rollout sugerido de enforcement + +### Fase 1: template + gate leve em CI (maior ROI rápido) + +- Expandir template de PR com seções obrigatórias: + - tipo de mudança + - impacto na API + - matriz de evidência de teste + - risco e rollback + - links de issues de follow-up +- Adicionar checagem em CI que falha se seções obrigatórias faltarem conforme padrões de arquivo alterados. + +### Fase 2: política de escopo e tamanho + +- Limiares de divisão de PR (contagem de arquivos/churn e checagens cross-domain). +- Rótulos de exceção com justificativa obrigatória. + +### Fase 3: checagens estáticas mais profundas + +- Checagens direcionadas para barreiras de auth, nullabilidade/caminhos de erro e armadilhas comuns de confiabilidade. + +## Metas de KPI (para validar valor dos ADRs) + +Acompanhar antes/depois por pelo menos 6 semanas: + +- p90 de eventos de review por PR +- parcela de PRs com >10 eventos de review +- tempo mediano até merge para PRs grandes +- parcela de PRs sem seções de evidência obrigatórias +- frequência de comentários de review que mapeiam para tópicos já governados por ADR + +Metas iniciais razoáveis: + +- redução de `20–35%` no volume de eventos de review de alto atrito +- redução de `15–25%` no tempo mediano até merge de PRs grandes +- declínio claro em comentários de review repetidos de política + +## Conclusão principal + +A principal ineficiência não é qualidade de código em geral. É **tomada de decisão repetida no review** para problemas previsíveis e padronizáveis. + +Em escala tipo Sentry, ADRs no estilo Archgate mais enforcement de regras são um bom encaixe para tirar esses debates recorrentes das threads de PR e colocá-los em governança explícita e reutilizável. diff --git a/docs/src/content/docs/studies/sentry-pr-review-friction-and-adr-pack.mdx b/docs/src/content/docs/studies/sentry-pr-review-friction-and-adr-pack.mdx new file mode 100644 index 00000000..5bfb3066 --- /dev/null +++ b/docs/src/content/docs/studies/sentry-pr-review-friction-and-adr-pack.mdx @@ -0,0 +1,251 @@ +--- +title: "Study: Sentry PR Friction and ADR Standardization" +description: "A 90-day pull request study of getsentry/sentry showing where review back-and-forth clusters and which ADRs/rules could reduce repeat discussion." +--- + +# Study: Sentry PR Friction and ADR Standardization + +## Objective + +This study evaluates where review back-and-forth is concentrated in [`getsentry/sentry`](https://github.com/getsentry/sentry) and identifies which Architecture Decision Records (ADRs) plus enforceable rules could reduce repeated discussion cycles. + +The goal is not to remove human review. The goal is to move repeated and predictable review debates into explicit decisions and machine-checkable policy. + +## Full study + +Read the canonical publication (methodology, metrics, ADR index) at: + +- [**Sentry PR review friction — overview**](https://studies.archgate.dev/studies/sentry-pr-review-friction/) — same content as the [`archgate/studies`](https://github.com/archgate/studies) narrative pages + +## Scope and method + +Aligned with the live study’s [methodology](https://studies.archgate.dev/studies/sentry-pr-review-friction/methodology/): + +| Dataset | Count | +| --------------------- | ----------------------------------------------------- | +| Merged PRs | 500 | +| Closed-unmerged PRs | 500 | +| Open PRs sampled | 251 | +| Deep comment analysis | 60 high-friction PRs (50 merged + 10 closed-unmerged) | +| Comments collected | 965 total (604 non-bot) | + +Data is collected via the GitHub API (see the methodology page for exact `gh` commands, friction scoring, and limitations). + +### Reproducibility and peer review + +Everything below is audited in **[`archgate/studies`](https://github.com/archgate/studies)**: + +| What | Where on GitHub | +| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Method script and generated artifacts | [`studies/sentry-pr-review-friction/`](https://github.com/archgate/studies/tree/main/studies/sentry-pr-review-friction) (e.g. [`analyze_sentry_prs.py`](https://github.com/archgate/studies/blob/main/studies/sentry-pr-review-friction/analyze_sentry_prs.py), [`output/`](https://github.com/archgate/studies/tree/main/studies/sentry-pr-review-friction/output)) | +| Theme dictionary (deterministic coding) | [`theme_dictionary.json`](https://github.com/archgate/studies/blob/main/studies/sentry-pr-review-friction/theme_dictionary.json) | +| Published site source (MDX) | [`src/content/docs/studies/sentry-pr-review-friction/`](https://github.com/archgate/studies/tree/main/src/content/docs/studies/sentry-pr-review-friction) | +| ADR proposals and companion rules | [`proposed-adrs/`](https://github.com/archgate/studies/tree/main/studies/sentry-pr-review-friction/proposed-adrs) and [`proposed-lint-rules/`](https://github.com/archgate/studies/tree/main/studies/sentry-pr-review-friction/proposed-lint-rules) | + +### Metrics used + +- Review events per PR +- Share of PRs with repeated formal change requests +- Median/p75/p90 time-to-merge +- Large-PR vs small-PR friction delta +- Theme frequency in high-friction discussion threads + +## Baseline findings (summary) + +Figures here track the **[published study overview](https://studies.archgate.dev/studies/sentry-pr-review-friction/)** (90-day window ending April 2026). See that page and [baseline metrics](https://studies.archgate.dev/studies/sentry-pr-review-friction/baseline/) for full tables. + +### Important coverage caveat + +Merged PRs alone can miss **decision ambiguity**: high-discussion PRs closed without merge, and **stale** open PRs. The live study includes closed-unmerged and open cohorts; see [Abandoned PRs](https://studies.archgate.dev/studies/sentry-pr-review-friction/abandoned/). + +### Repo-wide friction profile + +- **Median time-to-merge:** ~`4.98h`; **P90** ~`70.54h` (~14× median) +- **PR size is the strongest friction predictor:** large PRs (≥10 files or ≥400 churn) hit the high-friction quartile **~57%** of the time vs **~10%** for tiny PRs + +A low formal `CHANGES_REQUESTED` rate does not mean low rework—many loops stay in comment threads. + +### Size matters (merged PRs) + +- **Large PRs** (threshold above): median TTM **~22.5h** +- **Tiny PRs:** median TTM **~1.7h** + +Large PRs are a minority but dominate review drag. + +### Domains, scope, and themes + +The study breaks down friction by domain, commit title scope (`feat` vs `fix`, etc.), and discussion themes from **604 non-bot comments** across **60** high-friction PRs—see [themes](https://studies.archgate.dev/studies/sentry-pr-review-friction/themes/) and [friction map](https://studies.archgate.dev/studies/sentry-pr-review-friction/friction-map/). + +## Abandoned and stale PRs + +The analysis includes **500** closed-unmerged PRs and **251** open PRs (with 14+ / 30+ day staleness), per the [methodology](https://studies.archgate.dev/studies/sentry-pr-review-friction/methodology/). + +From the published overview: + +- **12** closed-unmerged PRs (**2.4%**) had **≥10** discussion items; those **abandoned** cases show **~2×** median TTM and **~2.5×** median review events vs merged high-friction PRs +- **92** open PRs are stale **14+** days; **33** stale **30+** days (most-discussed stale example: **55** review events) + +If you only measure merged PRs, governance can look healthier than it is. Treat closed-unmerged and stale-open cohorts as first-class metrics—details on [**Abandoned PRs**](https://studies.archgate.dev/studies/sentry-pr-review-friction/abandoned/). + +## High-Friction PR Examples + +These examples illustrate where discussion loops tend to repeat: + +- [#111160](https://github.com/getsentry/sentry/pull/111160) + `43` review events, `114.8h` time-to-merge +- [#111192](https://github.com/getsentry/sentry/pull/111192) + `25` review events, `144.2h` time-to-merge +- [#111306](https://github.com/getsentry/sentry/pull/111306) + `23` review events, `75.2h` time-to-merge +- [#111454](https://github.com/getsentry/sentry/pull/111454) + `20` review events +- [#110956](https://github.com/getsentry/sentry/pull/110956) + `18` review events, `187.1h` time-to-merge + +## What Gets Repeated in Review + +From the high-friction deep dive, repeated discussions clustered around: + +- **API/contract semantics** (`13/15` high-friction PRs) +- **Type/nullability and error-path handling** (`13/15`) +- **UX/flow behavior invariants** (`10/15`) +- **Test evidence expectations** (`9/15`) +- **Performance/reliability edge cases** (`5/15`) +- **Permission/security guardrails** (`3/15`) +- **Scope splitting and follow-up boundaries** (`4/15`) + +These are exactly the kinds of team decisions that ADRs can encode and rules can enforce. + +## Proposed ADR Pack for Sentry + +The evidence-backed proposal set—with Markdown ADRs, companion `.rules.ts` files, and lint artifacts—is indexed on the study site at [**ADR proposals**](https://studies.archgate.dev/studies/sentry-pr-review-friction/adr-proposals/) and in [`archgate/studies` under `proposed-adrs/`](https://github.com/archgate/studies/tree/main/studies/sentry-pr-review-friction/proposed-adrs). + +The narrative below is prioritized by expected review-friction reduction. + +## 1) ADR: PR Slice Boundaries and Risk Budget + +**Problem:** Large or mixed-scope PRs create long comment threads and delayed merge cycles. +**Decision:** Enforce decomposition triggers before review begins. + +### Candidate rules + +- Fail or warn when PR crosses both frontend and backend without explicit exception rationale. +- Warn/fail if churn or file count exceeds a threshold unless marked as approved exception. +- Require linked follow-up issue for intentionally deferred work. + +### Why this helps + +It moves "please split this PR" from review-time negotiation to pre-review policy. + +## 2) ADR: API Contract Evolution Protocol + +**Problem:** Repeated back-and-forth on response shape, behavior changes, and backward compatibility. +**Decision:** Contract-impact changes must include compatibility declaration and rollout plan. + +### Candidate rules + +- If API surface is touched, PR body must include an **API impact** section. +- Require compatibility type: `none`, `backward-compatible`, or `breaking`. +- Require migration notes when compatibility is not `none`. + +### Why this helps + +It removes ambiguity around "is this a contract change?" and "what is the blast radius?" + +## 3) ADR: Test Evidence Matrix by Change Type + +**Problem:** Reviewers repeatedly ask for test depth and risk proof. +**Decision:** Define mandatory evidence per change class. + +### Candidate rules + +- Feature changes touching API + UI require both backend and frontend evidence. +- Security/permission changes require positive and negative authorization tests. +- Behavior flow changes require flow-level test or an explicit exception note. + +### Why this helps + +It standardizes proof requirements before reviewers need to ask. + +## 4) ADR: UI/Flow Behavioral Invariants + +**Problem:** Many comments resolve around navigation, state transitions, and user-flow correctness. +**Decision:** Flow-changing PRs must state and validate behavioral invariants. + +### Candidate rules + +- Require "before/after behavior" section for flow-related components. +- Require screenshot/video evidence for significant UX flow changes. +- Require explicit empty-state/error-state handling declaration. + +### Why this helps + +It converts subjective UX review loops into explicit behavior contracts. + +## 5) ADR: Permission and Reliability Guardrails + +**Problem:** Late review catches around auth checks, memory safety, and reliability edges. +**Decision:** Codify non-negotiable protections for sensitive paths. + +### Candidate rules + +- Endpoint changes in sensitive domains require explicit permission check declaration. +- Detect known anti-patterns in short-circuit auth logic. +- Flag memory-risky operations in provider/integration code paths. + +### Why this helps + +It reduces avoidable late-stage risk comments and critical fixes. + +## Prioritization Matrix (Impact vs Effort) + +| ADR | Expected impact on review friction | Implementation effort | Priority | +| ------------------------------------- | ---------------------------------- | --------------------- | -------- | +| PR Slice Boundaries and Risk Budget | High | Low-Medium | P0 | +| API Contract Evolution Protocol | High | Medium | P0 | +| Test Evidence Matrix | High | Low | P0 | +| UI/Flow Behavioral Invariants | Medium-High | Medium | P1 | +| Permission and Reliability Guardrails | Medium-High | Medium-High | P1 | + +## Suggested Enforcement Rollout + +### Phase 1: Template + lightweight CI gate (fastest ROI) + +- Expand PR template with required sections: + - change type + - API impact + - test evidence matrix + - risk and rollback notes + - follow-up issue links +- Add CI check to fail if required sections are missing based on changed file patterns. + +### Phase 2: Scope and size policy + +- Add PR-slicing thresholds (file count/churn and cross-domain checks). +- Introduce exception labels with mandatory rationale. + +### Phase 3: Deeper static checks + +- Add targeted checks for auth guardrails, nullability/error-path handling, and common reliability pitfalls. + +## KPI Targets (to validate ADR value) + +Track before/after for at least 6 weeks: + +- p90 review events per PR +- share of PRs with >10 review events +- median time-to-merge for large PRs +- share of PRs missing required evidence sections +- frequency of review comments that map to already-governed ADR topics + +Reasonable initial targets: + +- `20-35%` reduction in high-friction review-event volume +- `15-25%` reduction in large-PR median time-to-merge +- clear decline in repeated policy-level review comments + +## Key Takeaway + +The main inefficiency is not code quality in general. It is repeated decision-making during review for issues that are predictable and standardizable. + +For Sentry-like scale, Archgate-style ADRs plus rule enforcement are a strong fit for moving these recurring debates out of PR threads and into explicit, reusable governance.