dash-discover · diff

git:20260913.945146b to git:20261030.3a1a8c4

23 added, 12 removed. Audit A to A.

---

name: dash-discover

description: |-

Diagnoses latent architectural modernization opportunities across Dart and

Flutter packages (language idioms, testing hygiene, CLI patterns, doc rot)

and prescribes matching specialized skills.

key_features:

- Architectural Gap Diagnosis

- Latent Modernization Discovery

- Two-Tier Prescriptions & Evidence

---

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

```bash

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

```

Or for structured machine ingestion:

```bash

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:

+ ```bash

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

+ ```

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.

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

### 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

```

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.

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

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