/discovery

name: discovery
user-invocable: true
argument-hint: "[all|code|infra|ui|arch|session|audit|vault|feature] [--since <git-ref>] [--full]"
tags: [quality, discovery, probes, issues]
model: sonnet
model-preference: sonnet
model-preference-codex: gpt-5.4-mini
model-preference-cursor: claude-sonnet-4-6
description: >
  Use this skill when running systematic quality discovery and issue detection. Runs modular probes
  adapted to the project's tech stack, presents findings interactively
  for user triage, and creates VCS issues for confirmed problems.
  Invoked standalone via /discovery or embedded in session-end.

Discovery Skill

Invocation

The user invokes `/discovery` with scope: **$ARGUMENTS** (if empty, default to `all`).

Parse `$ARGUMENTS` before doing anything else. Extract the following flags and tokens in any order:

• `--since <git-ref>` — restrict discovery to files changed since the given git ref (e.g. `HEAD~5`, `main`, a commit hash). Sets `since_ref = <git-ref>`, which is passed into Phase 3 plumbing.
• `--full` — explicit full-repo scan. Sets `full_scan = true`.
• Any remaining tokens are treated as scope specifiers (see the scope enum in § Invocation Modes).

**Conflict check:** If BOTH `--since` and `--full` are present, stop immediately and report:

Error: Cannot use --since with --full. Provide one, not both.

Do NOT proceed with discovery when this conflict is present.

**Argument validation:** Valid scopes: `all`, `code`, `infra`, `ui`, `arch`, `session`, `audit`, `vault`, `feature` (comma-separated for multiple). If any scope is invalid, inform the user: "Invalid scope '[token]'. Valid scopes: all, code, infra, ui, arch, session, audit, vault, feature." and default that token to `all`.

Scan the codebase for quality issues, technical debt, and improvement opportunities within the requested scope. Do NOT skip the interactive triage phase — every finding must be confirmed by the user before issue creation (a lead-guided run confirms by recorded decision, § Lead-guided runs). Evidence before assertions.

Invocation Modes

Two modes of operation:

• **Standalone** (`/discovery [scope]`): Full 6-phase flow with interactive triage (Phases 0-6)
• **Standalone, lead-guided or headless**: the same flow; every triage question takes its recommended answer instead of asking (§ Lead-guided runs)
• **Embedded** (from session-end when `discovery-on-close: true`): Phases 0-4 only, returns structured findings to session-end

<!-- scope-enum SSOT (#762): this line is the canonical token list; the wiring test derives SCOPE_TOKENS from it. Add/remove tokens HERE first, the test guards the other surfaces. --> The `scope` argument accepts: `all` (default), `code`, `infra`, `ui`, `arch`, `session`, `audit`, `vault`, `feature`, 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`) | | `docs/` directory present **AND** Session Config `docs-staleness.enabled: true` | docs-staleness probe (`skills/discovery/probes-docs.md`) | | `CLAUDE.md` (or `AGENTS.md` on Codex CLI) or `README.md` present in repo root | ssot-code-diff probe (`skills/discovery/probes-docs.md`) — always active within the docs category, no Session Config gate |

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`