Build in Public

Purpose

Turn ongoing development into progress updates that are worth reading without being worth doubting. Building in public works when the audience can trust the signal: a shipped feature means shipped, a milestone means counted, a failure means described. This skill produces updates that keep that trust, including the discipline of not turning every setback into a redemption arc.

When to use this skill

• The user wants to share a development update from active work
• Something shipped, broke, failed, changed, or hit a milestone
• The user says "build in public", "progress update", "devlog post", "share today's progress", or similar

This skill covers single updates. It does not plan a content calendar; see the notes in "When NOT to use".

Required inputs

1. What actually happened, in the user's words: the event
2. Enough context to explain the event to someone outside the project (what the product is, in one line)

If the user gives only "shipped an update", ask what the update does.

Optional inputs

• Type of update (see the seven supported types below)
• Technical detail worth including (the bug, the decision, the numbers)
• What happens next, if anything
• A link (repo, changelog, deploy note)
• Permission status: whether employer/client work may be mentioned at all

Supported update types

1. Feature shipped. Lead with the capability, not the commit count.
2. Bug fixed. The interesting part is the cause, when knowable.
3. Architecture changed. Name what forced the change.
4. Deployment failed. Factual incident report; see failure rules.
5. Experiment failed. State what was tried, what was observed, and what changes. A null result is still a result.
6. Milestone reached. Only count milestones with a real definition: "v0.3 shipped", "first paying customer", "100 tests green". Counted things only.
7. Product direction changed. Say what changed and what killed the old plan. Honesty about pivots is unusual and therefore memorable.

Workflow

1. Triage the event. Sort the user's account into KNOWN / INFERRED / UNKNOWN per credibility-rules.md.
2. Classify the update type from the list above. The type determines the shape.
3. Apply the failure rules if the event is a failure (below).
4. Check milestone integrity if the event is a milestone: ask how it is defined and counted if the user has not said.
5. Draft at 50 to 150 words. Lead with the event. Follow with the one detail that makes it concrete. End with next steps or nothing; endings are optional.
6. De-hype and check against voice-guide.md and the quality check below.
7. Deliver the post plus, on request, the information audit.

Failure rules

This skill's most important rules govern failure posts:

• Report the failure chain as known: trigger, mechanism, detection, fix. Unknown links stay unknown ("I still don't know why the cache thrashed").
• Do not automatically convert failure into inspiration. Some failures end at "reverted and moved on". Manufactured lessons are the fastest way to sound fake.
• When a lesson exists, make it procedural: "we now set lock_timeout", "I now backfill in batches". A lesson is something the reader could adopt.
• No invented blame, no invented heroes, no invented downtime numbers. If the user does not state the duration of an outage, the post does not state one.
• Never describe a failure as "part of the journey". Describe it as an event with a cause.

Truth and credibility rules

• Full triage per credibility-rules.md before drafting.
• Protected categories at high risk here: user counts, revenue, uptime, performance, GitHub statistics. None appear unless stated.
• Momentum claims ("shipping fast", "crushing it") are not facts and are banned. Concrete events are facts and are welcome.
• "We" vs "I": use the pronoun the user earned. Solo builders write "I"; teams may write "we" only for work the user witnessed or did.
• Milestones only with definitions. "1000 users" requires knowing what a user is; if the user has not defined it, ask once.
• If the work belongs to an employer, the skill asks whether it is cleared for public discussion before drafting.

Writing rules

• Default voice per voice-guide.md. Short update, short post: 50 to 150 words, one to three paragraphs.
• The first line states the event. No throat-clearing.
• Streaks are not content. Never write filler updates to keep a cadence; if nothing happened worth saying, say nothing.
• Banned: "day 47 of my journey", "grinding", "the grind never stops", "big things coming", "stay tuned" as an ending when there is nothing specific to stay tuned for.
• One emoji maximum, only if the user uses them.

Output format

[The update, ready to copy]

[Optional, on request]
KNOWN: ...
INFERRED: ...
UNKNOWN (not claimed): ...

For failure posts, append one line: "If you'd rather not post this yet, it also works as an internal incident summary." The user decides.

Worked example

Input (summary): a routine migration added a column with a default and backfilled ~200,000 rows in one ALTER TABLE on Postgres 15; writes queued behind the lock; about 40 minutes of degraded API; fixed by killing the migration and batching the backfill; changes: lock_timeout, batched backfills, staging rehearsals.

Output (the update):

We had an incident today. About 40 minutes of degraded API.

Cause: a routine migration. I added a column with a default and backfilled
roughly 200,000 rows in one ALTER TABLE. On Postgres 15, that takes a lock
long enough that writes on the users table queued behind it.

What fixed it: kill the migration, run the backfill in batches.

What changes on Monday:
- Migrations set lock_timeout so they fail fast instead of stacking locks
- Backfills run in batches, never in one statement
- We rehearse migrations against a staging copy at production data sizes

No lesson about resilience here. I just wrote a migration that assumed a
smaller table.

Full walkthrough: examples/failed-deployment.md.

Edge cases

• Nothing went wrong and nothing shipped, but the user feels pressure to post. Advise skipping the post. Silence between real updates is normal and costs nothing.
• The failure involves other people's mistakes. Write the cause without naming or characterizing colleagues. "A misconfigured flag" not "Dave's flag".
• The user wants to post daily no matter what. The skill drafts only events with substance and says so plainly once.
• NDA or employer IP. Strip all identifying details; if the update cannot be made generic and true at the same time, decline.
• Milestone inflation request ("call it 1,000 users" when it is 60 signups). Decline and draft the honest version; defined, counted, labeled.

When NOT to use this skill

• The update announces a finished, presentable project: use project-post-writer.
• The event is research or experiment results framed as findings: use research-to-linkedin if results are the point.
• The user wants engagement farming, streak tactics, or algorithm hacks: this kit does not do that, and the skill should say so.
• The user wants a long-form retrospective of a finished project: use portfolio-storyteller.

Shared references

• ../../references/voice-guide.md — voice rules and banned patterns
• ../../references/credibility-rules.md — the full fact triage system
• ../../references/technical-storytelling.md — the story spine, especially the failure section

These paths assume the full repository is present. This skill works standalone: the rules above are the core, the references add depth.