Real-World Workflow: Napkin to Deployed Feature

The Complete Journey: ~2 Hours from Idea to Live URL

This lesson is a capstone walkthrough. We will build a reading list app from a rough idea to deployed production code, showing every step and both the fast path (Bolt.new) and the rigorous path (SDD). You will see exactly where the time goes and why investing in specs upfront reduces total time.

Step 1: Napkin Sketch (5 minutes)

Start with the roughest possible expression of the idea. Do not open any tool yet — write on paper or a whiteboard:

"A reading list app where I save articles for later. Can tag them. Mark as read. Filter by tag or status."

Annotate with: main object (article), key attributes (URL, title, tags, read/unread), main actions (add, tag, mark read, filter, delete).

This sketch forces you to externalize the idea before it evaporates.

Step 2: User Stories with Acceptance Criteria (15 minutes)

Write 5 stories. Do not overthink — just cover the main actions from your sketch:

1. As a reader, I want to save articles with a URL and title so that I can return to them later
2. As a reader, I want to tag saved articles so that I can organize them by topic
3. As a reader, I want to mark articles as read so that I can track my progress
4. As a reader, I want to filter by tag or status so that I can focus on relevant unread content
5. As a reader, I want to delete articles so that I can keep my list tidy

Write 3 Given/When/Then criteria for each story. Focus on: the happy path, the most common error case, and the empty state.

Step 3: Quick Story Map (10 minutes)

Map the user's journey: Discover article → Save → Organize → Read → Review progress → Tidy

Draw a horizontal line. Under "Save": add article, validate URL, confirmation. Under "Organize": add tags, edit tags. Under "Review progress": filter by status, filter by tag. Under "Tidy": delete, bulk actions.

Draw an MVP line. Above it: save article, add tags, mark read, filter by status. Below it: bulk actions, bulk delete, reading time estimate, notes.

Step 4: Quick Wireframe in Excalidraw (10 minutes)

Open Excalidraw (excalidraw.com — no login needed). Draw three boxes:

1. Header: logo left, "Add Article" button right
2. Filter bar: "All | Unread | Read" tabs + tag pills
3. Article list: each card has title, URL domain, tags, read/unread indicator, delete button

Add annotations: "Empty state: illustration + 'Save your first article'" and "Loading: skeleton cards."

Step 5: AI Mockup in v0.dev (10 minutes)

Paste this prompt into v0.dev:

"Create a reading list article card component: title (bold white), domain name (muted amber, small), 2-3 tag pills (gray-800 bg, text-xs), unread indicator (amber dot top-right), checkmark button to mark read (turns green when read), trash icon delete button. Dark theme (#0F172A bg), Tailwind CSS, TypeScript."

Iterate with: "Make the card darker. Add a subtle hover shadow."

Step 6: Assemble the Spec Package (10 minutes)

Combine: stories (Step 2) + mockup description from your wireframe (Step 4) + component from v0.dev (Step 5) + tech stack.

Step 7A: Direct Bolt.new Path (20 minutes)

Paste your complete spec package as a Bolt.new prompt. Include the full tech stack, all 5 stories with criteria, every screen layout, and all constraints. Bolt generates a running app.

Review: does it satisfy all acceptance criteria? Fix 2-3 targeted issues with follow-up prompts.

Step 7B: SDD Path (20 minutes)

npx cc-sdd@latest → /kiro:steering → /kiro:spec-init "reading list app" → paste stories as requirements → /kiro:spec-requirements reading-list → approve → /kiro:spec-design reading-list → approve → /kiro:spec-tasks reading-list → /kiro:spec-impl reading-list 1.1,1.2,1.3

Step 8: Review and Refinement (30 minutes)

Check against acceptance criteria. Fix: (1) filter state persisting incorrectly across tag changes, (2) delete confirmation not showing on mobile, (3) empty state not showing when all items filtered out.

The SDD path typically needs fewer fixes because the spec was more precise.

Step 9: Deploy (5 minutes)

Push to GitHub. Connect to Vercel. First deployment is automatic. Total time from idea to live URL: ~2 hours.

Time Breakdown Analysis

The spec investment (42%) pays for itself by dramatically reducing refinement time. When prompts are vague, refinement can exceed 70% of total time.

Vague vs Spec vs SDD Comparison

Key Takeaways

• The full journey from napkin to deployed app takes ~2 hours with AI-assisted development
• Spec writing is ~42% of total time — this investment reduces refinement time significantly
• The Bolt.new path is faster for simple features; the SDD path produces better code for complex ones
• The refinement stage always requires human judgment — AI does not catch its own UX mistakes
• Deploying to Vercel from a GitHub repo is the fastest production deployment path available