AI Agent Failure Modes
| Failure | Why it happens | Required correction |
|---|---|---|
| Claims cross-platform done after Android run | Agent confuses one target with all targets | List tested and untested targets |
| Adds stale package API | Training data or snippets are outdated | Load current docs/pub.dev and run analyzer |
| Assumes plugin supports web/desktop | Package works on mobile in examples | Check platform support before coding |
| Edits native folders blindly | Agent treats platform code as boilerplate | Read platform docs and isolate changes |
| Stores critical data in preferences | Fast code path looks simple | Use storage decision matrix |
| Claims release readiness from debug mode | flutter run succeeded | Build release artifact and smoke it |
| Commits signing secrets | Agent follows release guide too literally | Stop, use secret management, never print secrets |
| Enables driver extension permanently | App-driving setup copied into production path | Gate behind --dart-define and verify release excludes it |
| Skips accessibility | Visual screenshot looked fine | Run accessibility checklist and screen-reader smoke |
Agent Prompt Addendum
Use this in Flutter implementation prompts:
Before editing, identify target platforms and package/plugin support.
Do not add dependencies without approval.
After editing, run flutter analyze and flutter test.
If platform code or plugins changed, state which targets were actually smoke-tested.
Do not claim release readiness without a release artifact and target-specific checklist.