-
-
Notifications
You must be signed in to change notification settings - Fork 7
Troubleshooting
Alp Yalay edited this page Aug 10, 2025
·
1 revision
Symptoms: Shallow research, generic responses, missing technical details
Solutions:
- Use Gemini 2.5 Pro - Superior research capabilities with 1M token context
- Provide more detail in your answers - more context leads to better research
- Be specific about your industry - mention specific competitors, technologies, user types
- Ask follow-up questions - "Can you elaborate on [specific area]?"
Symptoms: Questions too simple or too complex
Solutions:
- Double-check your level selection (A/B/C)
- Switch paths mid-conversation - "Actually, I'm more of a [level], can you adjust the questions?"
- Clarify your background - "I know [specific skills] but not [other areas]"
Symptoms: Generated PRD doesn't match your needs
Solutions:
- Request specific adjustments - "Make this more detailed for developers" or "Simplify this for beginners"
- Upload your research - Part I research significantly improves PRD quality
- Be specific about features - Don't say "social features," say "user can like and comment on posts"
Symptoms: Wrong features marked as must-have vs nice-to-have
Solutions:
- Review your answers - Were you clear about what's essential?
- Request re-prioritization - "Move [feature] from must-have to nice-to-have because [reason]"
- Think MVP-first - Only include features absolutely necessary for core value
Symptoms: Suggestions too complex, too simple, or don't match preferences
Solutions:
- Be explicit about constraints - "I only want to use JavaScript" or "Must work on mobile"
- Mention your existing knowledge - "I already know React" or "I've never used databases"
- Request alternatives - "Show me 3 different approaches with pros/cons"
Symptoms: Budget recommendations don't match your constraints
Solutions:
- Clarify your actual budget - "I can only spend $X total" vs "I can spend $X/month"
- Ask for free alternatives - "Show me how to build this using only free tiers"
- Request cost breakdown - "Explain exactly what each service costs and when I'd need to upgrade"
Symptoms: Instructions unclear, missing steps, wrong tech stack
Solutions:
- Ensure all documents were uploaded - PRD and Technical Design are required
- Verify technical level matches - Should be consistent across all parts
- Request clarification - "Explain step [X] in more detail"
- Ask for corrections - "The tech stack should be [X] not [Y]"
Symptoms: Agent builds wrong features, uses wrong tech stack, doesn't follow requirements
Solutions:
- Start with explicit instruction - "First, read NOTES.md completely and confirm you understand the project"
- Reference documents directly - "According to the PRD, feature X should work like Y"
- Break into smaller tasks - "Just implement user authentication first, then we'll move on"
Symptoms: Generated code is too complex, uses advanced patterns unnecessarily
Solutions:
- Emphasize MVP focus - "This is an MVP - choose the simplest solution that works"
- Set explicit constraints - "Use basic HTML/CSS/JavaScript only" or "No external libraries unless necessary"
- Request simpler alternatives - "This seems complex. What's a simpler way to achieve the same result?"
Symptoms: Runtime errors, build failures, features don't function
Solutions:
- Share exact error messages - Copy/paste the full error, don't paraphrase
- Provide context - "This error happens when I try to [specific action]"
- Test incrementally - "Let's test this one feature before adding more"
- Ask for debugging help - "Walk me through debugging this error step by step"
"Cursor won't read .cursorrules"
- Check file is in project root
- Restart Cursor after adding the file
- Use "Ctrl/Cmd + Shift + P" → "Cursor: Reload Window"
"AI suggestions are irrelevant"
- Use "@codebase" to reference entire project
- Use "@file" to reference specific files
- Clear conversation and start fresh
"Can't install Claude Code"
# Try alternative installation
npm uninstall -g @anthropic-ai/claude-code
npm cache clean --force
npm install -g @anthropic-ai/claude-code"Claude Code doesn't start"
- Check Node.js version:
node --version(should be 18+) - Verify API key is set correctly
- Try:
claude --helpto test installation
"Cascade AI not working"
- Ensure you're using latest Windsurf version
- Check internet connection for AI model access
- Try simpler prompts first
Bolt.new/Lovable not generating what you want:
- Be more specific in descriptions - Include exact features, user flows, visual style
- Break into phases - "First, create a simple landing page with [specific elements]"
- Iterate gradually - Make small changes rather than big revisions
Solutions:
- Reference PRD directly - "According to our PRD, this feature should [specific behavior]"
- Show the AI your PRD - Upload or copy relevant sections
- Break down requirements - "Let's implement just the core user story first"
Solutions:
- Test on actual devices - Don't just resize browser window
- Request responsive design - "Make this work properly on phones and tablets"
- Use mobile-first approach - "Design for mobile first, then adapt for desktop"
Solutions:
- Identify bottlenecks - "Why is this page loading slowly?"
- Optimize incrementally - Fix one performance issue at a time
- Use browser dev tools - Ask AI to help interpret performance metrics
Solutions:
- Follow deployment guide - Use the specific instructions from your Technical Design
- Check environment variables - Ensure all required config is set
- Test locally first - Make sure everything works in development
- Use platform-specific help - Vercel, Netlify, etc. have detailed deployment docs
Solutions:
- Take breaks between parts - Complete one part per day if needed
- Focus on one thing at a time - Don't worry about Part III while doing Part II
- Use the Quick Start Guide - Follow the simplified version first
- Ask for help - Each AI can help clarify what you need to do next
Solutions:
- Small changes - Update the current part and continue
- Major changes - Consider restarting from Part II with new requirements
- Feature creep - Resist adding features; save new ideas for version 2
Solutions:
- Before Part IV - Go back to Part III and redo with new preferences
- After Part IV - Generate new NOTES.md and config files with new stack
- During building - Ask AI: "How do I convert this from [old tech] to [new tech]?"
Prevention: Always save files locally and consider using Git
Recovery:
- Check browser downloads - Files might be there
- Recreate from memory - Answer the questions again (faster second time)
- Use chat history - Copy from AI platform if conversation is still available
Solutions:
- Check service status - Platform might be down temporarily
- Try alternative tool - Switch to backup option
- Contact support - Most platforms have help documentation
- Use free alternatives - Cline + Gemini CLI as backup
When to restart:
- Major requirement changes
- Wrong tech level selection
- Fundamental architecture issues
How to restart efficiently:
- Keep what works - Save any good research or planning
- Learn from mistakes - Be more specific in new answers
- Go faster - You'll answer questions quicker the second time
- GitHub Issues - Report problems with the workflow templates
- AI Platform Discord/Forums - Tool-specific communities
- Stack Overflow - Technical implementation questions
- Reddit - r/ChatGPT, r/ClaudeAI, r/LocalLLaMA communities
- Business strategy questions - AI gives technical advice, humans give business advice
- Complex integrations - Some APIs require human experience
- Legal/compliance issues - Always consult professionals for legal matters
- Design feedback - Humans better for subjective design decisions
When reporting issues:
- Specific steps to reproduce
- Expected vs actual behavior
- Screenshots or error messages
- Your technical level (A/B/C)
- Which tools you're using
- Browser and operating system
Remember: The workflow is designed to be resilient. Most issues can be solved by being more specific in your prompts or trying a slightly different approach. Don't give up! 🚀