Pitfalls

Pitfalls are not trivia. They are the traps that make AI-generated stack work look finished while it is still broken.

Pitfall Table

Pitfall	Symptom	Root cause	Detection	Fix or workaround	Status
`[pitfall]`	`[what user or agent sees]`	`[why it happens]`	`[command, doc, log, device check]`	`[safe fix]`	`[confirmed

Version managers selecting the wrong runtime.
Global CLIs diverging from project-local CLIs.
Templates assuming package managers, SDKs, emulators, or native toolchains that are not installed.
Cloud docs showing current syntax while local generated projects use an older version.

Missing Android, iOS, browser, desktop, or OS permissions.
Runtime prompts that only appear on real devices.
Background work, notifications, file access, camera, clipboard, and network APIs behaving differently across targets.

Build succeeds but package command fails.
Package succeeds but signing fails.
Signed artifact installs locally but fails store validation.
Release docs require account state, certificates, bundle IDs, or policy forms that the agent cannot verify.

Privacy disclosures missing for local storage, sync, analytics, camera, contacts, location, notifications, or AI processing.
Store review requires screenshots, age rating, data safety, export compliance, or payment policy answers.
Examples ignore regional policy or target-market constraints.

Dev build feels fine but production build regresses.
App works in browser but fails on device or WebView.
Local data, migrations, startup cost, bundle size, or background sync fail under realistic data.

Add a stale-doc warning when any source has high drift risk:

> **Warning:** This stack changes quickly around [area]. Re-check [source] before using this command or API in a real app.

Agents should stop and ask for direction when: