Repo Launch

repo-launch

Grounded in a research pass over 28,285 Show HN posts, 394 launched repos, and the peer-reviewed literature on open-source traction. Most of the standard launch playbook is folklore and this skill deliberately does not do it. Read §Evidence before arguing with any step.

The through-line: what you launch decides the ceiling, one exogenous event inside 72 hours decides whether you reach it, and polish moves neither. Spend accordingly.

0 · The kill gate — the pitch, before anything else

Write the Show HN title first. Before the README, before cleanup, before any launch prep.

Show HN: <Name> – <concrete capability, plain words>

Then apply the stranger test, honestly and out loud: reading only that line, with no context and no loyalty to the project, would a stranger want this?

The decision procedure — answer all four out loud, then rule:

1. Comprehension. Can a stranger say what it does after one read, with no follow-up question?
2. Surprise or relief. Does it either do something they didn't know was possible, or kill a chore they recognize? Neutral-but-competent is a fail.
3. Audience size. Roughly how many HN readers have this problem? A tool requiring a specific vendor's product, a niche framework, or a paid dependency shrinks this hard.
4. Barrier to try. Can they run it in under 2 minutes with no signup and no account?

PASS = yes to 1 and 2, plus a broad audience on 3 and a low barrier on 4. WEAK = 1 and 2 pass but 3 or 4 is narrow — say so and give the honest expected outcome rather than launching on autopilot. FAIL = 1 or 2 fails.

Show the user the title and the verdict. If it's WEAK or FAIL, say so plainly and stop — this is the step with the most leverage in the entire process and it is free. No amount of downstream craft rescues a project nobody wants. Offer to reframe (usually the capability is buried under the implementation) or to shelve the launch and keep the repo as a portfolio artifact, which costs nothing and still serves the credibility goal.

Grading your own project generously here defeats the whole skill. Be the stranger, not the author.

Title mechanics that measurably matter:

• Keep the description body 26–45 characters (best band). Past 70 it degrades.
• Use the Name – description shape, not a bare name.
• Never lead with AI/LLM/GPT. It roughly halves the hit rate, in every stratum. If it uses an LLM, name the capability instead.
• "Open-source alternative to [known paid product]" is the single strongest formula in the data.

Winners look like: "Run any GUI app in the terminal" · "docker push directly to servers without a registry" · "A git log for your day". Losers look like: "Advanced fetch client builder for TypeScript" · "built using AI and almost zero coding".

1 · The secret scrub — the only irreversible step

Hard gate. Nothing else in this skill can hurt you; this can. Once public, exposure is permanent: commits survive in forks, in SHA-1-addressable cached views on GitHub, and through any PR that references them.

Run references/secret-scrub.md in full. Do not skip it because the working tree looks clean — the risk lives in history. Do not rely on GitHub push protection: it is off by default at the repository level, bypassable, and only matches known provider patterns, so it misses custom app secrets, internal hostnames, customer data samples, and unusual key formats.

Order matters and it is the reverse of common advice: rotate first, rewrite second. Once a credential is rotated, rewriting history is often unnecessary.

Report findings to the user before flipping public. Flipping public is the user's call — never do it unprompted.

2 · Minimum credible repo — deliberately short

The evidence says this tier is hygiene, not a growth lever. Do it fast and stop.

• Description + topics set (GitHub's own surface; costs 30 seconds).
• A license. MIT unless there's a reason.
• README that answers What / Why / How-to-run in the first screen. Runnable in under 2 minutes, no signup — HN's rules require "no barriers such as signups or emails."
• Nothing embarrassing: no stale TODOs naming people, no dead links, no test123 commits at the tip.

Do NOT spend real time on: demo GIF production, badge arrays, CONTRIBUTING/CODE_OF_CONDUCT scaffolding, issue templates, or a docs site. Zero papers support any of them; badges past ~5 correlate with fewer downloads; documentation follows popularity rather than causing it. If the user asks for these anyway, build them — but say once that the evidence doesn't back it.

Decide the maintenance posture now, before traction exists: are you willing to owe this repo support? If not, say so in the README ("built for X, maintained as-is"). Popularity measurably reduces newcomer-to-contributor conversion and the most common OSS toxicity is entitled user demands. An honest "not actively maintained" note costs nothing and prevents the trap.

3 · The launch post

Show HN qualifies only for things people can run. Not blog posts, sign-up pages, newsletters, lists, or "quickly-generated one-offs" (HN's own words). Verify the project clears that bar.

• Link directly to the GitHub repo. Nearly doubles the hit rate (8.7% vs 4.8%).
• Post weekday midday US Eastern (12:00–13:00 ET peaks). Real but modest, ~2.75x best-to-worst hour. Ignore day-of-week advice — the whole-week spread is 1.22x and the best day is Sunday.
• Never ask anyone to upvote. HN penalizes or bans for it, and it's the one rule with teeth.
• Do not post a canned "author here" first comment. Tested and falsified: it rescues nothing. Answer real questions instead.
• Do not blast every channel at once. Lobsters is invite-only and locks new accounts out of the show/announce tags for 70 days; Reddit defines spam behaviorally, so an on-topic post can still be spam by ratio. Pick one channel, or stagger by days.
• Reposting is allowed if the repo hasn't had significant attention in ~a year. Don't delete-and-repost.

Draft the post, show it to the user, and let them post it. Never post on the user's behalf.

4 · The 72-hour window

Star-decay half-life from the peak day is 2 to 4 days, and the first week carries 38–77% of the entire first year. There is no slow burn. Tell the user to clear that day and the next before posting — and note the peak is usually day 1, not day 0.

During the window: answer questions fast and substantively, fix real bugs people hit, and merge trivial PRs. Not because engagement causes traction (it doesn't), but because a live thread is the one thing you can actually serve.

5 · Close the loop

Set expectations before the result lands, then record it:

• Median outcome of an open-source Show HN is ~22 stars. The mean is 951 and is a tail you cannot plan on. P(≥100 stars) ≈ 29%; P(≥1000) ≈ 7%.
• Roughly 5.9% of Show HN posts clear 30 points; 2.6% clear 100. Median post: 2 points, zero comments.
• One launch tells you almost nothing about your execution. The strategy the base rates support is a portfolio of small shots, not one big bet.

Append one row to launches.jsonl in this skill's own directory — never to skill-usage-log.jsonl, which has a fixed schema owned by the skill-outcome Stop hook and read by setup-audit. Exact schema, one line:

{"ts":"2026-07-20","repo":"yourname/your-repo","title":"Show HN: ...","channel":"show-hn","points":null,"comments":null,"stars_d0":0,"stars_d7":null,"note":""}

Write the row at launch with the day-7 fields null, then fill them in on a follow-up pass. After ~5 launches this is a personal base rate, which beats the global one.

Evidence — why steps are missing

Cite these when the user (or you) wants to add ceremony back.

• Launch mechanics move the tail, not the median. Stacking every controllable lever takes the hit rate from 1.4% to 10.1% — but the median is 2 points in every stratum, including the best.
• The only randomized experiment (Shen & Sood 2026, 622 packages) doubled-to-tripled star counts and found no effect on downloads, forks, PRs, or issues.
• 78.5% of developers whose repos went viral credited Hacker News or social media, not anything about the repository (Borges et al. 2016). Distribution, not decoration.
• Zero papers exist on demo GIFs/screenshots/video, repo descriptions, topics, or naming. "What makes a great README" traces to a blog post.
• The field is congested: Show HN submissions doubled in 18 months while the hit rate halved; the front page has fixed capacity.
• Stars are weak measurement and strong signalling — 0.14–0.47 correlation with real downloads, 6M known fakes, yet 73% of developers say they check them. That asymmetry is the whole reason a credibility play works, and the reason not to believe your own star count.
• No evidence exists that stars convert into consulting inbound or client leads. Instrument it yourself; don't assume it.

Don't

• Don't polish a repo that failed the §0 kill gate. Fix the pitch or shelve it.
• Don't flip public without §1, and don't flip it yourself — that's the user's call.
• Don't buy stars. Sub-two-month bump, ~5x weaker than real stars, net negative after, and public detection tooling exists.
• Don't promise traction. Quote the median (22 stars), not the mean.
• Don't let the repo's first impression be a stale fork of coursework — check what else is on the profile, since a launch sends people there.