Writing User Stories for AI-Powered Development

How AI Tools Interpret User Stories

AI coding tools are remarkably literal. They do not ask clarifying questions during code generation. They do not read between the lines. They fill every ambiguity with the most generic, average-case interpretation of your intent.

This means:

• "Build a reading list" → generic CRUD app with no personality
• "Allow users to add articles" → basic form with no validation, styling, or UX consideration
• "Make it look nice" → some AI model's interpretation of "nice" which may not match yours

The tools that produce bad output from AI are not bad tools. They are tools given bad input. The fix is not to find a better AI — it is to write better specs.

The Spec Package Format

A Spec Package is the complete input that produces high-quality AI output. It has four elements:

Element 1: User Story — captures intent

*As a [role], I want [goal], so that [benefit].*

Element 2: Acceptance Criteria — defines behavior in Given/When/Then format

Five or more GWT criteria that cover the happy path, validation, error states, and edge cases.

Element 3: Mockup Description — describes appearance as structured text

Layout, components, colors, typography, states (empty, loading, populated, error).

Element 4: Technical Constraints — specifies implementation

Tech stack, libraries to use or avoid, patterns to follow, performance requirements.

Complete Worked Example: Reading List App

Here are 5 user stories for a reading list app, followed by how to format them as a single Bolt.new prompt:

Stories:

1. As a reader, I want to save article URLs with titles so that I can read 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 articles by tag so that I can find relevant saved content
5. As a reader, I want to delete articles from my list so that I can keep it tidy

Assembled as a Bolt.new Prompt:

> Build a reading list web app using React and Tailwind CSS.

>

> TECH STACK: React 18, TypeScript, Tailwind CSS, localStorage for persistence

>

> DESIGN: Dark background (#0F172A), white cards with subtle borders, Inter font. Minimal, clean aesthetic.

>

> FEATURES (implement all):

> 1. Add article: URL input + title input + tag input (comma-separated). Validates URL format. On submit, adds card to top of list.

> 2. Tags: Each article shows colored tag badges. Clicking a tag filters the list to show only articles with that tag.

> 3. Mark as read: Checkbox on each card. Read articles show reduced opacity and a checkmark. Unread count shown in header.

> 4. Delete: Trash icon on each card. On click, asks "Remove this article?" confirmation, then removes it.

> 5. Filter bar: "All / Unread / Read" tabs plus a list of all tags as filter buttons.

>

> DATA STRUCTURE: { id, url, title, tags: string[], read: boolean, savedAt: Date }

>

> EMPTY STATE: Show "No articles saved yet" with an illustration and an arrow pointing to the add form.

The difference between this and "build a reading list" is dramatic. The AI has no ambiguity left to fill with assumptions.

Iterating When the First Output Is Not Right

Use targeted follow-up prompts, not rewrites. Instead of: "This doesn't look right, redo it." Use:

• "The filter bar should be horizontal, not vertical. Keep everything else."
• "The tag input should use a chip/tag UI — you type a tag and press Enter/comma to add it as a chip."
• "The confirmation dialog should be a modal overlay, not a browser confirm()."

Targeted prompts preserve what is working and fix only what is not.

Cross-Reference: Spec-Driven Development

For projects beyond a single feature, the Spec Package format is the foundation of the SDD pipeline. The SDD Framework module formalizes this into structured requirements documents, design specs, and task breakdowns that give you full traceability from idea to deployed code.

Key Takeaways

• AI tools fill ambiguity with generic assumptions — eliminate ambiguity with specific specs
• A Spec Package combines story + acceptance criteria + mockup description + technical constraints
• Format your stories as a single structured prompt for tools like Bolt.new
• Use targeted follow-up prompts to iterate — never scrap and rewrite an entire spec
• The Spec Package format scales to the full SDD pipeline for complex multi-feature projects