Exploring An Idea

Exploring an Idea

A design document reads as settled fact whether or not anyone checked. That is the whole failure mode: an unverified sentence in a PCD becomes an interface, then a dependency, then a week of work, and nothing in the process ever asks "how do we know that?"

This skill exists to put that question before the document instead of after it.

The case this was written from

Needledrop (NFC tap-to-stream for record collectors) had an unusually good PRD and PCD — real non-goals, numeric kill criteria, a named Phase 0 with exit criteria. It still shipped four false premises into its architecture, and the Phase 0 spike had to correct all four:

None of these were sloppy. Each is a plausible reading of vendor documentation. They were wrong anyway, and the cost was concrete:

• An entire provider-abstraction layer — LinkResolver, capabilities OptionSet, chain-of-resolvers — designed around swapping away from a dependency that turned out to be unnecessary.
• A "blocking, business" open question (email Odesli for commercial terms, owner assigned, week 1) generated by a gap that did not exist.
• A long "Option D — build our own resolver" analysis premised on Spotify being unreachable.
• The real finding — tracklist matching, which took the album shelf from 62.1% to 79.3% and Spotify from 0% to 60% — appears nowhere in the PCD, because the document had already decided the identifier ladder.

And the name: the PRD listed "run the trademark pass" as an open question, after the docs were titled Needledrop and the repo was created as needledrop. The check ran later, "Needledrop is not viable" came back, and the project renamed to Sleevetap — while the repo, its remote, and its clone path still say needledrop today.

The lesson is not "write better documents." It is that a design doc is the wrong instrument for discovering whether something is true.

The method

1. Split the idea into claims, and label every one

Before writing anything designed to be read as a plan, list the claims the idea rests on. Give each a provenance label — no exceptions, including the obvious ones:

• measured — you ran it and saw the result. Cite the number.
• documented — a vendor doc says so. This is not verification. Every false premise above was documented.
• assumed — someone's reasonable belief.

Then ask of each: if this is wrong, does the design change? A claim that is documented or assumed and load-bearing is not a claim. It is a task.

For Needledrop that filter alone catches all four: "Spotify is closed" was documented and load-bearing; "UPC is the strongest identifier" was assumed and load-bearing.

2. Probe the load-bearing ones — cheaply, before the document

A probe is a script that answers one question with a number, not a prototype. Hours, not days; throwaway, not the first commit of the product.

The Needledrop probes would have been: one curl with Spotify client credentials (kills premise 1 in ten minutes); twenty barcodes from a real collection run against three catalogues (kills premise 2 in an hour).

In Claude Code, write and run them. In Claude Desktop, you cannot — so name each probe, say what number would settle it, and hand them over as the first work item. A doc that ships with "unprobed" next to a load-bearing claim is honest; one that reads as settled is not.

Probe on real data, not a sample you constructed. Needledrop's collection turned out to be 28% 7-inch singles, which resolve at 0% because a single has no album-level streaming entity. A flat rate across that collection answers the wrong question — and only real data reveals it.

3. Write the document around what survived

Now write the PRD/PCD (see core "Docs Taxonomy" for where they live). Rules that keep it honest:

• Every technical claim carries its label. measured claims cite the number.
• Do not design for a risk you have not confirmed. The provider abstraction is the cautionary tale: a real pattern, applied to an imaginary problem, and the cost was not the code but the architecture built around it.
• Kill criteria are numbers with a decision attached: "auto-match below 70% on a real collection → revisit" is a kill criterion. "Validate feasibility" is not.
• When a probe contradicts the document, amend the document in place and say what was wrong. Needledrop did this well: the PCD was corrected rather than left asserting things known to be false. A doc nobody trusts is worse than no doc.

4. Do the irreversible-cheap things first

Some decisions cost nothing now and a rename later. Do them before the doc is titled:

• Name: saturation + trademark pass, and check the term isn't already loaded in the domain ("needle drop" is a music-licensing term of art).
• Repo name: follows the name check, never precedes it.
• Domain / handles: check availability while the name is still free.
• Stack: name it in the doc, as an archetype (lacquer init --list-stacks), then pass it to lacquer init --stack <name>.

Needledrop got the order backwards and still carries the wrong repo name.

The stack one is subtler than it looks. Needledrop's PCD said "iOS app with a web backend" and was right — but the repo was bootstrapped during the TypeScript-only Phase 0 spike, so detection recorded profiles = ["web"], correctly, and nothing ever looked again. Swift landed the next day with no hooks, no CI, and no CLAUDE region; 191 tests were run by nothing at any gate for a month. Declaring the whole stack up front is a one-word difference at init and it gates the halves that don't exist yet.

Two claims about the same project were held to completely different standards: the API premises got a Phase 0 spike, and "an iOS app with a web backend" got written down and never checked against what the repo was actually enforcing. A claim about your own build is still a claim.

What good looks like

You are ready to leave exploration when:

• Every load-bearing claim is measured, or explicitly flagged as unprobed with the probe named.
• The kill criteria are numbers, and you would actually stop.
• One end-to-end path has been proven on real data — not a diagram of one.
• The name has survived a trademark pass.
• The stack is named as an archetype and passed to lacquer init --stack, so every half of it is gated from the first commit.

Anti-patterns

• The confident PCD. Fluent architecture built on documented premises. Fluency is not evidence.
• Abstraction as insurance. A pluggable layer against a dependency risk nobody measured. Measure the risk; then decide if the seam is worth it.
• Phase 0 as ceremony. A phase whose exit criteria are activities ("outreach", "investigate") rather than numbers. Needledrop's Phase 0 was real precisely because criterion #2 demanded a measured percentage.
• Naming last. The one decision that gets more expensive every commit.
• Onboarding the spike. Running lacquer init inside a Phase 0 throwaway records the spike's stack as the project's stack. Detection is right about what is on disk and wrong about what the project is; --stack is how you say which one you meant.