← Build log

The Parity Closure Doc: How to Stop Lying to Yourself About What's Actually Shipped

May 2026
SoloBuilderShippingProjectManagementDocumentationHonestTrackingSoftwareEngineering

The specific document pattern that separates “the phase plan” (aspirational) from “what’s actually done” (reality) — and the practice that catches scope drift in 30 minutes instead of 3 months.

Published: May 2026 Tags: #SoloBuilder #Shipping #ProjectManagement #Documentation #HonestTracking #SoftwareEngineering

The “So What?” - Why You Should Care

Bottom Line Value: A concrete doc pattern (“parity closure”) that separates aspirational phase plans from reality. Forces an honest accounting of what’s done vs. what’s claimed done. The practice that surfaces hidden blockers before they cost you a ship date.

What You’ll Gain:

  • The 4-section template for a parity closure doc
  • The rule that defines “parity” (and the much harder discipline of NOT widening it)
  • A specific way to surface “the one thing that’s blocking everything else”
  • The 30-minute monthly ritual to keep your phase plan honest
  • ROI: ~30 minutes to write. Saves you from the “we’re 90% done, just need to wrap up… for 3 months” trap that kills solo-builder ship dates.

Who This Helps: Solo builders whose phase plan says “Phase 4: 90% complete” but they secretly know there are 7 outstanding issues, 2 of which are big. Anyone who’s ever shipped 6 weeks late because the actual remaining work was different from the plan’s “remaining work.”

Why Bother: Phase plans are aspirational by nature. The longer they exist, the more they drift from reality. Without a separate “what’s actually done” tracker, you’ll convince yourself you’re nearly done until the day you try to ship and discover you’re not. The parity closure doc is the discipline that prevents this.

TLDR: The Template

A parity closure doc has 4 sections:

  1. What “parity” means — a strict, narrow definition of “shippable”
  2. Current state snapshot — table of capabilities × Implemented / Partial / Blocker
  3. The remaining blockers — named explicitly, ranked by what unblocks what
  4. Recommended execution order — concrete steps to close the gap

Write it when your phase plan and your gut disagree about how done you are. Update it every 30 days (or after any week with significant work). Use it instead of your phase plan when sequencing the next sprint.

The Moment You’re Probably In

Open your project’s Execution-Plan.md. Read the latest status line. It probably says something like:

Current status: Phases 0–4 complete. 90% feature parity with v1. Next up: Phase 5 (polish + launch).

Now ask yourself, honestly: if you tried to ship today, what would actually break?

Not “what’s planned in Phase 5.” Not “what would be nice to have.” What would actually break for a user, right now, if you handed them the current build?

If you can name 4 things off the top of your head — and you’d characterize at least 2 of them as “blockers” rather than “polish” — your phase plan is lying to you.

The reason is structural. Phase plans are written prospectively (before you know what’s hard) and updated reactively (you mark steps complete as you complete them). They don’t surface what’s hidden between the lines: the integration work no one wrote down, the edge case you remember-when-prompted but forget when planning, the platform thing you keep meaning to verify but haven’t.

The fix is a second tracker — written with different rules. The parity closure doc.

What Parity Closure Means (the discipline)

The goal: an honest tracker that answers “can we ship?” — not “have we executed the plan?”

The rules:

  1. Parity has a narrow definition. Decide what “shippable” means for v1 specifically, and refuse to widen it. Every aspirational PRD item that doesn’t fit the narrow definition is out of scope for this tracker.
  2. It is separate from the phase plan. Phase plans are roadmaps. Parity closure is an audit.
  3. It is honest about what’s implemented vs. claimed. “Implemented” means: runs end-to-end on a real machine with real data and doesn’t error.
  4. It names blockers explicitly. Not “should investigate X” — “X is blocking ship.”
  5. It updates more often than the phase plan. Phase plans live for months. Parity closure should be re-checked every few weeks.

The hardest discipline: refusing to widen the parity definition when something interesting comes up. Every “we should also add…” adds a month. The parity doc exists specifically to say “no, that’s out of scope for parity. Keep it for v1.1.”

Section 1: The Parity Definition (the narrow promise)

The doc opens with a strict statement of what counts as parity. Write it as numbered claims, not paragraphs.

For our voice-transcription app, parity meant:

For this closure pass, parity means the rewrite can reliably replace the previous app for the core macOS workflow:

1. Capture audio
2. Transcribe it
3. Persist sessions/history
4. Trigger from tray/hotkeys
5. Copy/paste results
6. Recover interrupted recordings on next launch

This plan does NOT treat every aspirational PRD item as a parity blocker.
Items like encrypted export, Windows support, extended migration work,
or broader release polish belong to a later maturity pass.

The explicit “does NOT” is the most important part. The temptation when something interesting comes up is to fold it in. Resist.

The discipline: every time someone says “we should also…” check whether it’s already named in the parity definition. If not, default no.

Section 2: The Current State Snapshot (the table)

A table where rows are capabilities and columns are status + notes.

| Area | Status | Notes |
|---|---|---|
| Recording + transcription | Implemented | Rust commands, state machine, streaming updates, save flow present. |
| Settings persistence | Implemented | Frontend settings UI + Rust JSON persistence wired. |
| Session history | Implemented | History panel, search, paging, delete, backend session storage exist. |
| Session export | Implemented | UI exposes Markdown export; backend supports Markdown + JSON. |
| Tray + global hotkeys | Implemented, verify on device | Events wired into recorder; needs real-machine validation. |
| Clipboard + auto-paste | Implemented, verify on device | Clipboard command + macOS `osascript` paste path present. |
| Help + updater UX | Implemented | These are already beyond the strict minimum parity bar. |
| Crash recovery | **Partial / parity blocker** | Checkpoint writing + orphan scanning exist, but the restore-and-surface flow is incomplete. |

Three status categories, used strictly:

  • Implemented: runs end-to-end on real hardware, no known issues
  • Implemented, verify on device: code is in place but you haven’t actually tested it with real input recently
  • Partial / parity blocker: known incomplete; can’t ship without this

The “verify on device” status is critical. It’s the lie most solo builders tell themselves: “I wrote the code, so it works.” Code that hasn’t run end-to-end with real hardware in a week is not “implemented” — it’s probably implemented. Flag the difference.

Section 3: The Remaining Blockers (the truth section)

This is where the doc earns its place. For each parity blocker, write:

  • What it is (one sentence)
  • What’s actually there today (the code state)
  • What’s missing (the gap)
  • What unblocks it

For our project, this section read:

Key finding: recovery is the remaining real blocker

Recovery is not just missing UI glue.

Current code shows:

  • Checkpoint files are written and can be scanned on launch
  • recover_checkpoint only returns the first orphaned checkpoint
  • RecoveryNotification.tsx expects multiple results and assumes they are already “ready in history”
  • App.tsx does not render RecoveryNotification
  • I did not find code that promotes orphaned checkpoint WAVs into saved history sessions on startup

So parity closure requires finishing the recovery workflow, not merely toggling a toast on.

This is the level of specificity the parity doc needs. Not “recovery is partial” — exactly which files have exactly which gaps. Force the diagnosis at parity-doc-writing time so the closure work is concrete when you sit down to do it.

The good news: once written this clearly, the work is bounded. You can estimate it. You can sequence it. You can finish it.

The bad news: you have to actually do this — read your own code and write down the gaps — for every blocker. It’s the work most solo builders skip. It’s why they ship late.

The blockers from Section 3, sequenced and concretized:

### 1. Complete startup recovery discovery
Goal: every cold launch checks for orphaned checkpoints.
Actions:
- Choose one boot path and make it authoritative
- Return ALL orphaned checkpoints, not just the first
- Preserve clear typing/serialization for recovery payloads

Definition of done:
- Launching with 0 orphaned checkpoints is a no-op
- Launching with 1+ orphaned checkpoints produces a deterministic recovery payload
- Multiple orphaned sessions are supported

### 2. Add an actual restore path, not just discovery
Goal: orphaned checkpoint data becomes something the user can actually recover.
Recommended parity behavior:
- On startup, convert each orphaned checkpoint into a recoverable session artifact
- Make it appear in session history
- Only then show recovery UI that says it is available

Notice the “Definition of done” subsections. They’re concrete tests the work has to pass. Without those, “implement recovery” stays vague and never finishes.

This section becomes your sprint plan. You execute it in order. You ship parity when it’s all done.

When to Write a Parity Closure Doc

The trigger: when your phase plan and your gut disagree.

Specific moments:

  • You think you’re 90% done, but planning the next sprint feels weirdly hard
  • A teammate (or beta tester) asks “when will it ship?” and you can’t answer with confidence
  • The last 3 things you “completed” each took 2× the estimate
  • You catch yourself widening the scope to fit what’s already done (“we never really needed Y, did we?”)

If any of those are true, you don’t have a 90% complete project — you have a project whose remaining 10% you haven’t honestly inventoried. The parity doc forces the inventory.

What This Doesn’t Fix

  • Writing the doc takes 30–60 minutes of uncomfortable honesty. You’ll be tempted to skip the “verify on device” notes because they make you look less done. Don’t.
  • The parity definition will pressure to widen. Every interesting idea will want to be added. Keep saying no.
  • It doesn’t fix bad estimates. It just makes them visible faster. That’s still a win.
  • Other docs can drift. The parity doc is one tool. Your phase plan and PRDs still need their own audit rituals (see post #136).
  • The doc requires ruthless commitment to “actually done” definitions. “Implemented, but I haven’t run it in 2 weeks” is not Implemented.

Try It This Week

Saturday afternoon (60 minutes):

  • Open your existing phase plan / execution doc
  • Create a new file: Execution-Plan-Parity-Closure.md
  • Write Section 1: the narrow parity definition. Limit to 4–7 numbered claims.
  • Write the “does NOT” line — what’s deliberately out of scope.

Saturday evening (60 minutes):

  • Write Section 2: the current state table
  • Be honest with the status categories — use “Implemented, verify on device” liberally
  • Mark any “Partial / parity blocker” explicitly

Sunday morning (90 minutes):

  • Write Section 3: the remaining blockers, in the level of detail shown above
  • For each blocker, open the code and trace exactly what’s there vs. missing
  • This is the work most builders skip — do it

Sunday afternoon (30 minutes):

  • Write Section 4: execution order
  • Each item gets a “Definition of done” with concrete checks
  • This becomes your sprint plan

Once a month:

  • 30-minute review. Update status. Re-check blockers. Have any closed? Have new ones emerged?

That’s the practice. One uncomfortable Sunday afternoon. Bounded, honest work after.

The Takeaway

Phase plans are roadmaps. They’re optimistic by design and they age badly. They will tell you you’re 90% done indefinitely.

Parity closure docs are audits. They’re pessimistic by design and they age well. They tell you what’s actually shippable today.

The discipline that separates solo builders who ship from those who don’t is whether they keep both documents and trust the audit when it disagrees with the roadmap.

The pattern is concrete:

  • A narrow parity definition that you refuse to widen
  • An honest state snapshot with explicit “verify on device” gradations
  • Blockers named at the code level, not the feature level
  • A concrete execution order with definitions of done
  • A monthly ritual to keep it current

None of this is hard. The discipline is the value. Most solo builders skip this work because it feels uncomfortable. The discomfort is what makes it useful.

If your gut says you’re closer to done than the work suggests, you’re right — about the gut, not about the done. The parity closure doc is how you find out which is which while you still have time to act on it.

The end of the catch-up series. This post closes the arc that started with post #135 (the rewrite decision). If you’re working through a rewrite of your own, the path through these 9 posts is the path we took — decision, methodology, audio port, LLM port, what-not-to-rewrite, characterization tests, state machine, streaming UX, honest tracking. Each post is a moment you’ll recognize when you hit it. Each is a way through.