discover · git:20260519.a169a22 · 2026-05-19 · sha256 69f27ef0ffc78c7e
discover git:20260519.a169a22A
Immutable. This exact content is served forever at /api/v1/blob/69f27ef0ffc78c7e.
--- name: discover <<<<<<< HEAD description: "Primary router for discovery, debugging, investigation, quality, and exploration workflows. Analyzes user intent and dispatches to debug, bughunt, quick-review, deep-review, coverage, testing-strategy, learn, index, tour, impact, assist-review. The recommended entry point for any 'find out', 'check', 'review', or 'investigate' request." --- # Discover - Investigation & Quality Router `/draft:discover` is the single front door for all investigation, auditing, pattern learning, and quality exploration activities. ## When to Use - Any debugging or root-cause work - Code quality reviews (lightweight to exhaustive to architectural) - Coverage analysis and test strategy design - Discovering and codifying project conventions - Monorepo indexing and context aggregation - Project tours, impact analysis, or reviewer assistance ## Routing Logic Strong keyword and phrase matching with fallback to a menu when intent is broad or compound. Several quality commands auto-chain (e.g. review may call bughunt). | User Intent Keywords | Dispatches To | Purpose | |---------------------------------------------------|--------------------------|---------| | debug, investigate bug, reproduce, isolate, diagnose | `/draft:debug` | Structured 4-phase debugging | | hunt bugs, find bugs, exhaustive sweep, regression hunt | `/draft:bughunt` | 14-dimension bug hunt + regression tests | | quick review, fast review, sanity check, lightweight review | `/draft:quick-review` | 4-dimension review (~2 min) | | deep review, production audit, module audit, ACID compliance | `/draft:deep-review` | Full module lifecycle + architecture audit | | coverage, code coverage, test coverage report | `/draft:coverage` | Coverage measurement and gap report | | test strategy, testing plan, coverage targets, pyramid | `/draft:testing-strategy` | Test approach design | | learn patterns, discover conventions, update guardrails, anti-patterns | `/draft:learn` | Pattern mining + guardrail evolution | | index services, aggregate context, monorepo index | `/draft:index` | Monorepo service context aggregation | | tour, walkthrough, onboard me, getting started tour | `/draft:tour` | Guided interactive project tour | | impact, blast radius, change impact, analytics | `/draft:impact` | Telemetry-driven change impact reports | | assist review, help reviewer, PR architectural audit | `/draft:assist-review` | Risk audit to support human reviewers | ## Dispatch Examples User: "debug the flaky test in CI" → dispatches to `/draft:debug "flaky test in CI"` User: "quick review the PR diff" → dispatches to `/draft:quick-review [pr context]` User: "run a deep production audit on the auth service" → dispatches to `/draft:deep-review auth` User: "learn the coding patterns in this repo and tighten guardrails" → dispatches to `/draft:learn` User: "index the monorepo so agents see all services" → dispatches to `/draft:index --init-missing` ## Auto-Chains & Recommendations - `/draft:implement` and `/draft:review` (primary) frequently call into discover skills at phase boundaries. - `/draft:discover "full quality"` may suggest or chain review + bughunt + coverage. - After major changes, `/draft:discover learn` is recommended to keep guardrails current. Direct specialist commands are preserved as shims for existing workflows and scripts. ======= description: Draft Phase 0 — produce a discovery.md code-spike report before spec freeze. Run by draft:new-track as the first step on any new track. Reads current code, enumerates hotspots, names mode-selection flags, surfaces load-bearing open questions, and records references. Output is a first-class artifact verifiable by the citation verifier against metadata.json:synced_to_commit. --- # /draft:discover — Phase 0 Code Spike > Mandatory first step for any new Draft track. Builds the `discovery.md` > artifact that subsequent `spec.md` / `hld.md` / `lld.md` cite as their > grounding source. Without it, downstream artifacts are not eligible for > `ready-for-review` promotion. ## Contract - Schema: [core/shared/discovery-schema.md](../../core/shared/discovery-schema.md) - Template: [core/templates/discovery.md](../../core/templates/discovery.md) - Hygiene rules: [core/shared/template-hygiene.md](../../core/shared/template-hygiene.md) - Citation verifier: `scripts/tools/verify-citations.sh tracks/<track-id>` (exit 0 = clean, 1 = drift detected; add `--tolerance N` to widen the line-window match) ## Inputs 1. The track ID (from `metadata.json:id`). 2. The pinned commit (`metadata.json:synced_to_commit` — set by `draft:new-track` Step 0a). 3. The problem statement the user provided. ## When `draft/graph/schema.yaml` exists Follow the graph-first lookup contract in [core/shared/graph-query.md](../../core/shared/graph-query.md) §Mandatory Lookup Contract. The discovery hotspots **must** start from the graph; filesystem `grep` is permitted only after a documented graph miss. ## Procedure 1. **Read the problem statement.** Extract candidate nouns (component names, file extensions, flag names, behaviors). 2. **Query the graph** with each candidate. Capture modules and entry symbols. If the graph has no schema, fall back to `grep` and document the miss per `graph-query.md` rules. 3. **Read 3–10 files** at the entry points found. Quote the exact `path:line-range` you read. 4. **Fill the Hotspots table** with at least N rows (default 3; configurable via `metadata.json:hygiene_budget.discovery_min_hotspots`). 5. **Fill the Mode selection table** with every flag, env var, build option, or cluster-feature gate the reading surfaced. 6. **Write Open Questions**: each is a load-bearing unknown. Examples: "Does dependency X expose a public API for behavior Y?", "Is constraint Z still active given upstream change W?". Surface, do not hide. 7. **Write References**: flat list of files and named functions. 8. **Save** `discovery.md` under the track directory; emit the `generated_at` timestamp; do NOT touch `metadata.json:status` (still `draft`). ## Output gate The skill output is rejected if any of: - `discovery.md` has zero Hotspot rows AND no `_NONE_FOUND_` justification. - Any `path:line` citation in Hotspots fails `verify-citations.sh`. - Open Questions list is empty AND no `_NONE_FOUND_ — <reason>` line. - Any forbidden sentinel from `template-hygiene.md` appears in the output. ## Re-spiking If a later phase reveals the original spike missed material facts: 1. Rename the existing file to `discovery-<isodate>.md`. 2. Run `draft:discover` again to produce a fresh `discovery.md`. 3. Bump `metadata.json:synced_to_commit` if the re-spike was driven by an upstream change. ## Red Flags — STOP if you're: See [shared red flags](../../core/shared/red-flags.md). Skill-specific: - Writing hotspot rows without `path:line` citations. - Inventing function names not present in the code at `synced_to_commit`. - Filling the Open Questions section with non-blocking commentary instead of load-bearing unknowns. - Re-running discovery silently on top of an existing `discovery.md` without archiving the previous file. ## Graph Usage Report End every invocation with the standard footer from [core/shared/graph-query.md](../../core/shared/graph-query.md) §Graph Usage Report: ``` ## Graph Usage Report - Graph files queried: <list> - Modules / files identified via graph: <list> - Grep fallbacks: <count, with justification per item> - Justification when NONE: <if graph was not consulted> ``` >>>>>>> a79c14023e16774c77463870ac3510b728e8a91c