PR Hygiene rules

Do not combine mechanical changes (formatting, renames) with behavioral changes. If unavoidable, separate commits and call out which commits are mechanical.

If files under src/ change behavior, the PR must include tests/ updates or a PR description line no-tests: <reason> explaining why tests are unaffected.

If the PR claims to fix a specific issue (e.g., 'Fixes #123' / 'Fix PAY-123'), validate it against the real production error. - If an observability MCP is available (Sentry/Datadog/Bugsnag): fetch the event/stack trace and confirm the change addresses the root cause. - Require a regression test (or a clearly documented reason why a test cannot be added). Call out fixes that only hide symptoms (catch-and-ignore, broader retries, defaulting values) without removing the underlying failure mode.

If an API/contract or behavior is breaking, add a 'BREAKING CHANGE' section detailing what breaks, migration steps, and affected consumers.

Before approving/merging risky changes, check whether there is an active critical production incident. - If an incident/monitoring MCP is available (PagerDuty, Datadog Monitors): query for active Sev1/Sev2 incidents. - If there is an active incident: warn the author and suggest delaying merges/deploys or using an explicit emergency override process.

If the change is risky or user-facing, describe the feature flag, rollout plan (stages/segments), monitoring signals, and a clear rollback procedure.

Provide explicit verification steps (manual or automated), expected vs actual outcomes, and attach any logs or screenshots relevant to the changes.

Emergency access to ePHI must go through a dedicated break_glass path that requires reason, approver, limited time window, and automatic post-incident review. The PR must include changes to the audit log schema and runbook.

If a PR adds new PII fields (e.g., email, phone, address, dob, national_id), include links to updated DPIA and RoPA, migration with retention, and masking rules. Add a checklist item confirming lawful_basis. (GDPR Art. 35, Art. 30)

Provide an authenticated endpoint that assembles a user's data into a structured JSON export and returns a short-lived signed URL (≤24h). Include integration tests in the PR. (GDPR Art. 20)

Ensure the PR title/description honestly reflects what the diff actually changes. Flag out-of-scope changes (behavioral changes hidden as refactors, unrelated dependency bumps, config/security changes) and require either: - splitting into separate PRs, or - an explicit 'Additional changes' section with rationale and risk/rollout notes.

Include Motivation, Approach, Considered Alternatives, Risk & Rollout, and Testing Evidence. Use bullet points; avoid single-line descriptions.

When a PR introduces new PII fields or processing, the PR body must include legal_basis: (e.g., consent, contract) and dpia: (yes/no with link). CI should fail if missing.

If the PR is large (many files/lines), split it into logical chunks or provide a clear justification and review guide listing file groups and what to focus on.

If the PR references a ticket (e.g., 'Refs: ABC-123' or a Linear/Jira/Asana/ClickUp/Trello link), verify the diff covers each Acceptance Criterion. - If a ticketing MCP is available: fetch the ticket and list AC → code/tests mapping. - If no MCP is available or the ticket is inaccessible: ask the author to paste the Acceptance Criteria in the PR description. Flag any missing criteria, unhandled edge cases, or partial implementations before human review.

PR titles must follow the pattern: <scope>: <concise change summary>. Keep it under 72 characters and avoid vague words like 'stuff' or 'minor tweaks'.

Provide a short checklist tailored to this change (e.g., 'logic matches spec', 'docs updated', 'flags in place', 'rollback plan noted').

Tag code owners or subject-matter experts for impacted areas. Include a short 'What to review' section to guide each reviewer.

When altering UI, include before/after screenshots or a short clip demonstrating the change, and note responsive states and accessibility impacts.

If the repo defines a Definition of Done (e.g., `DOD.md`, `CONTRIBUTING.md`), ensure the PR meets it. To enable this check, reference the file path in the PR or ask to review it explicitly. Confirm bureaucratic requirements (docs, tests, design approval, rollout plan) are satisfied or explicitly marked as not applicable.

All production deployments must reference a change ticket ID, peer approval, and linked rollout plan; write the change_id to the audit log on deploy.

When a PR implements or changes a decision, include 'ADR: docs/adr/NNNN-title.md' in the PR description and reference it in the merge commit body.

Reference at least one tracking ID (e.g., JIRA/GitHub issue) in the PR description using a consistent format (e.g., 'Refs: ABC-123').

Do not include commented-out code, unused files, or unrelated snapshots. Keep diffs minimal and relevant to the change.