kevmoo/dash_skills/dash-discover

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

By default, scans report Defect and Capability rules while suppressing Alternative idiom rules (checks-migration, pattern-matching, matcher-best-practices) when existing code is already valid. Pass --include-alternatives (or target a rule directly via --rule <id>) to opt into alternative-idiom checks:

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

<!-- DISCOVERY_RULES_START -->

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

<!-- prettier-ignore -->

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

<!-- DISCOVERY_RULES_END -->

Tier 2: Token-Efficient Outline Probing

To capture complex cross-cutting architectural patterns beyond regexes:

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

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

1. 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).

1. 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 Trigger, Lifecycle & Confidence:

• Address Defect findings first (fragile or unportable patterns), then

evaluate Capability opportunities against project goals; treat Alternative idiom migrations (--include-alternatives) as opt-in.

• Focus on finite migrations before recurring hygiene sweeps, prioritized by

confidence and affected file count.

• Throttle ubiquitous recommendations (e.g. at most one test framework

migration at a time).

1. 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.

1. Verify Empirically:

• Ensure tests continue to pass (dart test).
• Ensure analysis remains clean (dart analyze).