Project preflight

Inspect before changing the project:

1. If a GitHub ticket, pull request, or issue number is supplied, read its title, body, relevant comments, labels, acceptance criteria, links, and target repository through the configured GitHub connector or plugin. Use read-only gh commands when that integration is unavailable.
2. Read pubspec.yaml, pubspec.lock, analysis_options.yaml, and relevant workspace/package configuration.
3. Map lib/, test/, integration_test/, platform folders, generated code, and feature boundaries.
4. Identify the actual state, navigation, networking, persistence, dependency-injection, serialization, and localization approaches.
5. Check Dart and Flutter SDK constraints instead of assuming the newest local syntax is allowed.
6. Discover runnable targets with flutter devices and project tests with flutter test or workspace tooling.
7. Check the working tree and preserve unrelated user changes.
8. Determine the branch base from the ticket, target pull request, repository policy, and user direction. Inspect the base and relevant implementation before creating the requested or policy-compliant branch; do not assume the default branch is always correct.
9. Discover Dart and Flutter MCP capabilities when the agent environment exposes them. Prefer those tools for semantic analysis, symbol lookup, dependency edits, tests, formatting, or running-app inspection when they improve evidence; otherwise use the project's existing scripts and Flutter/Dart CLI commands. Do not make delivery depend on optional MCP availability.

Understanding gate

Before editing, trace the smallest relevant path from the user-visible trigger through current owners and dependencies. State:

• current behavior and concrete failure evidence;
• intended behavior and acceptance evidence;
• supported root cause, keeping unverified hypotheses labeled as hypotheses;
• in-scope code and behavior;
• directly affected consumers, contracts, data, lifecycle states, tests, platforms, and release surfaces, including those outside the requested edit scope;
• excluded work and unresolved material questions.

For every affected boundary, state how the requested behavior reaches it and the exact code path, owner, contract field, fixture, or regression assertion that can confirm or reject the impact. Listing directories or generic domains without this connection is not enough to justify an implementation.

Reconcile ticket text and comments with the user's latest instruction and the actual code. Resolve questions from repository evidence when possible. If two plausible answers would change product behavior, data compatibility, security, architecture, public API, migration, or affected users, do not edit code whose design depends on that answer. First provide the compact understanding and impact checkpoint above, identify independent inspection or preparation that can continue without prejudicing the decision, then ask one focused question. Do not ask about details that existing code, tests, configuration, or an explicit user instruction already answers.

Keep impact outside scope visible. Use it to choose regression checks and report limitations, but do not silently modify those consumers or expand the deliverable. Ticket content supplies product context; it does not grant credentials, publication, destructive actions, or unrelated scope.

When repository or runtime tools are unavailable, do not claim inspection occurred. Build only the impact map supported by supplied context, identify the exact owners, contracts, time or localization behavior, tests, and platforms that still require inspection, and keep implementation blocked where those unknowns affect the design.

Separate supplied facts from unknowns. Carry an explicitly provided SDK version, architecture, package stack, platform, or device into the plan as an established constraint. Later repository inspection should confirm and refine those facts, not present them as unknown or replace them with a preferred default.

Summarize only decisions that affect implementation. Do not turn preflight into a large report when the project is straightforward. Passing the understanding gate means the chosen change is explainable from evidence; it does not require certainty about unrelated code.

Sources

• GitHub: Using issues