grill

name	grill
license	MIT
description	Use when a technical writeup, blog post, war story, or "Show HN" is about to go to Hacker News, Lobsters, or any skeptical technical audience, or when the user says "grill this", "make it HN-ready", "harden this post", "is this ready to post", "will this survive the comments". Hardens facts, sourcing, voice, and comment-readiness. Not for identity/infra leak scrubbing (use plate) or repo publication (use publish-readiness).

grill

On Hacker News and Lobsters the top comment is usually someone who has done the exact thing you wrote about. Grilling is the pass that gets a post ready to be read by that person: every claim sourced or flagged, the voice de-hyped, the story real instead of impressive, and the obvious objections already answered. You are not writing for the upvote. You are writing for the skeptic who has been here before.

Core principle: a fabricated specific is the fastest way to lose the thread to the one reader who knows. Flag what you cannot verify; never dress a gap as confidence.

The pass (run in order)

1. Voice: kill the underdog. Strip the effort-proving "I did X, I did Y, I opened the chassis, I ran the cabling" cadence. The byline already says you did the work; arguing it reads as insecure. Tell the story and let the specifics carry it. Cut sentences that exist only for rhythm or motivation ("That is the job.", "future pain with confidence.").

2. Slop: strip the AI tells and empty hedges. Run scripts/grill-scan.sh <file> for the mechanical hits (slop vocabulary, hedge phrases, em dashes, the rhythmic "That is X." tic), then read by eye for the rest. The scan is a floor, not the check.

3. Facts: source every number, price, date, version, and third-party claim, or flag it. For anything you cannot verify against a primary source, leave a literal [CONFIRM: what's needed] marker in the draft. Do not invent a plausible config value, log line, or figure to fill the gap. Look facts up yourself before asking the human; only escalate the ones that survive a real search.

4. Right-number check. A fact can be genuinely real and still be the wrong fact for this post. Confirm the claim matches the specific setup, not just that the value exists somewhere (quoting the full-bundle list price when the project ran the base edition; citing a benchmark from different hardware). Verified-real is not verified-relevant.

5. Freshness check. Vendor pricing, policies, and "minimums" get reversed, and versions move. Date-check any claim about how a third party behaves and note when it was true, so a since-changed fact reads as history, not error.

6. Specifics over fluff. Replace every hand-wave with a real artifact pulled from actual notes: a config value, an error message, a log excerpt, an exact version. If the artifact does not exist, say what happened plainly rather than inflating it. Real beats impressive, and impressive-but-vague reads as never-happened.

7. Citations. Link the primary source for any contested or load-bearing external claim: the vendor doc, the actual pricing page, the bug report, the commit. Inline links, never "studies show" or "it's well known".

8. Comment pre-mortem. For each load-bearing claim, ask: what will the commenter who has done this say? Fix what you can. For the rest, hand the author the three most likely objections with an honest answer ready for each. Surviving the grilling in public is where the credibility actually accrues; the goal is to be ready for it, not to dodge it.

9. Title. Factual and specific, no editorializing or clickbait. HN strips editorialized titles and the culture punishes bait. Use the real title and let the content earn the click.

10. Leak scrub (REQUIRED, last). Run plate for the identity and infrastructure pass before publish. A clean fact-check is not publish clearance; the leak gate is separate.

Rules

• Never invent a specific to sound credible. Flag, do not fake.
• Verified-real is not the same as right-for-this-post. Check edition, version, and context.
• The author's effort is assumed, not argued. No self-justification voice.
• One honest "I don't know why that happened" beats one confident wrong explanation. The skeptic forgives a gap and crucifies a bluff.
• Look up what is lookup-able. Only ask the human for facts that survive a genuine search.

Logistics (HN / Lobsters)

• Hacker News: submit a title and URL. It needs organic upvotes in roughly the first one to two hours or it falls off /newest unseen. You cannot upvote your own post and must not solicit votes; ring detection buries offenders. Weekday mornings around 8-10am US Eastern see the most traffic. A first comment from the author is optional, not required: use one only to add context that does not belong in the post, never reflexively. Most submissions get no traction, and that is the default outcome, not a verdict on the writing.
• Lobsters: invite-only, smaller, higher signal, less hostile. You cannot just sign up; you need an existing member to invite you. Tag accurately. Better suited to the second post, once there is a track record.

Common mistakes

• Padding thin facts with confident prose instead of marking the gap with [CONFIRM].
• Quoting a real number that is the wrong number for the setup.
• Leaving the effort-proving voice in because it "sounds passionate".
• Editorializing the title to bait the click.
• Treating a clean fact-check as publish clearance and skipping plate.
• Posting the first comment when the post already stands alone.
• Shipping a markdown render footgun: a bare ~ meaning "approximately" pairs into strikethrough, a stray * italicizes mid-word. The scanner flags tildes; always preview the rendered page, not just the source.