The other day I came across a Claude Code todo list that looked like this:

✓ Read and identify all screenshots
✓ Categorize screenshots into 4 groups
◼ Create folders and move/rename screenshots
☐ Write business requirements doc per screenshot

Four steps. Clean. The kind of plan a vibe coder would screenshot and post on X with the caption "AI is unreal right now."

And honestly — it is a good plan. Better than 90% of what I see in the wild. But it's also one tiny step away from producing 30 beautifully written documents that quietly contradict each other.

Let me walk you through why this strategy works, where it breaks, and the one step I'd add before you let your AI write a single requirement.

The strategy, decoded

Before we critique anything, let's give credit where it's due. This workflow has three things going for it that most vibe coding sessions don't.

It uses screenshots as the source of truth. Most people start vibe coding from a vague idea in their head — "build me a project management app like ClickUp but cheaper". The AI has nothing concrete to anchor on, so it hallucinates a generic CRUD app, and you spend the next three days correcting it. Screenshots flip this. They're concrete. They show real states, real data, real edge cases. An AI looking at a screenshot can't drift as far as one listening to a wish.

It categorizes before it documents. The "4 groups" step is the unsung hero here. Without grouping, you end up with thirty disconnected requirements docs that don't share vocabulary. Grouping forces pattern recognition — these eight screens are all CRUD on the same entity, these five are reporting, these three are settings. That clustering naturally maps to modules or bounded contexts later, which is exactly what you want when you start translating documents into code.

It produces atomic, reviewable artifacts. One BRD per screenshot. Small, self-contained, easy to diff, easy to hand to Claude Code with a prompt like "generate the Livewire component for this spec." You can iterate on one BRD without rewriting the whole project.

This is genuinely a good foundation. If you stopped reading here and ran with it, you'd be ahead of most teams.

But we're not stopping here.

Failure mode #1: BRDs without a shared vocabulary

Here's what happens when you skip from categorization straight to writing BRDs.

Screenshot 03 shows a customer list. The AI writes: "The system shall display a paginated list of **Customers."

Screenshot 11 shows a customer detail page. The AI writes: "The **Member* profile shall include..."*

Screenshot 19 shows the same person logging in. The AI writes: "Upon authentication, the **User* is redirected..."*

Screenshot 24 is a B2B contact view. The AI writes: "Each **Account* has a primary contact..."*

Customer. Member. User. Account. Four words. Same entity. Different document. Different author session. Different vibes.

Now imagine you feed all 30 BRDs to Claude Code and ask it to generate migrations. Watch what happens.

You get a customers table, a members table, a users table (probably from Laravel's default), and an accounts table. None of them reference each other. The Eloquent relationships are guesswork. Half your Actions take Customer $customer, the other half take User $user, and your form requests use both interchangeably.

This is the most common failure I see in screenshot-driven workflows, and it never shows up in the demo. It shows up in week three, when you realize half your codebase is talking past itself.

The fix is a vocabulary extraction step. Before any BRD gets written, you produce a glossary.md that looks something like this:

| Term     | Definition                              | Aliases                  |
|----------|-----------------------------------------|--------------------------|
| Customer | An organisation that purchases services | Account, Client          |
| Member   | An individual user within a Customer    | User, Contact, Staff     |
| Order    | A purchase transaction                  | Sale, Invoice (informal) |

Now when the AI writes BRD-019, it consults the glossary, sees that "Member" and "User" are aliases for the same concept, and picks one canonical term. Suddenly your thirty documents speak the same language.

Failure mode #2: Screen-driven design is not system design

Screenshots tell you what the user sees. They don't tell you what the system does.

Look at any login screen. The screenshot shows a form with email, password, and a button. The BRD writes itself: "User enters credentials, system authenticates, user is redirected to dashboard."

What the screenshot doesn't show:

• The rate limiter that locks the account after five failed attempts
• The audit log entry that records every login attempt, successful or not
• The webhook that fires to your CRM when a new user logs in for the first time this month
• The background job that recomputes the user's permission cache
• The SSO redirect path that bypasses the password field entirely
• The API endpoint that mobile clients use, which doesn't render this form at all

None of that is in the picture. All of it is in the system.

If you're building a SaaS — and especially if you're in the kind of architecture I tend to work in, where you've got a hub-and-spoke pattern with things like identity providers, API gateways, and webhook routers — half your architecture lives behind the UI. A pure screenshot-driven workflow will miss it entirely.

The fix is to add a step per group (not per screenshot) where you explicitly list the non-UI concerns:

• Background jobs and scheduled tasks
• Webhooks emitted and consumed
• Permission matrix (who can do what)
• Audit and observability requirements
• API contracts for non-UI consumers
• Integration points with other modules

This doesn't need to be exhaustive on the first pass. It just needs to exist so you remember to look behind the curtain.

Failure mode #3: Losing the trail

The original workflow says "create folders and move/rename screenshots." Good — but rename them to what?

If your screenshots become screenshot_001.png, screenshot_002.png, you've lost the only useful thing you could have encoded: traceability.

Three months later, when you're debugging a Livewire component and you want to know "what was the original requirement for this?", you want to be able to trace:

Code:        app/Livewire/CustomerList.php
   ↑ generated from
BRD:         docs/brd/g01-s03-customer-list.md
   ↑ extracted from
Screenshot:  screenshots/g01-customers/s03-list-view.png

The naming convention does this work for you, silently. Something like g01-s03-customer-list.png tells you immediately: group 1, screen 3, the customer list. The BRD inherits the same ID. The generated code references it in a docblock. Now you have a chain of custody from pixel to production.

This costs you nothing at rename time. It costs you everything if you skip it.

Failure mode #4: Inconsistent BRD structure

If you let the AI freestyle each BRD, you'll get thirty documents with thirty slightly different structures. One has a "User Stories" section, another has "Use Cases", a third has "Functional Requirements", a fourth jumps straight into a numbered list of behaviours.

This isn't a vibe problem, it's a parsing problem. When you later want to feed these BRDs into Claude Code to generate code, the AI does much better with predictable structure. Same headings, same order, same vocabulary for sections.

Define the template once, before the loop:

# {Screen ID} — {Screen Name}

## Purpose
What this screen exists to do, in one sentence.

## Actors & Permissions
Who can access this screen, and what role gates apply.

## Entities Referenced
List of glossary terms this screen interacts with.

## User Actions
For each action: trigger, validation rules, side effects, success state, failure state.

## States
Empty state, loading state, error state, success state.

## Non-Functional Notes
Performance expectations, accessibility, audit requirements.

## Open Questions
Things the screenshot doesn't tell us and we need to confirm.

Now every BRD looks the same. Claude Code knows exactly where to look for "what validation rules apply to the Save button." Your reviewers know exactly where to add comments. Your future self thanks you.

The refined workflow

Putting it all together, here's what I'd actually run:

1. ✓ Read and identify all screenshots
2. ✓ Categorize into groups (by feature area, not screen type)
3. ◼ Create folders and rename with traceable IDs (g{NN}-s{NN}-{slug})
4. NEW: Extract shared entities, enums, and permissions → glossary.md
5. NEW: Define the BRD template once
6. ☐ Write BRD per screenshot, referencing the glossary
7. NEW: Per group, document non-UI concerns (jobs, webhooks, audits, APIs)
8. NEW: Synthesise — produce the domain model, module boundaries, Action inventory

Steps 4, 5, 7, and 8 are the ones that turn a demo into a system.

Step 8 is where this becomes powerful, by the way. Once you have a glossary, BRDs in consistent format, and non-UI concerns mapped, you can feed all of it to Claude Code with a prompt like:

Given this glossary and these BRDs, generate the Eloquent models with relationships, Form Requests, invokable Actions, and Pest tests for the Customers module.

And the output will actually fit. The naming will be consistent. The relationships will make sense. The tests will reference the right entities. Because you did the upstream work of giving the AI a coherent context to operate in.

The lesson nobody puts on the screenshot

If you take one thing from this, take this:

AI is excellent at extraction. Humans must still define the schema of what's extracted.

The screenshot-to-BRD workflow looks like the AI is doing all the work. It isn't. It's doing the typing. The thinking — the categorization, the vocabulary, the template, the boundaries between modules — that's still yours. Skipping those steps doesn't speed you up. It just defers the cost to a later point in the project where it's ten times more expensive to fix.

Vibe coding isn't about letting the AI decide. It's about giving the AI a structured enough world that its decisions stop being random.

Add the glossary step. Define the template. Document what the screenshot doesn't show. Encode the trail in your filenames.

Then let it rip.

If you've tried screenshot-driven workflows on your own projects, I'd love to hear which failure modes you've hit and how you worked around them. Drop a comment.