knowledge-sweep-cocos

Cocos Prior-Art — Sweep the Corpus First, Then Grep to Ground It

Auto-loaded, project-gated. Inert outside Cocos projects — a Unity, designer, or kit-maintenance session never pays for this rule.

Gate

node ".claude/skills/t1k-cocos-base-knowledge-sweep/scripts/detect-cocos-project.cjs"
# exit 0 = Cocos project found (facts on stdout) · exit 1 = rule does not apply

Markers: a directory holding assets/ and either package.json with .creator.version (3.x) or project.json with engine: "cocos-creator-js" (2.4.x), searched to depth 2 — the Cocos project is routinely a subdirectory of the repo root.

Rule — prior art has two sources, in this order

Before /t1k:brainstorm proposes an approach, /t1k:plan writes a phase that builds something, or an architecture audit records a finding:

Step 1 — sweep the corpus. Always first.

Invoke t1k-cocos-base-knowledge-sweep. This is the default entry point for “does this already exist?”, because it is the only step that can reach what is not on your disk: another playable’s source, a package this project never installed, and a need you cannot yet name a symbol for. Grep cannot answer any of those, and its failure to answer them is silent — it returns clean and you conclude greenfield.

The corpus earns first position in exactly the cases grep structurally cannot serve:

Case	Why grep fails
Capability not installed here	You cannot grep a file that is not on disk. Check the premise before leaning on it — package count is not capability count: `@playablelabs/game-foundation` alone ships 17 of the 18 indexed subsystems, so a project holding only 3 packages can still hold nearly the whole foundation (measured, CharmDecorPLA 2026-08-13). List `assets/packages/@playablelabs/*/` before calling any capability absent.
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 (a hybrid lexical+vector ranking, not dense-embedding alone).

Skip Step 1 only when you can already name the exact symbol you are looking for. Asking the corpus to re-summarize a file you have open is waste; for a symbol you can name, grep returns more than the corpus does.

That exception is narrower than it sounds. A need phrased as behaviour — “cancel a looping hint safely”, “restore rest state on teardown” — names no symbol, so it has no grep target and stays a corpus question even when the answer is already sitting on disk. Measured 2026-08-13: a plan skipped the sweep having grepped tutorials/ clean, and the sweep then found TutorialPresets.dragHint in the already-installed sibling package @playablelabs/motion — deleting more machinery from the phase than the whole grep pass had justified adding. The negative it recorded was scoped to tutorials/*.ts but was written as though it settled the question.

Step 2 — grep to ground the hit. Never skipped.

assets/packages/@playablelabs/, assets/scripts/, and any embedded framework folders. The sweep tells you a capability exists somewhere in the studio; grep is what turns that into something you can act on — the real file path, the current on-disk version, the actual implementation, and a reference count the corpus does not carry. An installed-but-unreferenced package is a first-class finding: the capability is already paid for and simply unwired.

Grep is not optional and not a formality. It is the step that converts a corpus hit into a path, and it is frequently where the decisive local precedent surfaces once the sweep has supplied the vocabulary (measured 2026-08-13 — EndCardView._pulseHandle, which established that the handle idiom was already house style, was reachable by grep but only findable after the sweep named it). Treat the two steps as a loop you may re-enter, not a gate you pass once.

Two obligations whenever the sweep runs

Scope every query to the Cocos assembly set. A broad query runs at limit: 25, then filters on assembly — 25 because the .NET slice otherwise crowds every Cocos hit out of the window, and every query must mix in one all-lowercase word (an all-caps query returns confident junk). A follow-up pinned with assembly_prefix is already inside one Cocos assembly, so it has no noise to survive and any limit is fine; broad-then-prefixed-drill-down is the good pattern, not a violation. assembly_prefix is exact-segment: on flat Cocos names a shorter prefix than the full name ("Cocos" vs "CocosBlastPartyPLA") returns no_match that is indistinguishable from genuine absence — never report a prefixed no_match as absence; re-run unprefixed. Never cite a TheOne.*, UITemplate.*, GameFoundation.*, or PuzzleGame.* member as prior art for a Cocos project — C#/Unity APIs a playable cannot import. Reject GameFoundation.* by name, never by similarity score: it outranks real Cocos hits despite being unusable.

Scope by the generated allowlist, never by a remembered count. As of 2026-08-28 the corpus holds 709 assemblies / 31,408 members, of which 28 are Cocos-side (10 indexed Cocos*PLA projects + 18 foundation subsystems) — and those 10 projects carry 11,882 members, 37.8% of the entire corpus. Cocos is a minority of assemblies and a plurality of members, because the Cocos projects are the largest assemblies indexed: 7 of the top 10 by member count are Cocos, and CocosBlastPartyPLA (2,474) is bigger than any Unity assembly. Filtering to reduce Unity noise is right; treating Cocos as a rounding error is not. The allowlist is generated by scripts/refresh-assemblies.cjs, never hand-edited — a stale one silently discards real answers (on 2026-08-28 it knew 3 of 10 projects and was dropping 9,464 Cocos members).
Distinguish importable from referenceable. A hit in a foundation subsystem (inputService, score, objectPool, …) ships in a @playablelabs/* package → installable. A hit in a project assembly (Cocos*PLA, CocosPlayableAdsTemplate) is another playable’s source → nothing to install; reuse means porting the pattern. Never budget an install for a port.

Record which source answered — this is the audit trail

Every prior-art claim carries its provenance: installed (grep hit, with path), corpus (sweep hit, with assembly + kind), or none. A negative must carry its scope — no hit across 28 Cocos assemblies, never a bare “greenfield” / “does not exist” (negative-result-scope.md). If the MCP was unavailable, write discovery: fallback; a tool outage is not an empty corpus.

Why

A false “greenfield” is the highest-cost planning error: it invents whole phases, every downstream estimate inherits it, and the build never re-tests it. Two failure modes produce one:

Not sweeping — the capability exists in a sibling playable or an uninstalled package, and grep returned clean because it can only see this disk.
Not grepping — the package is installed and unreferenced, so the plan rebuilds what shipped.
Sweeping unscoped — the Unity slice outranks the Cocos answers. On "object pool spawn recycle prefab" all six top hits were TheOne.Pooling C# members; the real objectPool hits landed at #7–#8. Unscoped search does not dilute the answer, it replaces it with a wrong one.

When NOT to apply

detect-cocos-project.cjs exits 1.
You can already name the exact symbol you are looking for — grep it and stop. “An installed package answered it” is not that test; see Step 1 above.
The question is package names or versions → that is CPM (https://cpm.playablelabs.ai/); doc_search carries no package metadata.
Unity/.NET work that merely shares the monorepo.

skills/t1k-cocos-base-knowledge-sweep/ — the Step 1 procedure; its references/doc-search-contract.md is the Cocos scoping profile (allowlist, ranking proof, GameFoundation.* trap). Corpus reality, tool limits, query technique and the MCP-absence protocol are the general SSOT in core’s t1k-knowledge-retrieval. Do not restate either here.
negative-result-scope.md · code-quality-cocos.md (sibling auto-loaded Cocos rule) · development-principles.md § “Errors Over Silent Fallbacks”.