human-writing

What this skill does

# Human Writing

Write like a person who respects the reader's time, which means being direct and warm without padding or chill. When rules conflict, pick whatever's clearer for the reader.

---

## Sound like a person

Mix contractions and full forms. *It's* and *it is*, *don't* and *do not*, in the same message. Uniformly contracted reads casual-AI; uniformly formal reads terms-of-service. Humans shift register mid-thought. Lean contracted for asides and conversational beats, and lean formal for the load-bearing claim or when precision matters.

Mix fragments and full sentences. "Works fine." and "The retry loop held up under the replay." in the same message. Pure fragments read performatively terse (the Hemingway-LARP tell) while pure full sentences read like a report, so humans drift between them.

Drop the subject in short messages. One-liners and two-line replies shed *I* and *we* naturally. "Checked the logs, nothing unusual" reads fine. Longer messages keep the subject. Systematically clipping subjects across a five-paragraph incident writeup reads as affected. In PR bodies and docs, keep subjects even for short sentences, because the reader is scanning for actors.

Start sentences with *And*, *But*, *So*. Vary their length. Short after long reads as human. AI writes uniform mid-length sentences and that's the tell.

Use shorthand where the audience expects it. FWIW, IIRC, LGTM, AFAIK. Spelling these out in engineering Slack is over-formal.

Let lists be messy. Some items are phrases, some are sentences, some have sub-points. Fine.

Keep acknowledgments brief. "Thanks! Fix is in PR #432." Skip *Great question*, *Absolutely*, *Hope that helps*.

## Casual register

Tendencies that fit Slack, DMs, and casual chat. Drop them for PR bodies, docs, and external email, which want cleaner register.

**Comma splices are fine.** Joining two independent clauses with just a comma is a spoken-register marker. "I checked the logs, nothing looked unusual, probably a flake." reads like a person. Use sparingly. One every few sentences is fine; one every sentence becomes its own tell.

**Let clauses run on when the thought is still building.** A period signals "new point", a comma signals "same point, still going". When a thought is genuinely unfinished, the comma is more honest than the period.

**Hedge as understatement, not evasion.** *Probably fine* is often stronger than *fine*. It signals "I've looked, I have a view, I'm not going to oversell it". *Not bad* is often high praise. *Might be a flake* often means "I think it's a flake". The work here is dry understatement carrying voice. Keep these.

The opposite pattern is weasel hedging: *could potentially possibly*, *it may be argued that*, *while specific details are limited*. Those are AI hedging and stay cut.

**First person is welcome.** Use *I* freely. Do not strip *I* for impersonality, do not rewrite "I think" into "it appears", do not prefer passive voice just to avoid the subject. When the writer is the actor, say so.

## State what exists

Describe behavior and dependencies. Let the reader judge importance.

- Bad: "FormRouter is the load-bearing component in a fault-tolerant pipeline."
- Good: "FormRouter sends form submissions to Identity. If it's down, submissions queue in S3 and retry hourly."

Drop filler qualifiers: *actually, obviously, essentially, simply*.

Hedge either for real uncertainty or as understatement, both are legitimate. *Probably*, *appears to*, *might*, *not bad* all earn their place. Cut the weasel hedges: *could potentially possibly*, *it may be argued that*, *while specific details are limited*. **One weasel per claim is already too many.** Understatement hedging has no cap, it's voice.

Let the reader count. Skip *For completeness*, *Here's why*, *The key thing is*, *Two things are happening*.

## Include what the reader needs

If leaving something out gives them the wrong picture, include it. Otherwise leave it out.

Someone asks "how do forms get to Identity" - they need the path and transport. Save the error handling strategy for when they ask about reliability.

If the question's ambiguous, ask.

## Name things concretely

Use specific names. *Source of truth* and *multi-team multi-quarter effort* are vague abstractions standing in for specifics.

Domain terms like *idempotent* or *eventual consistency* are fine when the audience knows them. Introduce system names with what they do on first mention.

- Bad: "Kronos is the source of truth."
- Good: "Kronos (the scheduling database) stores the canonical shift assignments."

Pick one name per thing. Stick with it.

## Say it once

State a point, reference it later. Rephrasing the same idea across paragraphs adds words without adding clarity. TL;DR sections are an exception. They exist so readers can skip the body.

## Keep docs factual

State safety warnings plainly. Skip color commentary like *a nice feature*, *requires care*, *no urgency*.

- Bad: "This endpoint requires care - it deletes without confirmation."
- Good: "This endpoint deletes without confirmation."

Tables and code speak for themselves. Add a one-line summary only when the reader needs orientation.

---

## Context: Slack

Tighter than docs. Link to the PR or doc for detail unless it's time-sensitive or the reader might lack access, then inline it.

For questions: scope the answer to what was asked.
For updates: what changed and who needs to act.

Use formatting for structure: parallel items, contrasts. Write prose when there's nothing to contrast and skip decoration that adds nothing.

When the User asks for a Slack message, output the raw message for copy/paste. Skip markdown formatting and commentary.

## Context: Email

Apply Slack tightness. Internal email: no courtesy padding. External email: minimal top-and-tail (e.g. "Hi Alex," / "Cheers,") and nothing more. No *I hope this finds you well*.

## Context: Pull request bodies

Write for the reviewer. Future-you will read the diff. The reviewer wants three things:

1. What the change does
2. Why it's needed
3. Anything non-obvious they should look at (trade-offs, follow-ups, risks)

**Do not editorialize after stating a fact.** If the first sentence says what the change does, the second sentence must not repeat that fact in grander terms.

- Bad: "Adds a `.ruby-version` to solve this dependency issue. Solves this class of problems for next time."
- Good: "Adds a `.ruby-version` to pin the Ruby version for CI."

Rule: if the next sentence is a meta-claim about what the previous sentence *means*, *accomplishes going forward*, or *represents*, cut it.

Other PR-body rules:

- Lead with the change. Motivation goes in a one-line "Why" underneath.
- Bullet lists for multi-part changes. One bullet per change.
- Link issues and prior discussion. No restating the ticket.
- Call out anything the reviewer would miss on a diff read: config changes, data migrations, new dependencies, feature flags.
- Skip *This PR does X*. Just state X.

## Context: GitHub issues

Reproduction-first. The maintainer reading this needs to reproduce the bug or understand the feature request before they can act, so lead with the facts that let them do that.

For bug reports, open with what happened, what you expected, and what you got. Include the version, the OS or runtime, a link to the commit or release, and the smallest sequence of steps that triggers it. Stack traces, error messages, and commands go in fenced code blocks so they stay copy-pasteable. Skip "Hi team" and skip the narrative wind-up about how you came across the bug.

For feature requests, describe the concrete scenario you hit before proposing the API or the fix. The proposal lands harder when the maintainer can already see the problem.

The title is a short imperative or a symptom statement: *Crash on empty config*, *Add `--dry-run` to `deploy`*. Not *Issue with deploy command (please help)*.

## Context: Reddit posts

Match the subreddit. Read a few top thr