Deck: The answer to "why does this work this way?" already exists. It's in a ticket, a thread, or a PR comment from six weeks ago. Here's how to stop losing it.
What this article solves
Linear tickets hold the reasoning behind your code: the constraint, the tradeoff, the rejected alternative. This guide shows backend engineers how to connect that ticket context to living documentation so the next person who asks "why did we build it this way?" gets an answer in seconds, not a DM chain.
Who this is for: ICs shipping features who need to trace decisions without archaeology.
The question that keeps coming back
It was 9:14 on a Monday morning. Priya, a backend engineer three months into the team, posted in #backend-platform: "Hey, quick question about the rate limiter on the billing service. Is the per-tenant cap intentional or a leftover from the old plan?"
Someone answered her. Twelve minutes later, someone else answered her. The correct answer was the second one.
The correct answer had also been given to the previous engineer who asked, in October, in the same channel. And before that, it lived in LIN-2047, a Linear ticket from August titled "Billing rate limiter: cap strategy per tenant." That ticket had a comment from the staff engineer who designed it, explaining exactly why the cap was tenant-scoped and not global, with a link to the PR where the decision was implemented.
Nobody connected those three things. So the question keeps coming back.
Why Linear tickets are your best undocumented source
A Linear ticket at the moment of implementation contains things no README ever will: the original constraint, the alternative that was rejected, the edge case someone flagged in a comment, the product requirement that forced the tradeoff.
By the time the PR merges, that context is already aging. By the time someone writes a wiki page, half of it is paraphrased from memory. By the time a new engineer joins, it is gone.
The ticket is not the problem. The gap between the ticket and the code, and between the code and anything a future engineer can read, is the problem.
Linear tickets are rich with decision context. They are almost never treated as a documentation source.
Three things that make ticket context disappear
The ticket closes. Status moves to Done, the team moves to the next sprint, and nobody looks at LIN-2047 again. The information is technically still there. Nobody knows to look.
The PR doesn't reference the reasoning. A PR description might say "implements rate limiter per LIN-2047" but it rarely explains the why in a way that survives a code search six months later. The comment thread in the ticket does. The PR does not.
The Slack thread is the real ADR. The actual decision, the back-and-forth, the moment the staff engineer said "global cap won't work because of tenant isolation requirements," happened in a thread. Threads are not searchable in any useful way. They are not linked to the ticket or the PR. They evaporate.
Three artifacts, three places, zero connection.
A workflow that keeps the context alive
The fix is not to write more documentation. It is to capture what already exists and link it.
1. Write the reasoning in the ticket before you close it.
Before moving a ticket to Done, add one comment: what was decided, what was rejected, and why. Two to four sentences. This takes three minutes and it is the most durable form of context you can create. Future engineers can find a ticket. They cannot find a Slack thread from October.
2. Reference the ticket in the PR description, not just the title.
"Closes LIN-2047" is a link. It is not context. Write one sentence in the PR description that summarizes the decision the ticket documents. "Rate limiter scoped per tenant (not global) per LIN-2047; global cap would break tenant isolation in multi-plan accounts." Now the code and the reasoning are in the same place.
3. Let the tooling do the rest.
This is where the gap closes automatically. ScopeDocs connects Linear, GitHub, and Slack so the decision captured in LIN-2047, the PR that implemented it, and the thread where the tradeoff was argued get pulled into source-linked documentation that updates as the code changes. No manual wiki. No archaeology.
In practice
The billing rate limiter question gets asked again in January. This time, the engineer searching for the answer types "rate limiter billing" into the team's documentation. The result is a page titled "Billing service: rate limit architecture," generated from LIN-2047 and PR #1183. It shows the tenant-scoped cap, links to the original ticket comment explaining the isolation requirement, and notes the last time the implementation changed.
The page was not written by anyone. It was captured the first time the answer existed, linked to its sources, and kept current when PR #1219 adjusted the cap threshold in December.
Priya does not post in #backend-platform. She reads the doc, follows the link to the ticket, sees the staff engineer's original comment, and moves on.
Checklist: linking ticket context before it disappears
- Add a "decision summary" comment to the ticket before closing it
- Include a one-sentence reasoning note in every PR description that references a Linear ticket
- Flag Slack threads that contain tradeoff discussions and link them in the relevant ticket
- Connect Linear and GitHub so ticket-to-PR links are automatic, not manual
- Review closed tickets for any with substantial comment threads that never made it into docs
- Set a team norm: if someone asks a question in Slack that a ticket already answered, link the ticket in the reply
- Use a tool that generates documentation from ticket and PR context so the capture happens once, not every time someone asks
The answer to Priya's question existed in August. It was in a ticket, a PR, and a Slack thread, and none of them talked to each other. The goal is not to write better documentation. It is to stop letting good context die in closed tickets.
ScopeDocs connects Linear, GitHub, and Slack to build that link automatically: capture once, traceable to the source, current as the code moves.