Flutter App Discovery

Flutter App Discovery

A read-only methodology for rapidly understanding an existing Flutter codebase before writing a single line of code. Run this skill at the start of any session involving an unfamiliar project, or whenever a user asks what the codebase is doing.

Guiding Principle

Never modify files during discovery. This is a reconnaissance phase. All conclusions drawn here feed into subsequent planning and implementation skills. If you cannot read a file, say so — do not guess its contents.

Step 1: Validate the Project Root

Before anything else, confirm this is a Flutter project.

• Check for pubspec.yaml in the working directory.
• If pubspec.yaml is absent, stop immediately and tell the user: "This does not appear to be a Flutter project. No pubspec.yaml was found."
• Check that pubspec.yaml contains a flutter: section.
• If flutter: is absent, note that this may be a plain Dart package, not a Flutter app.

Step 2: Read pubspec.yaml

Extract and record the following:

• name — the package/app name
• description — app description (if present)
• version — current app version (semver + build number)
• environment.sdk — the Dart SDK constraint (e.g., >=3.0.0 <4.0.0)
• environment.flutter — Flutter SDK constraint (if set)
• dependencies — all runtime dependencies with version constraints
• dev_dependencies — all dev-only dependencies
• flutter.uses-material-design — whether Material is enabled
• flutter.assets — declared asset paths
• flutter.fonts — custom font declarations

Flag the following for the summary:

• Any package pinned to an exact version (no ^ or range) — this can block upgrades.
• Any package with a path: dependency — local packages that may not be portable.
• Any package with a git: dependency — unstable, tracks a branch.
• Any flutter_localizations or intl usage — indicates internationalization.

Step 3: Read analysis_options.yaml

If this file exists, extract:

• include: — the lint ruleset in use (e.g., package:very_good_analysis/analysis_options.yaml, package:flutter_lints/flutter.yaml, package:lints/recommended.yaml)
• Any custom rules: overrides — especially rules that are disabled
• analyzer.errors or analyzer.exclude overrides

Determine strictness level:

• very_good_analysis → high strictness (team project, agency standard)
• flutter_lints → standard Flutter strictness
• lints or custom → minimal or custom strictness
• Absent → no lint configuration, flag as a risk

Step 4: Inspect lib/ Structure (2 Levels Deep)

List the top-level directories and their immediate children inside lib/. Do not recurse deeper than 2 levels at this stage.

From the structure, determine the architecture pattern:

Feature-first (recommended):

lib/
  features/
    auth/
    home/
    profile/
  core/
  shared/
  main.dart

Layered (presentation / domain / data):

lib/
  presentation/
  domain/
  data/
  main.dart

Flat / unstructured:

lib/
  screens/
  widgets/
  models/
  services/
  main.dart

MVC/MVVM variant:

lib/
  models/
  views/
  controllers/ (or viewmodels/)

Record which pattern is in use, or note if it is mixed/unclear.

Check main.dart for:

• Entry point widget (e.g., MaterialApp, CupertinoApp, ProviderScope, BlocProvider)
• Theme configuration
• Initial route or home widget
• Any environment-based configuration (e.g., flavor setup, const String.fromEnvironment)

Step 5: Assess Test Coverage Signal

Check for the presence of:

• test/ directory — unit and widget tests
• integration_test/ directory — integration/E2E tests

Count:

• Number of *_test.dart files in test/
• Number of *_test.dart files in integration_test/

Check for:

• A test/helpers/ or test/mocks/ directory — indicates organized test infrastructure
• Import of mocktail, mockito, or flutter_test — indicates mocking strategy

Estimate coverage signal (this is not actual coverage, just a proxy):

• 0 test files → "No tests detected — high risk"
• 1–5 test files → "Minimal testing — some coverage"
• 6–20 test files → "Moderate testing — partial coverage"
• 20+ test files → "Good testing signal — likely meaningful coverage"

Step 6: Check Platform Folders

Android (android/):

• Check android/app/build.gradle for: compileSdkVersion, minSdkVersion, targetSdkVersion
• Check android/app/src/main/AndroidManifest.xml for: declared permissions, intent filters, deep link schemes
• Check for any *.kt or *.java files in android/app/src/main/kotlin or /java — indicates custom native code

iOS (ios/):

• Check ios/Runner/Info.plist for: bundle identifier, permissions usage descriptions, URL schemes
• Check for any *.swift or *.m files in ios/Runner/ — indicates custom native code
• Check ios/Podfile for minimum iOS version

Flag any platform-specific capabilities that have implications for plugin compatibility or OS version requirements.

Step 7: Identify Router Setup

Search the codebase for router configuration:

• GoRouter or go_router import → declarative routing with route definitions
  • Look for GoRouter(routes: [...]) — note top-level routes
  • Check for named routes, route guards, redirect logic
• AutoRoute or auto_route → code-generated declarative routing
  • Look for @AutoRouterConfig annotation
• Navigator.pushNamed or onGenerateRoute → imperative named routing
• MaterialApp(home: ...) with no named routes → ad-hoc imperative routing (no router library)

Record which router is in use and whether there is a central route definition file.

Step 8: Identify State Management

Search for the following imports in lib/:

If multiple state management libraries are found, flag this as an inconsistency — mixing patterns adds cognitive overhead and should be consolidated.

Step 9: Flag Key Dependency Concerns

For each package in dependencies, check:

1. Outdated packages — if you know a package has a significantly newer major version, flag it.
2. Deprecated packages — e.g., pedantic (replaced by lints), provider used alongside riverpod.
3. Security-sensitive packages — anything handling auth, cryptography, storage, networking:
   • flutter_secure_storage, crypto, dio, http, firebase_auth, supabase
   • Note the version and recommend verifying against latest stable.
4. Large packages that may have lighter alternatives — flag only if clearly relevant.

Also scan for:

• Hardcoded strings that look like credentials (API keys, tokens, passwords) in Dart files.
• TODO, FIXME, HACK, XXX comments — count them and note locations.
• debugPrint or print statements left in production code paths.

Step 10: Produce Summary Report

Print a structured summary to the conversation with the following sections:

## Flutter App Discovery Report

### Project Overview
- App name:
- Version:
- Dart SDK:
- Flutter SDK constraint:

### Architecture
- Pattern: [feature-first / layered / flat / mixed]
- Router: [GoRouter / AutoRoute / imperative / none]
- State management: [Riverpod / Bloc / Provider / GetX / setState-only / mixed]

### Key Dependencies
- [List notable runtime dependencies with version]
- Flagged: [any outdated / deprecated / pinned / git dependencies]

### Test Coverage Signal
- Unit/widget tests: [count] files
- Integration tests: [count] files
- Test infrastructure: [mocktail / mockito / none]
- Signal: [None / Minimal / Moderate / Good]

### Platform-Specific Notes
- Android: minSdkVersion, targetSdkVersion, custom native code: [yes/no]
- iOS: minimum iOS version, custom native code: [yes/no]
- Declared permissions: [list]

### Code Quality Signals
- Lint configuration: [ruleset in use or absent]
- TODO/FIXME comments: [count and locations]
- print() statements: [count]
- Hardcoded credential risk: [none detected / flagged locations]

### Risks
- [Bulleted list of risks in priority order]

### Recommended Next Actions
- [Bulleted list of concrete next steps]

Output Artifacts

The summary is always printed to the conversation.

If the user wants the report persisted, write it to: docs/audit/codebase_discovery.md

Create the docs/audit/ directory if it does not exist. Do not write the file unless the user explicitly requests persistence.

Rules

• Never modify any file during this skill. Read only.
• If a file cannot be read (missing, permission denied), note it and continue — do not halt.
• Do not infer content you cannot read. State what is unknown.
• If the project has no pubspec.yaml, stop immediately with a clear message.
• If the user's working directory is unclear, ask before proceeding.
• Do not generate architecture recommendations during discovery — that is the flutter-architecture skill's job.
• Flag but do not fix: hardcoded strings, TODO comments, print statements. Discovery is not remediation.