Imported from snoodleboot-io/discrecontinual_equations (.claude/skills/technical-communication/SKILL.md). Install upstream with npx skills add snoodleboot-io/discrecontinual_equations --skill technical-communication. Copyright stays with the author.

Technical Communication (Verbose)

Core Patterns

Audience First, Then Structure

Before writing anything, answer three questions: who reads this, what do they have to do, and what do they already know? The answers change the document completely, not just its tone.

The same migration produces four different first sentences. Writing one document for "everyone" produces a document that serves no one — the executive wades through connection-pool details, and the engineer cannot find the rollback plan.

Bottom Line Up Front

BLUF is a discipline borrowed from military briefing: the first sentence carries the conclusion or the request, and everything after it is supporting evidence that a reader may stop consuming at any point without missing the point.

Most engineers write in discovery order — the order they learned things — which is exactly backwards from the order a reader needs them.

❌ Discovery order
"Last week we started looking into the checkout timeouts. We first tried
raising the connection pool size, which didn't help. Then Priya suggested
profiling the gateway calls, and after some digging it turned out the
retry logic is nesting. We think we can fix it in a couple of days."

✅ BLUF
"Checkout timeouts are caused by unbounded retries in the payment gateway
client. Fix is ~2 days. I need a decision by Wednesday: ship behind a flag
or wait for the Nov 12 release train.

Detail: three nested retry layers (HTTP client, gateway SDK, and our
service wrapper) compound to as many as 27 attempts per checkout. Pool
size was a red herring."

The test: delete everything after the first paragraph. Does the reader still know what happened and what you need? If not, the summary is not a summary.

The Status Update

Status updates are the most-written and worst-written artifact in engineering. The failure mode is narrating effort instead of reporting position.

❌ "Making good progress on the migration. Ran into some issues with the
    legacy adapter but working through them. Should be done soon."

Every clause here is unfalsifiable. "Good progress" is compatible with being 90% done or 20% done. "Soon" is compatible with Thursday or next month. The reader must now schedule a meeting to extract what a sentence could have carried.

✅ Migration — on track for Thu Nov 24 (was Tue Nov 22; 2-day slip)

   Done:        6 of 8 services cut over (auth, users, orders, catalog,
                notifications, search)
   Remaining:   reporting (2d), billing (1d)
   Slip cause:  legacy adapter double-encodes UTF-8 on the reporting
                payload. Fixed in PRO-455, cost 2 days.
   Risk:        billing cutover needs a 15-min write freeze; not yet
                scheduled with finance
   Need from you: approve the write-freeze window (Thu 06:00-06:15 UTC)

Four properties make this work: a date with a delta against the previous date, a count rather than a percentage, a named cause for the variance, and an explicit "need from you" line. Include that last line in every update even when the value is "nothing" — its absence is precisely what makes people open the thread and ask.

The Escalation

Escalating well is a specific skill: you are transferring a decision, not a feeling. An escalation that lacks a recommendation delegates your judgment upward along with the problem, which is the opposite of helpful.

❌ "I'm getting pretty worried about the launch timeline. There's a lot
    still outstanding and I don't think people realize how much is left
    on the SSO piece. Can we talk about this?"

This creates work: your manager must now discover the facts you already have, and form the opinion you already hold.

✅ Subject: Nov 3 launch at risk — recommend Nov 17

   Recommendation: move launch to Nov 17.

   Why: SSO integration needs ~3 weeks; 1.5 weeks remain. The vendor's
   staging environment has been down since Oct 12 (their ticket #4471,
   no ETA), so we cannot test the SAML assertion path at all.

   Options:
     A. Move to Nov 17. No scope loss. My recommendation.
     B. Launch Nov 3 without SSO. 4 enterprise accounts (~$180k ARR)
        cannot onboard; they were promised SSO at signing.
     C. Add a second engineer now. Saves ~4 days — not enough to hold
        Nov 3, and slows the current work for 2 days of ramp.

   Decision needed by Fri Oct 24. After that, A is the only option left,
   because the release train cutoff passes.

   What would change this: if the vendor restores staging before Oct 22,
   Nov 3 becomes viable at roughly 60% confidence.

The final line is what separates an escalation from a complaint: it tells the reader what evidence would reverse the recommendation.

Writing for the Skimmer

Assume your reader gives the document 15 seconds before deciding whether to invest more. In those 15 seconds they will read headings, bold text, the first line of each paragraph, and any table. Design for that path deliberately.

• Front-load every paragraph — the first sentence carries the claim, the rest supports it. A reader who stops after sentence one still gets the point.
• Cap paragraphs at about 5 lines. Longer blocks get skipped wholesale.
• Use a table whenever you have 3+ items compared on 2+ dimensions. Prose comparison forces the reader to build the table in their head.
• Bold the decisions and the asks, nothing else. Bolding for emphasis everywhere is bolding nowhere.
• Put the detail in an appendix or a collapsed section rather than deleting it. Skimmers skip it; the one person who needs it can still find it.

Design Docs People Actually Review

A design doc's purpose is to get objections before the code exists. Most design docs fail at this, and the failure is usually structural rather than stylistic.

What makes a doc reviewable:

• Circulated before implementation, not after. A doc sent alongside the PR is a status report. Reviewers know their objections are now expensive and will stay quiet.
• Constraints stated first. Reviewers cannot evaluate a design without the boundaries: what latency budget, what scale, what must not change, what team owns the downstream system.
• Alternatives with real reasons for rejection. "Considered Kafka, rejected it" is filler. "Rejected Kafka: we have no Kafka expertise on-call, and the ordering guarantee we need is per-user, which the existing queue already gives us" is a claim a reviewer can attack.
• An explicit list of what you want reviewed. "I am confident about the schema; I want scrutiny on the backfill strategy and the rollback path." Ungated docs get either no comments or comments about naming.
• A decision deadline. "Comments by Thu; I start Fri with whatever we have." Open-ended docs collect comments forever and decide nothing.
• Length under about 3 pages for the main argument. Longer means fewer readers, and the marginal reader is usually the one who spots the flaw.

Async-First and the Written Record

In any team spanning time zones or more than a handful of people, the default medium must be written and durable. This is not merely a convenience preference — it changes who can participate. A decision made in a call includes only the people in that call, and excludes everyone asleep, on leave, or hired next month.

The operating rule: a decision that is not written down did not happen.

Not as a moral stance, but as an accurate prediction. Six weeks later there is no recollection of who agreed to what, the reasoning is lost, and the same argument runs again from zero — usually with a different outcome, which is worse than either outcome consistently applied.

So: synchronous discussion is fine and often faster for resolving a stuck disagreement. But it is not the artifact. Within the hour, post:

Decision: we will use per-user ordering in the existing SQS queue rather
          than introducing Kafka.
Decided by: Priya (owner), John, Marcus — call on Oct 21.
Reasoning: our ordering requirement is per-user, not global. SQS FIFO
          with user_id as the group key satisfies it. Kafka would add
          an operational surface nobody on this on-call rota knows.
Rejected: Kafka (ops burden), Redis streams (no durability guarantee we
          can defend to compliance).
Revisit if: we need cross-user global ordering, or throughput exceeds
          3k msg/s per group (SQS FIFO limit).

The "revisit if" line is doing real work. It converts a decision into a standing condition, so the next engineer knows whether the reasoning still applies rather than either blindly following it or blindly overturning it.

Communicating Uncertainty Honestly

A single-point estimate is a lie of precision. It silently converts your guess into another team's commitment, and when it slips, the cost is trust rather than just schedule.

❌ "Should take about a week."

✅ "3-8 days, low confidence.
    3 days if the auth layer uses the standard session middleware.
    8 days if it has the custom token handling I've heard about.
    I'll know which within a day of starting, and will update then."

Four components, all necessary:

The same structure works for incident impact ("between 400 and 2,000 users affected; the range is wide because we sample request logs at 5%"), for capacity ("this holds to somewhere between 5k and 15k RPS; untested above 5k"), and for risk. Widening a range costs you nothing with a reader who trusts you, and false precision is what destroys that trust.

State confidence explicitly rather than hedging with adverbs. "Probably fine" is unmeasurable; "80% confident, and the 20% is the migration lock" is a claim someone can plan around.

For incident-specific narrative and timelines, see incident-timeline-creation.

Common Anti-Patterns

❌ Chronological narration — "First we tried X, then Y, then we found Z." The reader reconstructs your week to find the conclusion. ✅ Conclusion first, evidence after. Discovery order is for your notes, not for your reader.

❌ The buried ask — a request for a decision in the final paragraph of a long thread, or implied and never stated. ✅ The ask goes in the first two lines and names a person and a date.

❌ Unfalsifiable status — "good progress", "some issues", "almost done", "should be soon". ✅ Counts, dates, deltas against the last date, and a named cause for variance.

❌ Single-point estimates — "about a week", which becomes a committed date in someone else's plan by the next morning. ✅ A range, a confidence level, the driver of each end, and a resolution date.

❌ Escalating a feeling — "I'm worried about the timeline." ✅ Escalate a recommendation with options, costs, a decision deadline, and what evidence would change your mind.

❌ Decisions that live only in a call or a DM — reasoning lost, argument repeated next quarter with a different outcome. ✅ Post decision, reasoning, rejected alternatives, and revisit-conditions to a durable place within the hour.

❌ The design doc sent with the PR — reviewers understand their objections are now expensive and stay silent. ✅ Circulate before implementation, name what you want scrutinized, set a comment deadline.

❌ One document for every audience — the executive reads pool-size details, the engineer cannot find the rollback plan. ✅ Pick one primary reader. Write a 3-line summary that serves the others and link to the detail.

❌ Prose comparison of many options — three paragraphs the reader must convert into a table themselves. ✅ Give them the table.

❌ Hedging adverbs as risk management — "probably", "should be fine", "hopefully". ✅ Numbers: "80% confident; the 20% is the migration lock window."

Communication Checklist

• Primary reader identified, and what they must do
• Conclusion or ask is in the first two lines
• Document survives deleting everything after paragraph one
• Every estimate has a range, a confidence, and a resolution date
• "Need from you" line present, even if it says "nothing"
• Dates carry a delta against the previously communicated date
• Variances have a named cause, not "some issues"
• Escalations carry a recommendation, options with costs, and a deadline
• Escalations state what evidence would reverse the recommendation
• 3+ items compared on 2+ dimensions are in a table
• Paragraphs under ~5 lines; first sentence carries the claim
• Design doc circulated before implementation, with a comment deadline
• Design doc names what specifically needs scrutiny
• Rejected alternatives include the actual reason for rejection
• Every synchronous decision written to a durable place within the hour
• Written decisions include reasoning and revisit-conditions