Joon Hee Kim

Building AI Product

I Spent Two Days Speccing a Product I’ve Never Used. Here’s What I Should Have Done Instead.

I’ve been building an AI-powered investment research tool. Multi-sector supply chain analysis, automated thesis management, adversarial stress-testing, the works. Over the past two days, my AI coding assistant and I produced:

  • 11 specification documents (1,400+ lines of Prisma schemas, API contracts, propagation algorithms)
  • 5 interactive UI mockups
  • 2 autonomous build prompts for parallel repo construction
  • 3 rounds of external review that caught 38 bugs
  • 4 rewrites of the research system

And I still haven’t used the product once.

I’m not writing this to complain. The specs are genuinely good. The architecture survived adversarial review. The code is building right now in two terminals. But somewhere around rewrite #3 of the research pipeline, I realized: I’ve been designing in the dark. Every “discovery” — the database path bug, the Google News quality problem, the fake seed data issue, the cron-doesn’t-work-on-sleeping-laptops problem — was something I would have found in the first 10 minutes of actual use.

This post is the framework I wish I’d followed from the start.

The Mistake Pattern

Here’s what I did:

Vague idea
  → Design everything
    → Spec everything
      → Review the specs
        → Fix the specs
          → Build everything
            → Discover it doesn't work as imagined
              → Rewrite

Time from idea to first real use: weeks. Amount learned before building: almost nothing.

The specs captured what I imagined. They didn’t capture what I needed. Those are different things, and you can’t tell them apart without using the product.

The Pattern That Actually Works

Vague idea
  → Build the core loop in one sitting (2-4 hours)
    → Use it yourself for 3 days
      → Write down what's missing from actual use
        → Build the missing pieces
          → Use it for a week
            → Now you know what the real product is
              → Spec and build that

Time from idea to first real use: one afternoon. Amount learned before committing to architecture: everything that matters.

Phase 0: Three Questions (30 minutes)

You have a vague idea. Don’t design. Don’t spec. Don’t open a code editor. Answer three questions:

Q1: What’s the atomic action? The single thing you’d do with this product every day. Not the grand vision. The smallest useful interaction.

For my tool: “Read a morning briefing about my investment theses and decide if anything needs action.”

Q2: What data makes that action possible? The minimum data. Not the complete data model.

“5-10 theses with evidence, and today’s relevant news matched to them.”

Q3: What does ‘done’ look like for a single session? When you close the app, what did you accomplish?

“I know which of my theses got stronger or weaker today, and I either acted or decided not to.”

If you can’t answer these clearly, the idea isn’t ready. Keep thinking. Don’t build.

Phase 1: The One-Sitting Prototype (2-4 hours)

Build a thing you can actually use tomorrow morning. Not a demo. Not a mockup. A tool that does the atomic action with real enough data to feel real.

Rules:

  • Single file or single page. No architecture.
  • Hardcoded data is fine. A JSON file with 3-5 real examples you wrote yourself.
  • No database. No API. No auth.
  • The UI can be ugly. The interaction must be real.
  • You must be able to open it tomorrow and DO the thing, end to end.

For my tool, this should have been: a single HTML page with 5 hand-written investment theses, 3 real news headlines I found that morning, and buttons to mark each as “strengthens / weakens / irrelevant.” Save decisions to localStorage. Total build time: 2 hours.

What I actually did: designed a 15-table database schema, a 4-agent pipeline, and a propagation engine with dampening coefficients. Before I’d ever used the product once.

Phase 2: The 3-Day Test (3 days, 15 min/day)

Use your prototype every day for 3 days. Actually use it. Not “look at it and imagine using it.” Wake up, open it, do the thing.

After each session, write exactly 3 things:

  1. What I actually did (not what I planned to do)
  2. What was missing that made me reach for another tool
  3. What I never touched

After 3 days you have 9 observations. These are worth more than any spec document. They reveal:

  • The real workflow (vs. the imagined one)
  • The real data requirements (vs. the theoretically complete model)
  • The features that seemed essential but aren’t

What I would have learned from 3 days of prototype use:

  • The morning flow takes 5 minutes, not 30. Design for 5.
  • I only care about 2-3 theses on any given day. Showing 22 is noise.
  • The adversarial challenge feature is annoying before coffee. Move it to evening.
  • Data quality matters infinitely more than data automation. One real finding from an SEC filing beats 12 scraped headlines.
  • The trade action needs to be one click from the signal, not buried in a separate page.

I’d have cut half the features before writing a single spec.

Phase 3: The Architecture Decision (2-4 hours, one document)

Now you know what the product is. Not what you imagined — what you experienced. Design the architecture around the real workflow, not the theoretical one.

Write one document. It covers:

  1. The daily loop — exactly what happens, in order, in how many minutes
  2. The data model — only the tables you need for the daily loop
  3. The build order — what to build first, based on what you use most

Build order rule: data before display. I built 5 beautiful UI screens before building the research system that produces the data they display. For weeks, the app showed gorgeous visualizations of made-up numbers. The system that produces real numbers — fetching SEC filings, validating edge weights against actual 10-K disclosures — came last and went through 4 rewrites because I kept discovering what “real data” actually means.

If the data is wrong, the UI doesn’t matter. Build the data pipeline first.

Review the architecture, not the specs. One reviewer spending 20 minutes on your data model and daily loop catches more than three reviewers reading hundreds of pages of spec. I had three independent reviews converge on the same fundamental flaw — I was asking the AI to compute answers to complex systems questions when it should only narrate answers that were computed deterministically. Twenty minutes of review found what weeks of internal iteration never would.

Phase 4: Build With AI (1-2 weeks with Claude Code, 4-6 weeks without)

This is where AI coding tools change the math. What used to take a solo developer months now takes days. But the speed multiplier makes the Phase 1-3 discipline more important, not less.

Here’s why: if you can build the wrong thing in 3 days instead of 3 months, you need to know it’s the wrong thing FASTER. The prototype-first approach isn’t about being slow and careful. It’s about learning fast enough to match your build speed.

With Claude Code, the build order is:

Days What Why This Order 1-3 Data pipeline. Real data from real sources. Validate quality. If data is bad, nothing else matters. 4-6 Core daily loop UI. The thing you do every morning. You should be using the product by day 4. 7-9 Supporting features. Only the ones your daily use revealed as necessary. Kill anything you haven’t missed in a week. 10-12 Automation. Scheduled jobs, background research, maintenance. Automate what you’ve been doing manually. 13-15 Polish and testing. Only on what you actually use. Don’t polish features you’ll cut.

Key principle: use it every morning starting day 4. You’re building and using simultaneously. Each morning reveals what to build that afternoon. By day 15, the product has been shaped by 10+ days of real use, not by imagination.

Without Claude Code, stretch this to 4-6 weeks, but the principle is the same: use it as soon as the core loop works, even if everything else is missing.

The build prompt pattern that works:

Don’t give AI a 200-line spec and say “build all of it.” Give it clear steps with verification at each one:

Step 1: Create the data model. Verify: these 5 queries return correct data.
Step 2: Create the API. Verify: these 3 curl commands return expected JSON.
Step 3: Create the UI. Verify: these visual tests pass.

Each step has a definition of done that the AI can check itself. It commits after each passing step and continues. When something breaks, the blast radius is one step, not the entire build.

Phase 5: The First Real Week (1 week, then ongoing)

Use it daily. Not testing — using. After each session, write:

  • Time spent
  • Actions taken
  • Data quality (did I trust what I saw?)
  • What I wanted to do but couldn’t

After the week you know: what you use daily (keep, polish), what you used once (keep, don’t polish), what you never touched (cut), and what’s missing (the next sprint).

The Meta-Rules

I’m writing these down because I violated every one of them and paid the price.

1. Prototype before you spec. A 2-hour prototype teaches more than a 2-day spec. The spec captures what you imagine. The prototype reveals what you need.

2. Data before display. If the data is wrong, the UI doesn’t matter. Build the pipeline that produces trustworthy data before the interface that displays it.

3. Bootstrap before maintenance. Don’t build a system that maintains data quality before you have quality data to maintain. Get the initial data right — manually or via automated deep research — then automate the daily upkeep.

4. Use the absolute shortest path to daily use. Every day you’re not using the product is a day you’re designing in the dark.

5. Kill features from experience, not imagination. You can’t know what’s unnecessary by thinking about it. You know by using the product for a week and noticing what you never touched.

6. Review architecture, not documents. The fatal flaws live in the data model and daily loop, not in the UI spec.

7. Show where you’re wrong. This applies to the product and to the process. The most valuable moment in my build was when three reviewers independently identified the same architectural flaw. I’d been iterating on the wrong design for days. External eyes found it in minutes. Seek review before you’re ready.

The Timeline

Day 0 (evening):     Answer Q1/Q2/Q3. If stuck, sleep on it.
Day 1 (afternoon):   Build one-sitting prototype. One page. Real-ish data.
Day 2-4 (morning):   Use it daily. 15 min/day. Write 3 observations.
Day 5 (afternoon):   One-page architecture doc. Data model + loop + order.
Day 5 (evening):     One reviewer, 20 minutes. "What will break?"
Day 6-8:             Build the data pipeline. Real data. Validate.
Day 9-12:            Build the daily loop UI. Use it each morning as you build.
Day 13-15:           Polish what you use. Cut what you don't.

Fifteen days. Assumes you’re using Claude Code or similar AI tools for the build phases. Without them, triple days 6-15. The Phase 0-4 timeline doesn’t change — that’s thinking and using, not coding.

At every step you know what you’re building because you’ve been using it the whole time. No surprises. No rewrites. No spec documents about features you’ll never touch.

What I’m Doing Differently Next Time

My tool is building right now. It’ll probably work. The specs survived adversarial review, the architecture is sound, the code is executing in two parallel terminals as I write this. But I spent two days writing specs for a product I could have prototyped in an afternoon and learned more from three mornings of use than from three rounds of review.

Next project, I’m starting with a single HTML file and a cup of coffee.

Concepts Spec gap