8.1 — Common pitfalls
On this page
8.1 — Common pitfalls
The patterns we see hurt people most often, and how to avoid them.
Pitfall 1: A prompt that tries to do too much
Symptom: Your features list comes out with 25+ items. Your acceptance criteria are vague. Your agent thrashes.
Cause: Your initial project prompt described the whole product roadmap, not v1.
Fix: Rewrite the prompt to cover only the v1 surface. Save the rest for a later regeneration once v1 ships. "Marketplace v1: browse + book. Reviews and operator dashboards are v2."
Pitfall 2: Vague acceptance criteria
Symptom: Your agent submits something, but it's the wrong something. You send it back. It submits another wrong something. Repeat.
Cause: Your AC said "filter UI works" instead of "price-range slider with min/max bounds matching the listings on screen."
Fix: Edit any AC that doesn't read like a passing test. Five minutes of editing saves hours of rework.
Pitfall 3: Approving everything before starting
Symptom: You spend a whole day reviewing 80 ACs, then start your agent, then realize features 3 and 4 needed editing.
Cause: You treated approval like a one-shot gate. It's not.
Fix: Approve in waves. Start with the spine of the product (2-3 foundational features). Plan sprints. Run your agent on Sprint 1 while you continue approving more. Re-plan after each wave.
Pitfall 4: Forgetting to re-plan after edits
Symptom: Your agent keeps claiming ACs you've already deleted or rewritten.
Cause: You edited the spec but didn't click Re-plan on the Plan tab.
Fix: Re-plan after any meaningful change to acceptance criteria. It's quick — usually under a minute — and it keeps your agent in sync.
Pitfall 5: Letting a passed AC stay wrong
Symptom: CI marked something passed but the work is actually broken. You're tempted to "unpass" it.
Cause: passed is terminal by design — to keep the audit log trustworthy.
Fix: Don't try to rewrite history. Instead:
- Edit the AC's content (or add a new follow-up AC).
- Approve the new draft.
- Treat the old
passedAC as historical.
This is the intentional friction. It keeps your audit log meaningful.
Pitfall 6: Using the same account from multiple windows
Symptom: Two of your IDE windows both try to claim the same AC; one errors with race.
Cause: Two MCP sessions, same API key, both asking for next-ready at the same time.
Fix: This is actually working as designed — atomic claims prevent double-work. The losing window should just call get_next_ready_criterion again to pick up a different AC.
Pitfall 7: Putting git stash in an agent's tool calls
Symptom: Your agent's session crashes mid-stash and your working tree is empty.
Cause: git stash from a tool call is very unsafe — if the call gets terminated between the stash and the pop, you lose all uncommitted work.
Fix: Tell your agent to commit a WIP checkpoint instead of stashing. "Before running typecheck on a clean tree, commit a WIP and revert it after." Lost stash hours are a known footgun across multiple AI coding tools.
Pitfall 8: Treating the spec as one-and-done
Symptom: You finish a sprint, change your mind about a feature, and the spec is now out of date. Your agent keeps building toward the old plan.
Cause: You stopped editing the spec once you started building.
Fix: The spec is living. A 10-minute refresh once a week (deleting obsolete ACs, adding new ones, re-planning) keeps the agent and the product aligned.
Pitfall 9: Skipping personas
Symptom: Your user stories all say "As a user, I want…" — generic, non-specific, hard to grade.
Cause: You didn't review the personas, so user stories defaulted to generic.
Fix: Read your generated personas. Edit any that feel like cardboard cutouts. Then regenerate user stories — they'll automatically tie to your sharper personas.
Pitfall 10: Sharing one account across a team
Symptom: The audit log says "user-abc-123" did everything — you can't tell who approved what.
Cause: You're sharing credentials.
Fix: One account per person. Pro+ supports teams; use seats so the audit log stays meaningful.