ticket-and-pr-prose

Write a Linear ticket or a pull request description that a non-engineer understands at the top and an implementing or reviewing engineer can work from at the bottom — one document, sliding from plain language into engineering detail. The method below IS the format, so you never need to open a reference ticket or PR.

The two artifacts share one spine and one set of rules. They differ only in tense (a ticket proposes, a PR reports), in the last few detail sections, and in how you publish them.

The one rule that governs everything: progressive disclosure

A reader starts at the top knowing nothing and stops reading the moment they hit their depth — and must have gotten real value by then. So each section is more technical than the last. A PM reads the first two sections and understands why and where. A staff engineer reads all of it and can implement or review. Never open with jargon; never bury the "why" under the mechanism.

Standalone — no outside references

The document is its own source of truth. Do not reference other tickets, PRs, ADRs by ID, design history, or "the thought process behind this." When sibling work matters, describe it by what it does ("the shared token issuer already shipped with the deployed-app lane"), never by ticket number. A reader with zero context and no other tabs open must fully understand the change.

Two narrow exceptions, both pointers rather than explanation:

• A live delivery-status table may cite the PR or sub-ticket that lands each piece.
• A PR may carry a single ticket link line (Closes ENG-1234) at the very top or bottom. The reviewer must never need to open it — everything they need to review the diff is in the PR body itself.