Do a deep dive to debug a complex issue in a Dart or Flutter app or package.
Investigates and resolves complex bugs in Dart or Flutter applications through systematic debugging.
/plugin marketplace add pleaseai/flutter-plugin/plugin install flutter@pleaseaiWe're going to debug a Dart or Flutter application. Your goal is to help the user debug an issue in their Dart or Flutter application. Follow these steps methodically.
Begin by prompting the user for a detailed description of the problem. Ask them to include:
After the user provides the initial description, ask clarifying questions until you have a clear and unambiguous understanding of the problem.
Next, collect additional information required for debugging. Ask the user one question at a time. Your questions should gather the following details:
list_devices tool to present them with a list of available devices to run the app on.lib/main.dart).Before diving into the code, let's verify the project's dependencies and environment.
flutter doctor to get the Flutter and Dart SDK versions and check for any issues reported.pub tool with the outdated command to look for outdated packages or dependency conflicts in pubspec.yaml and pubspec.lock.
pub tool with upgrade to upgrade to latest versions.pub tool can't do this, so run the command dart pub upgrade --major-versions to do this.Before developing a full debugging plan, perform initial checks to establish a baseline of the project's health.
analyze_files tool to check for static analysis issues.run_tests tool to check for any failing tests.If any issues are discovered, explain their potential impact and recommend a plan to resolve them first. If the user chooses to proceed, acknowledge their choice and continue with the primary debugging task.
Based on the information gathered, formulate a detailed, step-by-step debugging plan. The plan must be presented to the user for their approval before you begin execution.
The debugging strategy should be chosen to yield the best results and may involve a combination of the following techniques. Tailor your plan to the specific type of bug.
Initial Hypothesis: Start by stating a clear hypothesis about the cause of the bug. This will guide the debugging process.
Reproduction & Observation:
launch_app tool to start the application and reproduce the issue.flutter_driver tool to automate the steps.get_runtime_errors to monitor for exceptions.Logging and Tracing:
debugPrint() over print() for cleaner, non-interfering output.hot_reload to apply logging changes quickly while preserving the app's state. If the state needs to be reset, explain that a Hot Restart is needed, and you will need to stop and restart the app.Flutter DevTools & UI Inspection:
get_widget_tree tool to inspect the widget hierarchy and properties.set_widget_selection_mode and get_selected_widget tools to allow them to click on a widget to select it.Advanced Debugging Dumps:
Propose using Flutter's debugDump*() functions for deep inspection when necessary. These can be called from code (e.g., inside a button's onPressed handler) in a debug build and will write copious output to the logs. Be careful where you put these: they can produce too much output to process if placed in build functions, etc. Some strategies to reduce that are: trigger them from an event like a button click, or have a bool that prevents them from running more than once, etc.
If you want to look at the widget tree only, the get_widget_tree tool returns much less verbose output.
debugDumpApp(): To get a complete picture of the widget tree.debugDumpRenderTree(): For complex layout issues, to inspect the render tree's constraints and sizes.debugDumpLayerTree(): For painting and compositing problems.debugDumpSemanticsTree(): For accessibility-related issues.debugDumpFocusTree(): For debugging keyboard input and focus management.Assertions:
assert() statements to the code to verify assumptions and invariants. This can help catch logical errors early during development.Test-Driven Debugging:
Write the plan to DEBUGGING_PLAN.md in the package root.
Do not proceed until the user has explicitly approved the plan.
Execute the approved plan one step at a time. This is an iterative process:
Once the bug is confirmed to be fixed and the application is stable:
dart_fix, dart_format, analyze_files, and run_tests to ensure the codebase is clean and healthy.Fixes: #123) if the user provides an issue number or link. Present the message to the user for approval before committing the changes.