| name | find |
| description | Answer questions from stored facts in `facts/`, or research new questions against primary sources (source code, .refs/ clones, live APIs) and write verified facts. Single entry point for both lookup and research. NOT for Marinade doc/repo navigation (use marinade-docs); NOT for settlement/SAM context (load marinade-sam-bond first). |
| when_to_use | research X, verify X, dig into the code, check the source, confirm a claim, is this true, where in the program does, read the implementation, fact needs code verification, trace the logic, find out how X works in the code, .refs/ ds-sam, primary source, what do I know about X, do we have a fact on, recall, look up stored knowledge, check the facts, find the struct, struct definition, field names in source, name the field, exact code identifier, look up in source, search the codebase, ResultSettlementClaims, active_delegation_lamports, auction_effective_static_bid_pmpe, marinade_stake_share, settlement-distributions source, look them up in source, cite the source file and line |
| user-invocable | true |
| arg | <question or topic to research> |
Find
Lookup → answer from facts if sufficient → otherwise research, verify, write, answer.
Always use subagents. Never research in main context.
For settlement/SAM questions, load /marinade-sam-bond first — it has the
settlement type table with exact file paths and domain vocabulary. Use find
for code-level detail once you know what you're looking for.
Step 1: Check existing facts
Spawn an Explore subagent. It:
- Greps
summary: in facts/*.md
- Returns: file path, one-line summary, why it matches
List matched files, what each says, whether it answers, what gap remains.
Verdict: answer directly (sufficient), refresh via Step 2 (stale/partial), or research fresh (no match).
If facts fully answer the question — answer now. Skip Steps 2–3.
Step 2: Research (subagent)
Tools: Read, Glob, Grep, Bash, WebFetch.
Load context skills first, then dig:
/marinade-sam-bond — settlement type table with exact file paths, epoch
lifecycle, .refs/ repo pointers. Load this before any settlement/SAM dig./marinade-docs — repo clone commands, live API base URLs, GCS bucket paths./marinade-ecosystem — what each repo/package does, program IDs, SDK map.
Once you know what you're looking for: grep the tree for the exact symbol or
path; don't guess.
Local source (no clone needed): settlement-distributions/ is in the
current repo — Rust structs for all settlement types live there.
Key paths: settlement-distributions/bid-distribution/src/generators/bidding.rs
(ResultSettlementClaims, marinade_stake_share),
settlement-distributions/bid-distribution/src/sam_meta.rs
(auction_effective_static_bid_pmpe, active_delegation_lamports).
External repos (ds-sam, ds-sam-pipeline, etc.): Clone under .refs/ if
not already present — commands are in /marinade-docs. Never refuse to answer
just because a repo isn't pre-cloned. Clone it, then read it.
Note any claim from a private .refs/ repo as upstream-unverifiable.
Reading code to extract a formula: Read the full function body. Identify
the return/output variable. Trace each variable back to its inputs. Write the
formula as a mathematical expression (e.g. fee = value × coef) before
substituting values. Don't skim — calcs are often split across multiple lines.
Write new facts to facts/<slug>.md, one fact per file:
---
topic: <specific topic>
category: <sam-auction|settlement|on-chain|bond-lifecycle|scoring>
verified_at: <ISO date, YYYY-MM-DD>
expired_at: <ISO date — required; default 1 year from verified_at>
sources:
- <file:line or URL — required, ≥1>
summary: >
<one sentence for fast recall>
---
<claim + supporting evidence with direct quotes or line excerpts>
Facts without expired_at are invalid. Facts past their expired_at must be
re-verified or deleted before use. At least one inline citation per non-trivial claim.
Step 3: Verify (subagent per batch of 5)
Each fact must pass all checks before verified_at is set:
- Source accessible — every file:line exists; every URL returns 200
- Claim matches source — open the source, read it; paraphrase drift is the most common failure
- No contradiction — grep
facts/ for conflicting claims; investigate and delete the wrong one
- Numbers recomputed — any quantity, rate, or percentage re-read from source, not copied from a summary
- Upstream claims flagged — logic in
.refs/ repos can change; record the upstream source explicitly
Delete facts that fail any check. An unverified fact is worse than no fact.
Step 4: Answer
Read surviving fact files, answer the original question. Cite inline:
BidTooLowPenalty fires when a validator reduces its bid vs the previous epoch.
---
source: .refs/ds-sam/packages/ds-sam-sdk/src/calculations.ts:248
field: revShare.bidPmpe < tolCoef * (pastAuction?.bidPmpe ?? 0)
Cite file:line or URL. Never "probably" or "likely" — either you read it or you didn't.
