discovery

Discovery Skill

Invocation Modes

Two modes of operation:

• Standalone (/discovery [scope]): Full 6-phase flow with interactive triage (Phases 0-6)
• Embedded (from session-end when discovery-on-close: true): Phases 0-4 only, returns structured findings to session-end

The scope argument accepts: all (default), code, infra, ui, arch, session, audit, vault, or comma-separated like code,session.

Phase 0: Bootstrap Gate

Read skills/_shared/bootstrap-gate.md and execute the gate check. If the gate is CLOSED, invoke skills/bootstrap/SKILL.md and wait for completion before proceeding. If the gate is OPEN, continue to Phase 1.

<HARD-GATE> Do NOT proceed past Phase 0 if GATE_CLOSED. There is no bypass. Refer to skills/_shared/bootstrap-gate.md for the full HARD-GATE constraints. </HARD-GATE>

Phase 1: Read Session Config

Read and parse Session Config per skills/_shared/config-reading.md. Store result as $CONFIG.

Discovery-relevant fields (parse these specifically):

• discovery-on-close, discovery-probes, discovery-exclude-paths, discovery-severity-threshold, discovery-confidence-threshold, discovery-parallelism
• test-command, typecheck-command, lint-command
• pencil, vcs, cross-repos, stale-issue-days

Phase 2: Stack Detection & Probe Activation

Detect the project's tech stack via marker file checks. Use Glob and run checks in parallel:

| Marker File(s) | Activates | |---------------------------------------|-------------------------| | package.json | JS/TS probes | | tsconfig.json | TypeScript probes | | requirements.txt / pyproject.toml | Python probes | | Dockerfile / docker-compose.yml | Container probes | | vercel.json / .vercel/ | Vercel probes | | .github/workflows/ | GitHub CI probes | | .gitlab-ci.yml | GitLab CI probes | | supabase/ | Supabase probes | | next.config. / nuxt.config. | SSR probes | | tailwind.config.* | Tailwind probes | | Pencil in Session Config | design-drift probe | | .orchestrator/bootstrap.lock | harness-audit probe | | .vault.yaml OR Session Config vault-integration.enabled: true | vault probes | | package.json / requirements.txt / Cargo.toml AND Session Config slopcheck.enabled: true AND slopcheck.sources includes "discovery" | supply-chain probe (skills/discovery/probes-supply-chain.md) |

Build Activation Set

1. Start with all probes whose marker files are present
2. If discovery-probes is set in config, intersect with that list
3. If a scope argument was passed, restrict to that category
4. Remove probes whose activation conditions are not met

The audit probe activates when bootstrap.lock is present OR when discovery-probes config explicitly lists audit.

The vault probe activates when .vault.yaml is present in the repo root OR when vault-integration.enabled: true in Session Config OR when discovery-probes config explicitly lists vault.

Exclude Paths

Default exclude paths (always apply):

• node_modules/, .git/, dist/, build/, .next/, .nuxt/, coverage/

Add any paths from discovery-exclude-paths in Session Config.

VCS Detection

VCS Reference: Detect the VCS platform per the "VCS Auto-Detection" section of the gitlab-ops skill.

Status Report

Report: "Discovery: [N] probes active across [categories]. Stack: [detected]. Threshold: [severity]."

Phase 3: Probe Execution

--since Filtering (when since_ref is provided)

When since_ref is set (passed from the /discovery --since <git-ref> invocation):

1. Call changedFilesSince(since_ref) from scripts/lib/discovery/helpers.mjs.
2. If the helper throws (ref unresolvable), surface the error to the user and halt.
3. If the result is [] (no files changed since the ref), emit:

`` No files changed since <since_ref>. Skipping discovery. `` and exit with status 0. Do NOT fall back to a full-repo scan.

1. If the result is a non-empty array, pass it as changedFiles context to each probe agent below.

Probe exemptions: The vault-staleness probe and the harness-audit probe are EXEMPT from --since filtering — they always scan the full repository because their analysis targets metadata (vault narrative staleness, bootstrap lock state) that is not file-diff-gated. This exemption is advisory: no code enforcement is applied in this wave. The probe agents will naturally read whole-repo state; the changedFiles context they receive from --since is informational and does not restrict their glob/grep scope.

Dispatch probe agents IN PARALLEL using the Agent tool. Group by category (max $CONFIG['discovery-parallelism'] agents, default 5):

Cursor IDE: No Agent() tool available. Run probes sequentially within the current session — one category at a time. Complete each category's analysis before moving to the next.

• Code probes agent: Runs all activated code probes (hardcoded-values, orphaned-annotations, dead-code, ai-slop, type-safety-gaps, test-coverage-gaps, test-anti-patterns, security-basics)
• Infra probes agent: Runs all activated infra probes
• UI probes agent: Runs all activated UI probes
• Arch probes agent: Runs all activated arch probes
• Session probes agent: Runs all activated session probes
• Audit probes agent: Runs harness-audit probe
• Vault probes (skills/discovery/probes-vault.md): invokes skills/discovery/probes/vault-staleness.mjs and skills/discovery/probes/vault-narrative-staleness.mjs directly via node. Each probe returns {findings, metrics, duration_ms}. The runner reports FINDING: blocks per finding and appends summary records to .orchestrator/metrics/vault-staleness.jsonl and vault-narrative-staleness.jsonl.
• Supply-chain probe (skills/discovery/probes-supply-chain.md): invokes skills/discovery/probes/supply-chain-slopcheck.mjs directly via node. Gated: only activates when slopcheck.enabled: true AND "discovery" is in slopcheck.sources (Session Config). The probe returns {findings, summary}. SLOP findings surface as critical, ASSUMED as medium, LEGITIMATE packages generate no finding. See probes-supply-chain.md for invocation details and classification reference.

Each agent receives:

• The probe definitions from probes-intro.md (confidence scoring reference) AND the category-specific probes-<category>.md file for this agent's category (include the actual grep commands/patterns in the prompt)
• The exclude paths list
• The project root path
• When since_ref was provided and changedFiles is non-empty: the changedFiles array (informational context for per-probe filtering — per-probe filtering enforcement is deferred to W3)
• Tools: Read, Grep, Glob, Bash (read-only -- no Edit/Write)
• Instruction: "Run each probe. For each finding, output EXACTLY this format:"

FINDING:
  probe: <probe_name>
  category: <category>
  severity: <critical|high|medium|low>
  file_path: <absolute path>
  line_number: <number>
  matched_text: <exact text from tool output>
  title: <short title for the finding>
  description: <1-2 sentence description>
  recommended_fix: <concrete fix suggestion>

"If a probe's activation condition is not met, skip it with: SKIPPED: <probe_name> -- <reason>" "If a probe command fails, skip it with: FAILED: <probe_name> -- <error>" "Do NOT fabricate findings. Only report what tool output confirms."

CRITICAL: run_in_background: false for all agents.

Skip categories with no activated probes (don't dispatch empty agents).

Phase 4: Verification & Scoring

After all probe agents complete:

4.1 Parse Findings

Collect