--- model_tier: medium name: source-discovery description: "Use BEFORE planning/coding against a DB schema, API/GraphQL shape, DTO/Model/Entity, or vendor package — read the real source, emit an Evidence Report, stop inventing fields." domain: engineering workspaces: - engineering packs: - engineering-base --- # source-discovery The procedure behind the [`source-discovery`](../../rules/source-discovery-gate.md) rule. Hand-off target from [`think-before-action`](../../rules/think-before-action.md) when a task touches **external or expensive** structure. Definitions (Evidence Report buckets, provenance, trust tiers, the DB-not-in-codebase boundary, the card-worthiness threshold) live in [`evidence-discipline`](../../agent-src/contexts/execution/evidence-discipline.md) — read it once; this file is the executable procedure. ## When to use Before you plan or code against a structure you have **not** confirmed this session: a DB schema, an API/GraphQL shape, a DTO/Model/Entity, a vendor package's surface, or any field/endpoint/column/value. Do NOT use for: trivial edits (rename/typo/format), structure already verified this session, or when the user supplied the verified structure (gate-skip per `rdp-gate`). ## The shape of a run ``` discover the real source → Evidence Report (Verified / Assumed / Gaps) → plan → act → verify with the real tool ``` Scaffold the report cheaply so it never gets skipped: ```bash npx tsx node_modules/@event4u/agent-config/src/scripts/evidence_report.ts git-state # fail-fast: abort if a rebase/merge/cherry-pick is in progress npx tsx node_modules/@event4u/agent-config/src/scripts/evidence_report.ts init --task "" # writes the gitignored session report npx tsx node_modules/@event4u/agent-config/src/scripts/evidence_report.ts add --bucket verified --claim "users.email is unique" --source "db/schema/users.sql:23" ``` **Provenance on every item** (`observed_at` / `source` / `version`). Within a session a read is fresh until the file's mtime changes; **invalidate all session reads when `git rev-parse HEAD` changes**; across sessions always re-read. ## Step 0 — Resolve local structure fresh (NO persistent index) Resolve name → path **fresh** each lookup with `rg` / glob, then read the file fresh. There is **no** persistent bootstrap index (a measured `rg`-latency problem on a large monorepo is the only thing that would justify one — deferred). ```bash rg -n "class User\b|model User|CREATE TABLE .*users" --type-add 'src:*.{php,ts,js,py,go,rb,sql}' -t src ``` ## Procedure — discover and analyze each surface before planning 1. **Identify** which surface(s) the task touches (DB / API / vendor / DTO). 2. **Discover** the real source via the matching sub-procedure below — local before remote, analyzing the actual definition, never memory. 3. **Record** each fact into the Evidence Report with provenance, then build the plan from the report. ### A. DB schema — in-codebase = LOCAL, read fresh, no card **In-codebase** (schema defined by repo migrations / models / ORM / app code, **including** schemaless stores the app controls — Mongoose / Prisma / Firestore rules) → always local & fresh. Dump tables, columns, types, primary/foreign/ unique keys, indexes, relations, and derived filter/sort/group-ability into the session cache with provenance — framework-neutral (MySQL / Postgres / SQLite; ORM-agnostic). The **migration is intended truth, the live DB is actual**; divergence is a drift signal worth surfacing. Only **negative facts** graduate to a committed card (see [`database`](../database/SKILL.md) for the dump procedure). ### B. API / GraphQL — probe + confirm Resolve an OpenAPI/Swagger spec or GraphQL introspection from config/task first. Else run a **read-only, idempotent `GET` probe**, reduced with `jq` — never a full dump, never a write/stateful call, never prod without permission, secrets-aware per [`security-sensitive-stop`](../../rules/security-sensitive-stop.md). A probed positive shape is `trust: low` ("Assumed (from card)" if card-sourced) and must be confirmed against the live surface before use. ### C. Vendor / external-DB docs — card-worthy Card-worthy = **(external package / remote API / DB-not-in-codebase)** AND **(≥3 distinct methods/fields *intended* to be used, OR the source exposes >50 methods and ≥1 is used, OR a prior hallucination on it, OR local types/README are insufficient)** — judged on *intended* use at discovery (still built **before** coding). For a card-worthy dependency named in the task: **local-first** (`node_modules` / `vendor/` README + type defs; the **installed version is ground truth**), then the net (registry → repo host → homepage). **Pin the remote ref to the installed version — never blind `main`.** Reuse [`external-reference-deep-dive`](../../rules/external-reference-deep-dive.md) + [`markitdown`](../markitdown/SKILL.md); honor `source-confidentiality`, `untrusted-input-defense`, `lethal-trifecta-guard`. Persist via the `knowledge-card` template under `agents/knowledge/.md`. ### D. DTO / Model / Entity — local, read fresh Resolve and read the actual class fresh (Step 0). In-codebase → local, no card. ### E. Global cards — leads only (v2, ADR-100) When `knowledge.global_sharing.enabled` (user-global, default on), a matching card may exist in the per-user file-first store (`~/.event4u/agent-config/knowledge/`), promoted from another project. It is a **lead, never a build input**: - Load its **negative facts + pointers** as usable leads (`trust: durable`). - Load any **positive structure** into the Evidence Report under **"Assumed (from card · GLOBAL, unverified)"** — record it with `evidence_report.ts add --bucket assumed --origin global …` and **re-confirm it against the live source this session** before use (version skew / schema drift across projects). Never "Verified" on the global card alone. - A `public`/`vendor` card seen in ≥ `auto_promote_threshold` distinct repos triggers a one-tap promotion **suggestion** (never silent). `proprietary` cards are manual-only and never auto-shared. Record sightings via `_lib/knowledge_global_promote.ts record-seen`. ## Missing structure → fixed extension workflow When the field/endpoint/table you need is **not** there: 1. **Search** the relevant sources. 2. **Not found** — record the **absence-search log** with `searched` *and* `not_searched` (via `evidence_report.ts add --bucket gaps --searched … --not-searched …`). 3. **Negative-fact card** — only **after the search is exhausted across all relevant sources** for that claim: write `type: anti-hallucination`, `polarity: negative`, with `actionable` + `next_step` + a `revalidate_if` trigger ("an OpenAPI spec / contracts dir is added"). A negative fact is a **current-state fact** ("searched X, didn't find X") — not a card-worthiness *decision* (that belongs in notes/ADR). 4. **Extension plan** — a codebase-fitting plan (migration + model/cast/factory/ seeder, or the stack equivalent). **Plan only, never silent execution** ([`scope-control`](../../rules/scope-control.md)). ## Verify after acting (Phase-3 wiring) After acting on discovered structure, verify with the **real tool** per the [`think-before-action`](../../rules/think-before-action.md) matrix — `curl` / Playwright / debugger / test runner / DB query. Any **Assumed (from card)** or `trust: low` line used without this-session confirmation is a violation surfaced post-task. A stale card (installed-version mismatch OR `last_verified` older than N days) is **lead-only**: negative facts + pointers stay usable, positive structure must be re-confirmed. Green is not a correctness proof — high-risk / irreversible steps verify regardless. ## Output The Evidence Report (gitignored session cache), three buckets, soft-capped to ~10–20 decision-relevant facts, produced **before** the plan; plus, where the threshold is met, a thin committed card. ## Evidence v2 — self-building context (heuristics only, never a bypass) Curated project-intelligence (Class A config digests, Class B observed conventions, Class C learned lessons) may be loaded to inform *where to look* and *what convention to expect* — but it is read **for heuristics only** and **never** bypasses a fresh structural read. A field/endpoint/column/value is still confirmed against a live source this session. v2 capture is **write-only into gitignored intake** (the agent may *suggest* a signal, never silently commit); trust and commit are always human-gated. Full model + the three classes + memory tiers: [`project-intelligence`](../../agent-src/contexts/execution/project-intelligence.md). ## Knowledge capture (`api_shape_learned` / `convention_detected` events) A confirmed API/GraphQL shape (§B) or an observed coding convention with ≥ 2 supporting locations is worth persisting for the team, distinct from the per-session Evidence Report above. Append to the knowledge intake — never write a tracked page mid-task: ```bash npx tsx node_modules/@event4u/agent-config/src/scripts/emit_knowledge_event.ts --type api_shape_learned \ --endpoint "" --method "" --request-schema '' --response-schema '' npx tsx node_modules/@event4u/agent-config/src/scripts/emit_knowledge_event.ts --type convention_detected \ --pattern "" --evidence "file:line" --sample-size --scope project ``` `/team-knowledge consolidate` turns accumulated events into `agents/knowledge/concepts/` pages as a reviewed batch — see [`knowledge-pages`](../../agent-src/templates/contexts/knowledge-pages.md). ## Gotchas - A card's positive structure is **never** "Verified" on the card alone — it is "Assumed (from card)" until confirmed this session (R4 P1). - L0–L4 depth labels are documentation only — the same evidence rules apply at every tier; no per-tier relaxation. - The self-log is instrumentation; the deterministic teeth are pointer-CI + the eval. Do not treat a written "verified" as proof. ## Do NOT - Do NOT plan or code against an unconfirmed field/endpoint/column. - Do NOT treat a card as a source of truth or a build input. - Do NOT execute a schema/API extension silently — plan, then hand back. - Do NOT read an intermediate tree mid git-op — fail-fast.