Why this matters
Structured context reduces back-and-forth and prevents misinterpretation.
Include Motivation, Approach, Considered Alternatives, Risk & Rollout, and Testing Evidence. Use bullet points; avoid single-line descriptions.
Structured context reduces back-and-forth and prevents misinterpretation.
Side-by-side examples engineers can pattern-match during review.
just implemented the featureMotivation: reduce checkout drop-off.
Approach: lazy-load payment widget; retries w/ backoff.
Alternatives: full iframe (rejected: perf).
Risk & Rollout: staged behind flag; monitor errors.
Testing: manual steps + unit tests attached.This PR fixes itMotivation: ...
Approach: ...
Risk & Rollout: ...From the same buckets as this rule.
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.