t1k:cocos:base:knowledge-sweep

Field	Value
Module	`base`
Version	`3.3.2`
Effort	`low`
Tools	—

Keywords: already-exists, cocos-scoped, doc-search, greenfield, knowledge-retrieval, knowledge-sweep, prior-art

How to invoke

/t1k:cocos:base:knowledge-sweep
<capability or need> [--project <root>] [--json <out>]

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: on a Cocos question the corpus’s Unity/.NET members rank above the real Cocos hits. Unscoped, doc_search returns confidently-wrong C# APIs a playable can never import. Measured 2026-08-28: 709 assemblies / 31,408 members, of which the Cocos side is 28 assemblies (3.9%) but 12,737 members (40.6%) — a small minority of assemblies and a large minority of the index, because the Cocos projects are the biggest assemblies in the corpus. Scope to cut the Unity ranking noise; do not treat Cocos as a rounding error, and never filter by a remembered count — the allowlist is generated. Corpus facts, tool limits and query technique are the SSOT in core (t1k-knowledge-retrieval); the Cocos scoping profile, allowlist and ranking proof are in references/doc-search-contract.md — read both, do not re-derive them.

When to invoke — first, by default

Run this skill BEFORE grepping. It is the only prior-art step that can see past your own disk, and its blind spot is the one that costs the most: grep returns clean for a capability that exists in a sibling playable or an uninstalled package, and clean reads exactly like absent. A false greenfield invents whole phases and nothing downstream re-tests it.

Grep is step 2 and is never skipped — it grounds a corpus hit in a real path, on-disk version, implementation, and reference count the corpus does not carry. Verified 2026-08-12: a /t1k:plan run found ScoreTracker already installed and unwired at 0 references, which no corpus hit would have told it. Sweep to find out what exists; grep to find out what you have.

The one licensed skip is a nameable symbol. If you can already name the exact symbol, grep it and stop — asking the corpus to re-summarize a file you have open returns less than grep did. That exception is narrow: 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. “It was installed” never licenses the skip; references/doc-search-contract.md § Drift history carries the worked case.

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?

node scripts/detect-cocos-project.cjs [root]      # exit 0 = Cocos found, 1 = none

Emits facts, never blocks:

{ "cocos": true, "playable": true, "searchedFrom": "…", "roots": [
  { "path": "CocosCharmDecorPLA", "engine": "3.x", "version": "3.8.7",
    "playable": true, "playableSignals": ["package.json:playableSync", "assets/ParameterToolBuild"],
    "cpmPackages": ["@playablelabs/game-foundation", "@playablelabs/parameter-tool", "@playablelabs/motion"] } ] }

cocos: false → this skill does not apply; say so and stop. Detection markers and the depth-2 monorepo search are documented in the script header — a Cocos project is routinely a subdirectory of the repo root, so a cwd-only check misses it.

Workflow

Gate. Run the detector. Not a Cocos project → stop. playable: false → sweep still valid, but do not assume playable-only subsystems (parameter-tool, SDK, end-cards) are relevant.
Name the needs. Decompose the task into capability phrases, not local class names — the index is hybrid lexical+vector, not name-matched. "combo multiplier score streak", not "ComboMeterController".
Query, one call per need. doc_search({ query, limit: 25 }). limit: 25 is mandatory on broad queries — at 10 the .NET slice crowds every Cocos hit out of the window (25 is the tool’s Zod schema cap, not an engine limit). Once a hit identifies the owning assembly, a drill-down call with assembly_prefix set is the right next move and is exempt from the limit: pinned to one Cocos assembly, it has no noise to outrank it. Broad-at-25 → prefixed drill-down is the intended shape. The prefix is exact-segment — assembly_prefix: "Cocos" matches NOTHING; use the exact full assembly name (contract § How to scope 2).
Filter hits to assembly ∈ assets/cocos-assemblies.json. Then apply the signature positive test before citing anything (contract § How to scope).
Deepen the survivors worth citing: doc_get_member({ id }) for the real signature. Read the member block only — the siblings array is 30 alphabetically-ordered members of the whole assembly, not of the hit’s class, so on a project assembly it is noise. To see a class’s real surface, run a second doc_search with assembly_prefix set to that assembly instead.
Tag and emit the prior-art table. Every ○ is new work someone will be asked to pay for — be sure the miss is real, not a filter artefact or an absent MCP.

Output — the prior-art table

The one artefact every consumer reads. Keep this shape.

| Need | Found | Assembly | Kind | Tag | Consequence |
|---|---|---|---|---|---|
| Combo/streak scoring | `ScoreTracker.addCombo()` | `score` | foundation | ● | Import from the owning package |
| Slot occupancy model | `FixedSlotState.typeIndex` | `CocosTripleMatchCityPLA` | project | ◐ | **Pattern only** — copy or extract; no package ships it |
| Rhythm-lane hit window | — | — | — | ○ | New work — no hit across 21 Cocos assemblies |

discovery: mcp | scope: 21 Cocos assemblies of 613 | swept: 2026-08-12

The Kind column is load-bearing — never drop it. The allowlist holds two very different things, and conflating them produces a plan that budgets an npm install for work that is really a port:

Kind	Assemblies	What a hit actually means
foundation	the 18 bare-name subsystems (`inputService`, `score`, `objectPool`, `signalBus`, …)	Ships inside a `@playablelabs/*` package → genuinely importable. Resolve the package via CPM / the folder map.
project	`CocosPlayableAdsTemplate`, `CocosBeatCatsPLA`, `CocosTripleMatchCityPLA`	Another playable’s own source. Nothing to install. Reuse means copying the pattern or extracting it into a package first — real work, and a CONTRIBUTE candidate.

A project hit is still valuable — often more valuable, because it shows how the problem was actually solved in shipped code — but it is evidence about design, not about available packages.

The trailing discovery: / scope: line is not decoration — it is what stops a miss from hardening into “greenfield” three documents downstream. Never omit it.

Gotchas

limit: 25 or the sweep is worthless. Verified: at limit: 10 on an object-pool query, 8 of 10 hits were TheOne.* and the two real objectPool hits landed at #7 and #8. Drop the limit and you filter your way to an empty result on a capability the studio demonstrably has.
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; rules/negative-result-scope.md treats a bare “does not exist” as the single highest-cost planning error, because every downstream estimate inherits it unverified.
Never call doc_list_assemblies in a workflow — ~110K chars, it will blow the context. It is a maintenance call for refresh-assemblies.cjs only.
Do not hand-edit the allowlist. It went stale once already (contract § Drift history). 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. Sibling Cocos*PLA projects also crowd the top window with byte-identical summaries — up to ~44% of a Cocos page can be one repeated fact (measured 2026-08-25). Check duplicates before calling the corpus thin. CocosTripleMatchCityPLA and CocosBeatCatsPLA are other playables’ source, indexed for reference. Tagging one ● tells the reader to import something that does not exist as a package. Verified 2026-08-12: a drag/snap sweep returned the whole FixedSlot model/view/port design from TripleMatchCity — excellent prior art, zero of it installable.
doc_get_member’s siblings are assembly-wide, not class members. On a project assembly you get 30 alphabetically-adjacent fields from unrelated classes. Use assembly_prefix on a second doc_search when you need a class’s real surface.
MCP absent ≠ nothing found. Reconnect, then degrade and label it. Reporting a tool outage as an empty corpus marks every subsystem as new work.

Maintenance

# 1. assistant calls mcp__knowledge-retrieval__doc_list_assemblies, saves the raw result
# 2. re-derive (no --write = drift check, exits 1 on drift; suitable as a gate)
node scripts/refresh-assemblies.cjs <dump.json>
node scripts/refresh-assemblies.cjs <dump.json> --write

References

references/doc-search-contract.md — Cocos profile: allowlist, the ranking proof, the GameFoundation.* trap, drift history.
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 (28 of 709, regenerated 2026-08-28). Never hand-edit: run scripts/refresh-assemblies.cjs <dump> --write.
rules/knowledge-sweep-cocos.md — the auto-loaded rule that binds /t1k:brainstorm and /t1k:plan to this sweep in Cocos projects.
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 evidence exposesSeamFor.