Asked questions like: "Am I doing this right?", "Am I holding it right?", or "What skills should I use on this repository?"
Entering a new or unfamiliar Dart/Flutter repository and determining where to focus modernization effort.
dart analyze reports clean code (0 errors, 0 warnings), but the codebase may still harbor outdated pre-Dart 3 constructs, legacy matcher assertions, unstructured CLI entrypoints, or rotting doc examples.

When NOT to use (Abstention Guardrails)

Do NOT run or prescribe discovery scans when:

Non-Dart / Non-Flutter Projects: The repository or directory has no pubspec.yaml or Dart source files (e.g. pure documentation repositories or external language services).
Targeted Single-File Edits or Bug Fixes: The user is requesting a narrow, isolated bug fix or single-file adjustment. Do not derail the turn into a broad repository-wide architectural audit unless specifically solicited.
Active In-Flight Breaking Migrations: The repository is midway through a breaking SDK upgrade or uncommitted refactoring. Allow primary migrations to stabilize before running discovery sweeps.

2. Core Mental Model: The Analyzer Blindspot

Static analysis (dart analyze) verifies syntactic and semantic correctness, not architectural quality or modern idiomatic design. A package can pass dart analyze --fatal-infos with zero warnings while simultaneously:

Using 7-branch polymorphic else if (x is Y) cascades instead of concise Dart 3 switch expressions with pattern destructuring.
Relying on legacy package:test expect(actual, matcher) calls instead of fluent, type-safe package:checks.
Storing rotting, unverified code snippets in /// ``` doc comments instead of automated {@example} region testing.
Building ad-hoc monolithic 300+ line bin/main.dart entrypoints without package:args/command_runner.dart.

Dash Discover systematically identifies these latent gaps and points directly to the specialized skills equipped to remediate them.

3. Two-Tier Discovery Protocol

Tier 1: Fast Static Heuristics (<50ms)

Run the discovery CLI from anywhere in the workspace:

dart run dash_discover <path-to-target-package>

Or for structured machine ingestion:

dart run dash_discover <path-to-target-package> --json

The static scanner performs rapid, zero-network checks across 7 built-in rules:

Testing Architecture (dart-migrate-to-checks-package): Detects test or flutter_test in dependencies when checks is absent.
Dart 3 Language Idioms (dart-use-pattern-matching): Detects legacy else if (... is ...) type cascades and returning switch statements.
CLI Architecture (dart-build-cli-app): Detects ad-hoc bin/*.dart CLI entrypoints lacking structured argument parsing.
Cross-Platform Robustness (dart-use-path-package): Detects manual path string concatenation without package:path.
Testing Architecture (dart-generate-test-mocks): Detects handwritten fake or mock class definitions without mockito or mocktail.
Testing Architecture (dart-matcher-best-practices): Detects unidiomatic expect() assertions (e.g. expect(x.length, ...) or expect(x.isEmpty, true)).
Dart 3 Language Idioms (dart-seal-type-hierarchies): Detects closed type hierarchies that are not sealed, so the compiler cannot check switch exhaustiveness over them.

Tier 2: Token-Efficient Outline Probing

To capture complex cross-cutting architectural patterns beyond regexes:

Generate the condensed repository outline (~1k tokens):

dart run dash_discover <path-to-target-package> --outline-only

The outline captures:
- pubspec.yaml (dependencies, dev-dependencies, SDK constraints).
- Shallow directory structure (up to 3 levels deep).
- Structural API signatures and class outlines (via sem entities lib/ --signatures).
Pass the generated prompt (--prompt-only) and outline to a fast model (such as Gemini Flash) along with the active skills catalog to evaluate semantic architectural fit with concrete file evidence.

4. Remediation Workflow

When dash-discover produces recommendations:

Triage by Lifecycle & Confidence:
- Focus on finite migrations first (e.g. core language modernization and testing migrations), prioritized by confidence and affected file count.
- Treat periodic hygiene audits (e.g. cognitive complexity, doc validation) as recurring sweeps rather than one-time migrations.
- Throttle ubiquitous recommendations (e.g. at most one test framework migration at a time).
Follow the Resolved Skill Target:
- Each opportunity output by dash-discover includes a resolved_uri in --json and a clickable link in Markdown.
- If the target skill is installed locally (is_local: true), inspect and follow the local SKILL.md directly (file://...).
- If not installed locally, inspect the upstream definition at the provided github_url or install the skill into your agent environment before applying changes.
Verify Empirically:
- Ensure tests continue to pass (dart test).
- Ensure analysis remains clean (dart analyze).

dash-discover

Dash Discover (Meta-Skill)

1. When to use this skill