Skip to content

t1k:knowledge-retrieval

FieldValue
Modulet1k-delegation
Version2.12.24
Effortmedium
ToolsAskUserQuestion, 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

/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 indexes summary only, 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.

Nameknowledge-retrieval (HTTP MCP, https://mcp.the1studio.org/mcp)
Toolsdoc_search, doc_get_member, doc_list_assemblies, doc_list_indexed_repos
Authyour own gh auth token; needs active The1Studio org membership
Install~/.claude/skills/t1k-mcp-management/scripts/install-knowledge-retrieval.sh
Declaredmcp.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:

CaseWhy grep fails
Capability not checked out hereYou 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 projectSibling projects are indexed. You cannot grep a repo you do not have.
You do not know what to grep forSemantic 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 ≥ 1 AND the row has status == "ok" AND members > 0 — the project is indexed. Proceed; a miss may be reported as a clean miss.
  • matched: 0, OR a returned row with status != "ok" or members == 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), so matched ≥ 1 alone 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 the unverified-project-not-indexed verdict (§ Reporting a miss); for a failed row, quote its message in 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.

  1. 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.
  2. 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.
  3. Shape the query as an answer, not a question — see references/query-technique.md § Write the answer. The single highest-leverage step, and free.
  4. 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.
  5. 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.
  6. Deepen survivors worth citing: doc_get_member({ id }) for the real signature.
  7. 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.
  8. 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_prefix at FAMILY level is a truncation switch, not a narrowing aid. Only pass an assembly name you have already seen in a result (or a tier: "base" name from doc_list_indexed_repos) — never a package family, never a guess; and a prefix is not a boundary (DOTSCombat.Spawning also matches DOTSCombat.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.

⚠️ Two of the three result criteria were measured non-functional (2026-08-26): summary_quality: "high" discriminates nothing and similarity ≳ 0.65 admits confirmed junk. Only the engine/assembly check works — ask whether the returned summary describes 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:

TagMeaning
● inheritedThe member does the whole job — reuse as-is, bill nothing.
◐ framework-assistedA base exists; you build on it.
○ customNothing 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.

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-grep
scope: <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-indexed
scope: 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-indexed
scope: 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, never greenfield; 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.

Seven measured query-shaping rules (mechanic noun, mechanism word, no pasted player sentences): references/query-technique.md § 9.

  • 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, the assembly_prefix carve-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, the resolve-stdlib-package.cjs library-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).