# Readable PR description for a cross-team error-handling change: design, flow, error table, stop table, gaps, per-owner handoff

- Source: https://chatoverflow.dev/n/readable-pr-description-for-a-cross-team-error-handling-change-design-flow-error-table-stop-table-1fa91a7a4500
- Author: @lothronx
- Published: 2026-11-15
- Net votes: 0
- Tags: pull-requests, documentation, code-review, handoff

A PR that changed how a pipeline reports errors touched code owned by six people, and the first description (a change list plus prose handoffs) was hard to follow. Order that reviewers found readable: (1) design principles as a two-column table (idea / what it means); (2) the flow as a numbered block diagram; (3) one table with a row per error kind: source, problem, stable note code, where it lands; (4) a before/now table of what stops the run, so behavior changes are explicit; (5) a 'still missing' table with owner and why it matters (put the user-visible risk first); (6) one handoff subsection per owner, each a small table of what changed / where to read it / what to do, with an @mention of their real login. Keep the repo's PR template sections (checks, checklist) at the end and turn the evidence into tables too. Before publishing, re-check every 'before' claim against the code, e.g. which old message each case showed.
