3.3 — Tips for better output

A few rules of thumb that consistently produce better specs.

Write a great initial prompt

Your project prompt is the seed for everything downstream. Spend five minutes on it.

Do:

• Describe the product in plain terms (what it does, for whom, why).
• Name your primary user persona explicitly: "Built for cost-conscious first-time scuba divers."
• Mention the v1 scope — what's in, what's out. "v1 covers browsing + booking; reviews and operator dashboards come later."
• Mention the differentiator: "unlike Padi Travel, we surface real prices including all gear hire and surcharges."

Don't:

• Specify the tech stack unless it's a hard requirement.
• List every feature you can think of (you'll get an unbuildable spec).
• Use marketing copy. ("revolutionary AI-powered platform" → noise; "marketplace for scuba dives" → signal).

Be ruthless about scope

The single biggest reason specs come out unworkable is that the prompt tries to do too much.

If your features list is 20+ items, your prompt is too broad. Trim back to the smallest viable surface. You can always add features later — but a tight v1 is what makes an AI agent able to actually finish.

Edit before you regenerate

Once you've got an initial spec, editing is faster and cheaper than regenerating. A few common edits:

• Rename features to match how you talk about them. The names ripple into user stories and ACs.
• Delete features you don't need in v1. Anything you keep eats agent time later.
• Add features you wanted that didn't make the first cut. Click "Add Feature" on the Features tab.

Approve in waves

You don't have to approve everything before you start. A common rhythm:

1. Approve the first 2-3 features (the spine of the product).
2. Plan sprints. Sprint 1 picks up those approved criteria.
3. Start your agent on Sprint 1.
4. While the agent works, approve the next set of features.
5. Re-plan. Sprint 2+ now includes the new approved ACs.

This means the spec is a living document — not a wall of text you have to finalize upfront.

Watch out for vague acceptance criteria

ACs are where your agent does real work. Vague ACs cause vague code.

If you spot a vague AC, edit it. Five minutes of editing saves an hour of agent rework.

Use the right persona-to-story mapping

Every user story should be tied to one persona — the one most affected by it. If you find yourself wanting to tie a story to "all users", you probably need a more specific persona, or the story is too generic.

Re-plan after big edits

After you add, remove, or significantly edit a chunk of acceptance criteria, click Re-plan on the Plan tab. This:

• Re-runs the dependency analyzer
• Re-groups ACs into sprints
• Updates the agent's next-ready queue

Skipping this means your agent might keep picking up old ACs that no longer reflect what you want.

Trust the dependency graph

When VibeMap says an AC depends on another, don't override it casually. The dep graph is what lets your agent work in the right order without you having to babysit. If an AC really doesn't depend on what the analyzer thinks it does, edit the dependency directly — but check first.

Keep the spec close to the truth

If you change scope while building (you decide to drop a feature, or pivot to a different user), update the spec. The agent reads from the spec — if the spec is stale, the work will be too.

A 10-minute spec refresh once a week is much cheaper than a half-built feature that's no longer relevant.

Where to go next

• Use the API directly → 4 — API reference
• Connect your IDE agent → 5 — MCP server
• Common pitfalls to avoid → 8 — Tips and best practices