t1k:knowledge-retrieval
| Field | Value |
|---|---|
| Module | t1k-delegation |
| Version | 2.12.24 |
| Effort | medium |
| Tools | AskUserQuestion, Bash, Glob, Grep, Read |
Keywords: assembly lookup, corpus search, doc_get_member, doc_list_indexed_repos, doc_search, does this exist, have we built this, knowledge-retrieval, prior art, rag query, reuse check, semantic search, studio docs
How to invoke
Section titled “How to invoke”/t1k:knowledge-retrieval<capability or need> [--engine unity|cocos] [--json <out>]Studio Knowledge Retrieval — Prior-Art Lookup That Actually Returns the Answer
Section titled “Studio Knowledge Retrieval — Prior-Art Lookup That Actually Returns the Answer”Retired 2026-08-26 — you may now query a bare symbol name. The old “every query needs one all-lowercase word” rule worked around a deployment defect (AIPGDS#9/#16) that AIPGDS#18 hit + the corpus rebuild fixed (
IObjectPoolManager→TheOne.Pooling.ObjectPoolManager, 0.7302). A residue remains — “fixed” is premature. The lexical arm indexessummaryonly, so of 40 indexed types 8 could not be found by typing their own name. Measurements + the conjunctive-arm note (AIPGDS#10) that keeps the 2–3-content-word guidance standing:references/query-technique.md§0.
Ask the studio corpus “do we already have this?” against one MCP that indexes both engine worlds — and get an answer scoped to the engine you are actually working in.
The whole problem in one line: the corpus is overwhelmingly Unity/.NET, so the same unscoped query is correct for a Unity question and confidently wrong for a Cocos one — scope decides whether the answer is usable at all.
Query mechanics and corpus facts are the SSOT in
references/doc-search-contract.md; how to shape a query —
the part that most changes result quality — is
references/query-technique.md. Cite them; do not restate them.
The server
Section titled “The server”| Name | knowledge-retrieval (HTTP MCP, https://mcp.the1studio.org/mcp) |
| Tools | doc_search, doc_get_member, doc_list_assemblies, doc_list_indexed_repos |
| Auth | your own gh auth token; needs active The1Studio org membership |
| Install | ~/.claude/skills/t1k-mcp-management/scripts/install-knowledge-retrieval.sh |
| Declared | mcp.required[] with autoInstall: true in both t1k-config-unity.json and t1k-config-cocos.json |
Registration, credentials, and auto-install policy belong to t1k-mcp-management; this skill owns
only what to do once the tools are loaded.
When to invoke — the second half of prior art, not the first
Section titled “When to invoke — the second half of prior art, not the first”Sweep the corpus FIRST — grep only confirms what you already know to ask for (corpus-first,
grep-second: theonekit-unity#533). The corpus answers a capability not checked out here, a sibling
project’s source, or a need phrased as behaviour; local grep is what turns a corpus hit into an
actionable path (real path, on-disk version, implementation, reference count). A clean grep is not a
miss. The skip is licensed by a nameable symbol, never by “it was installed” — a need phrased as
behaviour (“cancel a looping hint safely”) names no symbol, has no grep target, and stays a corpus
question even when the answer is already installed locally (the Cocos drift log carries the
worked case where that reasoning lost a hit).
Invoke for the three things grep structurally cannot answer:
| Case | Why grep fails |
|---|---|
| Capability not checked out here | You cannot grep a file that is not on disk. Confirm that is really the situation first — package count is not capability count. |
| Design precedent from another project | Sibling projects are indexed. You cannot grep a repo you do not have. |
| You do not know what to grep for | Semantic search answers “does anything solve X?” when you cannot name the symbol. |
Not for: package names and versions (Cocos → CPM, https://cpm.playablelabs.ai/); needs a
grep you could actually phrase already answers; a question about a third engine — the corpus indexes
Unity/.NET and Cocos only, and a React-Native or web question returns confident nonsense from both.
A third-engine need reports the reuse-search: engine-not-indexed verdict (§ Reporting a miss)
instead of a corpus sweep.
Step 0 — is this project even in the corpus?
Section titled “Step 0 — is this project even in the corpus?”Before the first doc_search, resolve the current repo (git remote get-url origin → owner/name)
and call doc_list_indexed_repos({ query: "<name>" }).
matched ≥ 1AND the row hasstatus == "ok"ANDmembers > 0— the project is indexed. Proceed; a miss may be reported as a clean miss.matched: 0, OR a returned row withstatus != "ok"ormembers == 0— the project is not in the corpus. A failed index still returns a row (status:"error",members:0,last_indexed_at:null; seen 2026-10-23 for PirateEndlessPuncher, DOTSTemplate, NekoSimulation), somatched ≥ 1alone proves nothing. The sweep still runs (the corpus covers other repos and may hold real prior art), but its negative can no longer be reported as a clean miss. Carry the coverage fact into the scope line and use theunverified-project-not-indexedverdict (§ Reporting a miss); for a failed row, quote itsmessagein the report as the reason.- Tool absent / unreachable — the existing
corpus-unavailable:/grep-only-corpus-unreachable:protocol, plus the studio-knowledge-only tier (corpus-fallback: studio-knowledge only):references/doc-search-contract.md.
The query accepts a URL, .git remote or SCP form (pass git remote get-url origin through as-is). Not-indexed and no-hit mean opposite things; only Step 0 tells them apart: references/doc-search-contract.md.
Workflow
Section titled “Workflow”- Establish the engine. Unity, Cocos, or neither. This picks the scoping profile in § Scoping and it is not optional — the same query needs opposite handling.
- Name the needs as capabilities, not class names.
"combo multiplier score streak", not"ComboMeterController"— the index is semantic, and a local symbol name is the one string guaranteed not to appear in another project. - Shape the query as an answer, not a question — see
references/query-technique.md§ Write the answer. The single highest-leverage step, and free. - Retrieve with the engine’s budget (§ Scoping). One call per need — and run the library-first pass (§ Library-first pass) first, so the installable answer is inside the candidate window instead of below a page of game-repo copies.
- Filter, then apply the positive test before citing anything. A name predicate is not proof; confirm the hit’s language and types match the engine you are in.
- Deepen survivors worth citing:
doc_get_member({ id })for the real signature. - Tag and emit the prior-art table. Every
○is new work someone will be asked to pay for — be sure the miss is real, and not a filter artefact or an absent MCP. - Promote genuinely new, charter-generic work upstream. A corpus-miss on code carrying no
project-specific token is a contribute-back case, not just a
○in the table — see § Contribute back. The other half of the same sweep, not a separate task.
Scoping — the same corpus, two opposite problems
Section titled “Scoping — the same corpus, two opposite problems”Do not quote a corpus count from memory or from this prose. Resolve the live split with
doc_list_indexed_repos (Step 0) or the pointer in
references/doc-search-contract.md — never a pinned count.
What stays true regardless: Unity/.NET is the large majority, Cocos a small minority split between a
fixed foundation set and a growing list of projects. Your engine decides which failure mode you fight.
Unity: too many valid hits (default limit 10, disambiguate with assembly_prefix, risk = deprecated/internal overload). Cocos: right answers outranked (default limit 25, mandatory, filter-after-search against the committed allowlist, risk = filtering to an empty result). Table: references/scoping-table.md.
The rule underneath both columns: retrieve budget scales inversely with filter selectivity; derivation and ceiling rule: references/query-technique.md § Over-retrieve.
When limit: 25 is not enough, switch mechanisms (pre-filtering assembly_prefix drill-down): references/scoping-table.md.
⛔
assembly_prefixat FAMILY level is a truncation switch, not a narrowing aid. Only pass an assembly name you have already seen in a result (or atier: "base"name fromdoc_list_indexed_repos) — never a package family, never a guess; and a prefix is not a boundary (DOTSCombat.Spawningalso matchesDOTSCombat.Spawning.Authoring). Measurements:references/assembly-prefix-hazard.md.
Cocos callers: use the t1k-cocos-base-knowledge-sweep skill directly (allowlist, ranking proof): references/scoping-table.md.
Library-first pass — ask the canonical library before the broad call
Section titled “Library-first pass — ask the canonical library before the broad call”Ask the canonical library first (tier: "base" discovery, a prefixed doc_search per library assembly, library hits ranked first). A library-first miss licenses no greenfield verdict. Procedure: references/library-first.md.
Reading a result
Section titled “Reading a result”⚠️ Two of the three result criteria were measured non-functional (2026-08-26):
summary_quality: "high"discriminates nothing andsimilarity ≳ 0.65admits confirmed junk. Only the engine/assembly check works — ask whether the returnedsummarydescribes the capability, in an assembly that belongs to your engine. Measurements:references/criteria-measured.md.
Treat a hit as real prior art only when the assembly belongs to your engine and the summary actually answers your question (the two struck criteria above are unreliable). Then tag it:
| Tag | Meaning |
|---|---|
| ● inherited | The member does the whole job — reuse as-is, bill nothing. |
| ◐ framework-assisted | A base exists; you build on it. |
| ○ custom | Nothing upstream — genuinely new work. |
Record the verdict as reuse-search: found <Type>@<path> — byte-exact, its own line, nothing
appended to it (§ Reporting a miss covers the miss form and why the line must stay pristine).
Sizing effort from these tags — hours and points, not just a symbol — is § Sizing the delta.
Record the hit’s kind with the tag (foundation/package tier: "base" vs. project source): references/reading-a-result.md.
similarity is a ranking signal, not a correctness one. It orders candidates within one query;
it does not transfer across queries, and it cannot tell a right-language hit from a wrong-language
one. Filter by assembly and by the positive test — never by score alone.
When the MCP is absent — reconnect first, degrade second, never fake
Section titled “When the MCP is absent — reconnect first, degrade second, never fake”Reconnect (claude mcp list, then the kit installer in the background — step-by-step and the
restart requirement: references/doc-search-contract.md
§ “When the MCP is absent”). Only then degrade, and say so in the output
(discovery: fallback). Never report “nothing found” because the MCP was down — a miss caused
by an absent tool is not evidence of absence, and reporting it as one turns every subsystem into
false greenfield.
Reporting a miss
Section titled “Reporting a miss”A miss is a claim about your search, not about the studio. Every reported miss carries two lines — the verdict, then the scope on a separate adjacent line, never merged into it:
reuse-search: not-found-after-corpus-and-grepscope: <what was actually searched> | swept: <date>reuse-search: is the canonical cross-kit verdict token — shipped first from theonekit-unity
(PR #496), reviewer-gated (t1k-unity-dots-core-reviewer checklist item 14 treats a missing line as
CRITICAL). Keep that line byte-exact and pristine; the scope: line beneath it is what satisfies
rules/negative-result-scope.md — reuse-search: alone records the verdict, not what was swept, so
the scope line is not optional and must never be appended to the gated line above it.
When Step 0 found the project not indexed (matched: 0, status != "ok" or members == 0), emitting not-found-after-corpus-and-grep is forbidden, not
discouraged. The third verdict replaces it:
reuse-search: unverified-project-not-indexedscope: corpus covers <N> repos; <owner/name> is not among them; <local paths> | swept: <YYYY-MM-DD>The corpus covers a fixed list of repos; doc_list_indexed_repos({ query: "<name>" }) names which
ones. <N> is whatever the tool returned for total, never a pinned number from this prose. Carry
the project’s absence from the corpus into the scope: line, and with it the local paths the grep
arm actually swept — the verdict records where an answer could have come from, the scope records
what you checked, and both claims must be present.
What this verdict does NOT do: it does not block the work (a NEW Reuse Ledger row carrying it is valid, the local grep arm carries it); it only withdraws the clean-miss token and any greenfield / “no prior art in the studio” phrasing. greenfield is an unverifiable assertion; see rules/negative-result-scope.md. Detail: references/unverified-verdict.md.
Third engine (Godot, web, React-Native, …). The corpus indexes Unity/.NET and Cocos only, so a
third-engine need returns Unity/Cocos near-misses that are indistinguishable from absence. Do not
sweep for one and do not emit not-found-after-corpus-and-grep; the verdict is:
reuse-search: engine-not-indexedscope: corpus indexes Unity/.NET and Cocos only; <engine> is outside it; <local paths grepped> | swept: <YYYY-MM-DD>The scope: line still names what you checked locally — the corpus can say nothing about a third
engine either way, so the verdict records that limit, not a studio-wide negative.
⛔ A corpus miss is NOT evidence of absence — measured false-absence 20–60% on capabilities known to ship; a false negative and a true negative are indistinguishable (every call returns a full page). A miss downgrades a claim to
unverified, nevergreenfield; for a Unity member, grep the source (and check its declaration line for a trailing//comment). Measurements and causes:references/miss-evidence.md.
Contribute back — the other half of the sweep
Section titled “Contribute back — the other half of the sweep”The corpus sweep says what is upstream; contribution is the other direction. Generic-by-charter code is contributed the moment it is written (five-part pass-test, then /t1k:sync-back or an upstream PR). Gate, procedure and the hit/miss rule: references/contribute-back.md.
Sizing the delta — the flow, not a general estimator
Section titled “Sizing the delta — the flow, not a general estimator”Sizes only the delta a sweep reveals; the Base/Worst-case flow and Cocos multipliers: references/sizing-the-delta.md.
Query recipe — measured, not guessed
Section titled “Query recipe — measured, not guessed”Seven measured query-shaping rules (mechanic noun, mechanism word, no pasted player sentences): references/query-technique.md § 9.
References
Section titled “References”references/doc-search-contract.md— SSOT: corpus composition, tool signatures and limits, result shape, MCP-absence protocol.references/query-technique.md— SSOT: how to shape a query (HyDE, multi-query + RRF, step-back, decomposition) and how much to over-retrieve, with the retrieval literature each rule comes from.references/library-first.md— the library-first pass in full:tier: "base"discovery, the ranking rule, theassembly_prefixcarve-out’s derivation, and the package-resolution boundary every engine kit owns for itself.references/sizing-the-delta.md— full Base/Worst-case flow, Cocos’s production multipliers, units.t1k-cocos-base-knowledge-sweep— the Cocos consumer; adds the generated 21-assembly allowlist, a project detector, theresolve-stdlib-package.cjslibrary-hit resolver, and the prior-art table its four consumers read.t1k-mcp-management— registration, credentials, auto-install policy for this server.references/see-also.md— rules and docs this skill cites (negative-result scope, library-quality mandate, pinned-baseline companion).