Dash Discover (Meta-Skill)

The Meta-Skill Discovery Engine evaluates a Dart or Flutter project's architecture, language idioms, testing patterns, and documentation health to uncover latent modernization opportunities that standard static analysis passes ignore.

---

1. When to use this skill

Use this skill when:

• 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:

1. Testing Architecture (dart-migrate-to-checks-package): Detects test or flutter_test in dependencies when checks is absent.
2. Dart 3 Language Idioms (dart-use-pattern-matching): Detects legacy else if (... is ...) type cascades and returning switch statements.
3. CLI Architecture (dart-build-cli-app): Detects ad-hoc bin/*.dart CLI entrypoints lacking structured argument parsing.
4. Cross-Platform Robustness (dart-use-path-package): Detects manual path string concatenation without package:path.
5. Testing Architecture (dart-generate-test-mocks): Detects handwritten fake or mock class definitions without mockito or mocktail.
6. Testing Architecture (dart-matcher-best-practices): Detects unidiomatic expect() assertions (e.g. expect(x.length, ...) or expect(x.isEmpty, true)).
7. 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:

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

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

2. 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).
3. 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:

1. 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).
2. 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.
3. Verify Empirically:
   • Ensure tests continue to pass (dart test).
   • Ensure analysis remains clean (dart analyze).