t1k:cocos:base:knowledge-sweep
| Field | Value |
|---|---|
| Module | base |
| Version | 4.51.9 |
| Effort | low |
| Tools | — |
Keywords: already-exists, cocos-scoped, doc-search, greenfield, knowledge-retrieval, knowledge-sweep, prior-art
How to invoke
Section titled “How to invoke”/t1k:cocos:base:knowledge-sweep<capability or need> [--project <root>] [--json <out>]Cocos Knowledge Sweep — Scoped Prior-Art Lookup
Section titled “Cocos Knowledge Sweep — Scoped Prior-Art Lookup”Ask the studio corpus “do we already have this?” — without getting a Unity answer to a Cocos question. One sweep, several consumers.
The whole problem in one line: unscoped, the corpus Unity/.NET members outrank the real Cocos hits, and the cocos-stdlib
packagesassembly is absent from unscoped results at all. Scope every sweep to Cocos, and run its own library pass (Step 3b) on every need. Measured numbers, the Cocos slice and the ranking proof:references/problem-framing.mdandreferences/doc-search-contract.md.
When to invoke — first, by default
Section titled “When to invoke — first, by default”The loop (corpus, then graph, then grep, then one reuse-verdict: line, when the licensed skip applies, what a
negative must state) is engine-neutral and lives in theonekit-gamedev t1k-gamedev-reuse-loop (module
theonekit-gamedev:reuse, a dependency of this module). This skill is its Cocos side: the values the neutral
skill’s Step 0 asks for (x-knowledge in t1k-cocos-base-gamedev-adapter) and everything that is true only
of the Cocos corpus slice. Run it BEFORE grepping; grep is never skipped, it grounds a corpus hit on disk.
This skill is what answers the three things grep structurally cannot:
| Case | Why grep fails |
|---|---|
| Capability not installed here | You cannot grep a file that is not on disk — but confirm that is the situation: package count is not capability count. game-foundation alone ships 17 of the 18 indexed subsystems, so a 3-package project can hold nearly the whole foundation (measured, CharmDecorPLA). List assets/packages/@playablelabs/*/ first. |
| Design precedent from another playable | CocosBeatCatsPLA, CocosTripleMatchCityPLA are indexed. You cannot grep a repo you do not have. |
| You do not know what to grep for | The corpus answers “does anything solve X?” when you cannot name the symbol (hybrid lexical+vector ranking, not semantic-only). |
Then: before declaring anything greenfield (a miss needs a stated scope), during an architecture
audit to evidence exposesSeamFor, and as the shared pass feeding t1k-cocos-playable-modularize’s Phase 0 / Pillar
A / Pillar C.
Not for: package names and versions (that is CPM — https://cpm.playablelabs.ai/); needs already answered by a grep you could actually phrase — a behaviour-shaped need does not qualify, see above; non-Cocos projects (the gate below makes it inert).
Gate — is this even a Cocos project?
Section titled “Gate — is this even a Cocos project?”<skill> = .claude/skills/t1k-cocos-base-knowledge-sweep from the repo root holding .claude/, never a Cocos subfolder; Module not found = unresolved (#1893, #1948).
cwd is a game subfolder (monorepo, no .claude of its own): resolve <skill> from the nearest ancestor .claude/ by absolute path, never a relative path. A Cocos project is routinely a subdirectory of the repo root (references/gate-details.md).
bun .claude/skills/t1k-cocos-base-knowledge-sweep/scripts/detect-cocos-project.cjs [root] # exit 0 = Cocos found, 1 = nonecocos: false → this skill does not apply; say so and stop. The output shape, the depth-2 monorepo search, and the no-project-yet branch (which starting-point template) are in references/gate-details.md.
Workflow
Section titled “Workflow”Eight steps. Every command, the library-pass calls and the graph pass are in references/workflow-steps.md. Do not skip step 3b.
- Gate. Run the detector (§ Gate). Not a Cocos project → stop.
- Name the needs as capability phrases, not local class names.
- Query, one call per need.
doc_search({ query, limit: 25 });limit: 25is mandatory on broad queries. A prefixed drill-down, once a hit names its assembly, is exempt. 3b. Library pass, mandatory on every need.assembly_prefix: "packages"(the only REUSE source) and"catalog"(design pattern, never installable). 3c. Graph grounding (Step 2.5,references/graph-grounding.md): blast radius, extraction candidates, PR impact. Grep still grounds every hit. - Filter hits to the effective allowlist:
bun <skill>/scripts/refresh-assemblies.cjs --effective, then the signature positive test. - Resolve every
packages#…hit before it enters the prior-art table — REUSE or not — withresolve-stdlib-package.cjs(§ Resolving a hit). - Deepen the survivors with
doc_get_member. - Tag and emit the prior-art table (§ Output).
- Decide and act: one
reuse-verdict:line per need, then its Step 4 action (rules/knowledge-sweep-cocos.md; mechanics inreferences/contribute-back.md).
Resolving a hit — resolve-stdlib-package.cjs
Section titled “Resolving a hit — resolve-stdlib-package.cjs”A packages#… hit names no package, so the resolver maps its declaration to @playablelabs/<name> and version. Exit codes (0, 1, 2, 3) and the declaration-anchor rule: references/resolve-hit.md.
bun <skill>/scripts/resolve-stdlib-package.cjs <qualified_name|member id> [--stdlib <dir>] [--json]Exit 1 is the verdict, not a resolver failure: unresolved ⇒ ◐ pattern-only, never ●, never REUSE.
Output — the prior-art table
Section titled “Output — the prior-art table”One table per sweep (columns, Kind values and a full worked example: references/output-table.md), then these lines:
discovery: mcp | scope: <N> Cocos assemblies of <total> | swept: <YYYY-MM-DD>graph: cocos scope · <N> nodes / <M> edges · built <date from graph_stats> | graph: unavailable — mcp__code-graph-cocos__* absent this sessionreuse-verdict: REUSE — @playablelabs/core-tick-schedule — scope: 32 Cocos assembliesreuse-verdict: CONTRIBUTE — FixedSlotState — scope: 32 Cocos assembliesreuse-verdict: NEW — RhythmLaneHitWindow — scope: 32 Cocos assemblies — reason: this game's lane timingRequired fields (NEW: scope: + reason:; KEEP: reason: 20+ chars + index:) are core data
(data/reuse-gate.json); full table: docs/knowledge-sweep-cocos.md.
Executed by
Section titled “Executed by”Project detection, assembly refresh and sweep verification are scripted. Routing SSOT: theonekit-core/.claude/modules/t1k-orchestration/rules/orchestration-rules.md § “Task-Type → Agent Routing”.
| Step | Agent |
|---|---|
Run detect-cocos-project.cjs, refresh-assemblies.cjs and verify-sweep-ran.cjs; report their verdicts | t1k-fact-fetcher |
Run resolve-stdlib-package.cjs on a hit and quote the resolved package | t1k-fact-fetcher |
| Decide REUSE / EXTEND / KEEP-LOCAL from the prior-art table | stays with the orchestrating skill/user — a judgment call |
Hard rules
Section titled “Hard rules”limit: 25or the sweep is worthless. Verified: atlimit: 10on an object-pool query, 8 of 10 hits wereTheOne.*and the two realobjectPoolhits landed seventh and eighth. Drop the limit and you filter your way to an empty result on a capability the studio demonstrably has.- A
packageshit does not name a package.doc_get_memberreturns the assembly only — no name, no version, no path. WritingREUSE — packages/FreeListrecords a verdict nobody can act on. Runresolve-stdlib-package.cjsfirst (Step 5); its whole contract is that it fails loudly (1not found,2ambiguous,3no checkout) rather than guessing. - A
packageshit can be game-repo code with no installability at all. The shared assembly also indexes symbols that resolve against nothing in cocos-stdlib (packages#T:CurrencyHudnames no@playablelabs/*package and resolves only against the game repo). The resolver’s exit1is the only catcher — a doc-table hit looks real, carries no installability signal, and only running Step 5 exposes it — so unresolved ⇒◐pattern-only, never●, never REUSE (#1970). - The library needs its own call, every time. The broad query does not merely rank the library
low — it omits it (measured:
references/doc-search-contract.md§ One exception).verify-sweep-rangates any recordedreuse-verdict:line on at least oneassembly_prefix: "packages"/"catalog"call — a KEEP is gated exactly like a REUSE, because KEEP asserts “nothing installable does this” and only the library can check that (#1965: a foundation-only camera-follow KEEP missed@playablelabs/core-camera-follow’sCameraFollowModel). - Reject
GameFoundation.*by name, never by score. It is the Unity GameFoundation and it scores ~0.73 — above any sane threshold. Score-based filtering lets it straight through. - A miss is not greenfield. The corpus holds 3 Cocos projects. Report misses with the swept
scope;
theonekit-core/.claude/modules/t1k-verification/rules/negative-result-scope.mdtreats a bare “does not exist” as the single highest-cost planning error, because every downstream estimate inherits it unverified. - Never call
doc_list_assembliesin a workflow — ~110K chars, it will blow the context. It is a maintenance call forrefresh-assemblies.cjsonly. - Do not hand-edit the allowlist. It went stale once already (contract § Evidence moved out of the body). If a new Cocos assembly appears, re-dump and regenerate — the drift is the bug, not the missing entry.
- Existence ≠ reuse. A hit says the capability exists upstream, not that upstream is better than
the local copy. Divergence check before any swap —
modularize-reuse-scan§ EXTEND. - A
project-kind hit is not an installable package. SiblingCocos*PLAprojects also crowd the top window with byte-identical summaries — up to ~44% of a Cocos page can be one repeated fact. Check duplicates before calling the corpus thin.CocosTripleMatchCityPLAandCocosBeatCatsPLAare other playables’ source, indexed for reference. Tagging one●tells the reader to import something that does not exist as a package: a drag/snap sweep once returned the wholeFixedSlotmodel/view/port design from TripleMatchCity — excellent prior art, zero of it installable (contract § Cocos-specific hard limits). doc_get_member’ssiblingsare assembly-wide, not class members. On a project assembly you get 30 alphabetically-adjacent fields from unrelated classes. Useassembly_prefixon a seconddoc_searchwhen you need a class’s real surface.- A
reuse-search: not-foundline expires. Give it a datedswept: <YYYY-MM-DD>token; an undated or pre-re-index line is stale: re-run Step 3b and rewrite it (references/verify-sweep-verdicts.md§ Stale not-found lines). - MCP absent ≠ nothing found. Reconnect, then degrade and label it. Reporting a tool outage as an empty corpus marks every subsystem as new work.
Did the sweep actually run? — verify-sweep-ran.cjs
Section titled “Did the sweep actually run? — verify-sweep-ran.cjs”A forensic check over a finished session’s transcript: it answers whether the corpus was really consulted. modularize-reuse-scan § Workflow step 8 requires it. Usage, the ISSUED-vs-ANSWERED rule and the verdicts: references/verify-sweep-verdicts.md.
Recording the sweep for the gate — record-sweep-hits.cjs
Section titled “Recording the sweep for the gate — record-sweep-hits.cjs”After each doc_search, save the raw result and run (inside the Cocos project):
bun <skill>/scripts/record-sweep-hits.cjs --query "<the query>" --results <result.json | -> [--session <id>]Package hits only. The data-file contract, the session default and the warn-and-exit behaviour are in references/recording-hits.md.
Maintenance
Section titled “Maintenance”Allowlist maintenance (refresh-assemblies.cjs: page doc_list_assemblies to exhaustion, drift check
without --write, --effective consume path, ALLOWLIST_SEED floors packages and catalog):
references/maintenance.md.
References
Section titled “References”-
references/doc-search-contract.md— Cocos profile: the measured slice, allowlist, the library-prefix exception (with the ranking proof), theGameFoundation.*trap, the dated evidence moved out of this body, and drift history. -
references/starting-point-templates.md: which repo template starts a new Cocos project,CocosTemplate(new games) vsPlayableAdsTemplate(playable ads), and whyCocosGameTemplateis not a starting point. -
t1k-knowledge-retrieval(core) — general SSOT: corpus composition, tool signatures/limits, result reading, MCP-absence protocol, and query technique (HyDE-style phrasing, multi-query + rank fusion, post-filter oversampling). -
assets/cocos-assemblies.json— generated allowlist. Filter withbun <skill>/scripts/refresh-assemblies.cjs --effective, never by reading this file directly (the seed is not in it) and never by restating a count from memory — this line carried a stale total once, and a remembered count is exactly the kind of fact that drifts silently. Never hand-edit: run<skill>/scripts/refresh-assemblies.cjs <dump> --write. -
scripts/resolve-stdlib-package.cjs— Step 5: apackages#…hit →@playablelabs/<name>+ version + declaring file. -
references/contribute-back.md— Step 4: where each verdict lands (install, cocos-stdlib, PLAGameFoundation fixes). -
references/graph-grounding.md— Step 2.5: the graph pass, the Cocos dead-code prohibition, and thegraph:provenance line. -
t1k-cocos-base-code-graph— the Cocos recipe set for Step 2.5 (blast radius, extraction candidates, PR impact, communities). Usage SSOT is core’st1k-code-graph. -
rules/knowledge-sweep-cocos.md— the kit’s most important rule: the sweep → grep → verdict → contribute-back loop this skill starts. -
t1k-cocos-playable-modularize-reuse-scan— the REUSE/EXTEND/KEEP/CONTRIBUTE consumer; adds CPM as a second source for package names. -
t1k-cocos-base-architecture-patterns— consumes the sweep to evidenceexposesSeamFor. -
references/problem-framing.md,references/gate-details.md,references/workflow-steps.md,references/resolve-hit.md,references/output-table.md,references/recording-hits.md,references/why-this-runs-first.md: sections moved out of this body, verbatim; read on demand.
Why this runs first
Section titled “Why this runs first”A false greenfield is the costliest planning error (t1k-gamedev-reuse-loop § Provenance). Two causes are specific to this corpus: sweeping unscoped (Unity hits outrank Cocos), and sweeping without the library pass (the packages assembly is absent from unscoped results, not outranked). Detail: references/why-this-runs-first.md.