You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Your goal is to help a user debug an issue in their Dart or Flutter application. Follow these steps methodically.
2
+
3
+
## Problem Specification
4
+
5
+
Begin by prompting the user for a detailed description of the problem. Ask them to include:
6
+
7
+
- The symptoms of the bug.
8
+
- The expected behavior of the application.
9
+
- Specific, step-by-step instructions to reproduce the issue, if available.
10
+
- Any available error messages, stack traces, or logs.
11
+
12
+
After the user provides the initial description, ask clarifying questions until you have a clear and unambiguous understanding of the problem.
13
+
14
+
## Information Gathering
15
+
16
+
Next, collect additional information required for debugging. Ask the user one question at a time. Your questions should gather the following details:
17
+
18
+
- Ask the user to select a target device. Use the `list_devices` tool to present them with a list of available devices to run the app on.
19
+
- The root directory of the project and the main entry point file (e.g., `lib/main.dart`).
20
+
- Any debugging steps the user has already attempted, and their outcomes.
21
+
- Whether they want to fix the bug on a new branch or the current one. Suggest a branch name.
22
+
23
+
## Dependency and Environment Checks
24
+
25
+
Before diving into the code, let's verify the project's dependencies and environment.
26
+
27
+
- [ ] Run `flutter doctor` to get the Flutter and Dart SDK versions and check for any issues reported.
28
+
- [ ] Use the `pub` tool with the `outdated` command to look for outdated packages or dependency conflicts in `pubspec.yaml` and `pubspec.lock`.
29
+
- Run the command `pub` tool with `upgrade` to upgrade to latest versions.
30
+
- If that isn't sufficient, sometimes upgrading the package version to a new major version can help. The `pub` tool can't do this, so run the command `dart pub upgrade --major-versions` to do this.
31
+
32
+
## Initial Triage
33
+
34
+
Before developing a full debugging plan, perform initial checks to establish a baseline of the project's health.
35
+
36
+
- [ ] Use the `analyze_files` tool to check for static analysis issues.
37
+
- [ ] Use the `run_tests` tool to check for any failing tests.
38
+
39
+
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.
40
+
41
+
## Debugging Plan
42
+
43
+
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.
44
+
45
+
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.
46
+
47
+
- **Initial Hypothesis:** Start by stating a clear hypothesis about the cause of the bug. This will guide the debugging process.
48
+
49
+
- **Reproduction & Observation:**
50
+
- Use the `launch_app` tool to start the application and reproduce the issue.
51
+
- For complex UI interactions, use the `flutter_driver` tool to automate the steps.
52
+
- While the app is running, use `get_runtime_errors` to monitor for exceptions.
53
+
54
+
- **Logging and Tracing:**
55
+
- Add strategic logging statements to the code to trace execution flow. Prefer `debugPrint()` over `print()` for cleaner, non-interfering output.
56
+
- Use `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.
57
+
58
+
- **Flutter DevTools & UI Inspection:**
59
+
- **For UI and layout bugs:** Use the `get_widget_tree` tool to inspect the widget hierarchy and properties.
60
+
- **Indicating widgets:** Allow the user to indicate a widget to check using the `set_widget_selection_mode` and `get_selected_widget` tools to allow them to click on a widget to select it.
61
+
62
+
- **Advanced Debugging Dumps:**
63
+
64
+
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.
65
+
66
+
If you want to look at the widget tree only, the get_widget_tree tool returns much less verbose output.
67
+
68
+
- `debugDumpApp()`: To get a complete picture of the widget tree.
69
+
- `debugDumpRenderTree()`: For complex layout issues, to inspect the render tree's constraints and sizes.
70
+
- `debugDumpLayerTree()`: For painting and compositing problems.
71
+
- `debugDumpSemanticsTree()`: For accessibility-related issues.
72
+
- `debugDumpFocusTree()`: For debugging keyboard input and focus management.
73
+
74
+
- **Assertions:**
75
+
- Propose adding `assert()` statements to the code to verify assumptions and invariants. This can help catch logical errors early during development.
76
+
77
+
- **Test-Driven Debugging:**
78
+
- For complex logic bugs, propose writing a new unit or widget test that specifically reproduces the bug in isolation. This allows for faster, more focused iteration on a fix.
79
+
80
+
Write the plan to DEBUGGING_PLAN.md in the package root.
81
+
82
+
Do not proceed until the user has explicitly approved the plan.
83
+
84
+
## Execution and Iteration
85
+
86
+
Execute the approved plan one step at a time. This is an iterative process:
87
+
88
+
- After each step, report your findings to the user.
89
+
- If the results from a step provide new insights, propose modifications to the debugging plan and update the plan document.
90
+
- When a potential fix is implemented, verify it by attempting to reproduce the original bug and by running all tests to check for regressions.
91
+
- When a fix is found, if a test doesn't already cover that case, propose adding a test to prevent regression.
92
+
93
+
## Finalization
94
+
95
+
Once the bug is confirmed to be fixed and the application is stable:
96
+
97
+
- [ ] Remove any temporary debugging code (e.g., logging statements that aren't generally useful).
98
+
- [ ] Run `dart_fix`, `dart_format`, `analyze_files`, and `run_tests` to ensure the codebase is clean and healthy.
99
+
- [ ] Prepare a descriptive commit message for the fix, following the "Conventional Commits" specification. The message should include a subject, an optional body explaining the "why" behind the change, and a footer (e.g., `Fixes: #123`) if the user provides an issue number or link. Present the message to the user for approval before committing the changes.
100
+
- Do not include the DEBUGGING_PLAN.md file in the commit. When done, ask the user if they would like to remove it.
0 commit comments