docs(experience): add documentation for discover experience command

.omp/commands/discover-experience.md

@@ -0,0 +1,95 @@
+---
+description: Read every URL referenced in docs/experience and docs/projects and enrich entries with verifiable material
+---
+
+# Discover Experience
+
+Enrich the canonical resume sources under `docs/` by mining the URLs each entry
+already references — repos, live sites, press, docs, package registries, talks.
+The goal is to capture verifiable facts (metrics, scope, adoption signals,
+tech-stack evidence) that the YAML doesn't state yet.
+
+Scope: $ARGUMENTS — if empty, process all of `docs/experience/` and
+`docs/projects/`. If a directory, glob, or entry name is given, restrict to it.
+
+## Phase 0 — Inventory
+
+1. `search` for URL-bearing fields across the scope: `url`, `repo`, `links`,
+   `demo`, `press`, `website`, `github`, or any bare `https://` value.
+2. Build a per-entry worklist: entry → [urls]. Entries with zero URLs get
+   flagged in the final report as "no external evidence available" — do not
+   invent sources for them and do not web_search around them unless the entry
+   names a public artifact (a company, a published app, a talk).
+3. Deduplicate URLs shared across entries; fetch once, attribute to all.
+
+## Phase 1 — Fetch (fan out)
+
+Use `read` directly on every URL — GitHub repos, PRs, arxiv, registries, and
+docs pages all come back as structured markdown with anchors intact. For GitHub
+repos, prefer the scheme forms where useful (`issue://`, `pr://`) and read the
+README, release notes, and repo metadata (stars, language breakdown, last
+commit) rather than crawling the tree.
+
+If the scope spans more than ~5 entries, fan out with `task`: one subagent per
+entry, each yielding a schema-shaped result:
+
+```
+entry_id, urls_read[],
+facts[]: { claim, source_url, anchor, confidence: high|medium|low },
+contradictions[]: { yaml_says, source_says, source_url },
+dead_links[]
+```
+
+Per-fact rules for extraction:
+- **Verifiable only.** A fact must be literally present at the source — star
+  counts, npm downloads, contributors, changelog entries, press quotes, listed
+  features, launch dates, named integrations. No inference from vibes.
+- Prefer facts a resume can use: scale, adoption, recency, named technologies,
+  third-party validation (press, citations, forks).
+- Marketing copy on my own sites is weak evidence — mark it `confidence: low`
+  and prefer registry/repo/press corroboration.
+- Note anything at a URL that contradicts the current YAML (dates, stack,
+  scope, status). Contradictions are findings, not silent fixes.
+
+## Phase 2 — Enrich
+
+For each entry, merge subagent findings and propose a YAML diff:
+
+- Append to (or create) an `evidence:` list: `{ fact, source, retrieved: <date> }`
+- Strengthen existing bullets ONLY when a fetched fact directly supports the
+  upgrade (e.g., bullet says "open-source CLI" and the repo shows 1.2k stars →
+  bullet may carry the number, with the evidence pointer)
+- Add missing structural fields the source confirms: `stack`, `status`
+  (active/archived per repo activity), `launched`, `press`
+- Record `dead_links:` so I can fix or drop them
+- NEVER touch employers, titles, dates, or claims of ownership based on
+  fetched content — external sources verify artifacts, not my role in them.
+  If a source implies a role discrepancy, list it under contradictions instead.
+
+Show me the diff per entry via `ask` (apply / skip / edit). Apply approved
+diffs with `edit`. Do not batch-apply without approval.
+
+## Phase 3 — Gap search (optional, ask first)
+
+After URL mining, ask whether to run `web_search` for coverage the YAML doesn't
+link: press mentions, conference talks, podcast appearances, aggregator
+listings tied to entry names (company names, product names, my name). Same
+extraction rules; anything found enters as `confidence: medium` at best until
+I confirm it's actually about me/my work — common-name collisions are real.
+
+## Phase 4 — Report
+
+- Entries enriched vs. skipped, fact count by confidence level
+- All contradictions found (these matter more than the enrichments)
+- Dead links list
+- Entries with no external evidence — candidates for the interview command
+  instead, since their content can only improve through my own answers
+
+## Hard rules
+
+- Every added fact carries `source` + `retrieved` — unattributed facts are
+  banned from docs/.
+- Enrichment never rewrites bullet prose style; it adds facts and evidence.
+  Wording polish belongs to the resume-optimize pass.
+- If a fetch fails, record it and move on. Never substitute memory of what a
+  page "probably says."