t1k:cocos:playable:primitive-decompose
| Field | Value |
|---|---|
| Module | playable |
| Version | 4.33.13 |
| Effort | medium |
| Tools | — |
Keywords: baseline, decomposition, method-length, primitive-decompose, pure-core-extraction, single-responsibility, srp
How to invoke
Section titled “How to invoke”/t1k:cocos:playable:primitive-decompose[--sweep] | --fix <file.ts> --symbol <Name> [--name <coreName>] | --reuse sweep <rootDir> | --reuse drain | --reuse probe --hits <file>primitive-decompose
Section titled “primitive-decompose”Gates every method in assets/scripts on size and single responsibility — nothing else —
against a committed, identity-keyed baseline. This skill decides whether a method’s shape is
acceptable; it does not decide whether a method should be packaged into a @playablelabs package
(that is t1k-cocos-base-stdlib-contribute’s question, and it is a different test — see
“Two meanings of primitive” below).
The entry rule (fixed; do not re-derive)
Section titled “The entry rule (fixed; do not re-derive)”entry <=> lineCount > 60 OR (lineCount > 30 AND named receiver groups >= 5)“Named receiver groups” = distinct this.<field> collaborators the method touches. Full schema,
identity-key discipline, and the both-directions gate: references/baseline-contract.md — read it
before touching docs/primitive-baseline.json or scripts/primitive-baseline.cjs.
Two meanings of “primitive” — do not conflate them
Section titled “Two meanings of “primitive” — do not conflate them”| Skill | Tests |
|---|---|
t1k-cocos-base-stdlib-contribute | Is this capability worth packaging at all — scope gate, corpus sweep, then decouple/package/PR |
| This skill | Short, one reason to change — size + SRP. Purity is explicitly NOT a criterion |
A method can fully satisfy one and completely fail the other. applyDamage(raw, armor, mult) below
is short and single-purpose (passes this gate) while also being state-touching-adjacent through
this.armor — that is fine here, and whether it is worth packaging is a call the contribute skill
makes separately. Full contrast: references/meter-ownership.md § “Two meanings of primitive”.
The three verbs
Section titled “The three verbs”--sweep (default when invoked with no flags)
Section titled “--sweep (default when invoked with no flags)”Rebuild the whole-project baseline. Runs scripts/primitive-baseline.cjs sweep <rootDir> from
the Cocos project root (CocosBlastPartyPLA/) — ts-morph and the baseline’s own docs/ path are
both cwd-relative; running from anywhere else silently produces wrong identity keys, not an error.
cd CocosBlastPartyPLAbun ../.claude/skills/t1k-cocos-playable-primitive-decompose/scripts/primitive-baseline.cjs sweep assets/scriptsRender the result per references/report-format.md — FAIL and INFO lines must never look alike;
the report states inline that INFO never affects the baseline. A drift (diff fired) is reported
verbatim per baseline-contract.md § 7 — never soften or re-pin it.
--fix <file.ts> --symbol <Name> — perform ONE pure-core extraction
Section titled “--fix <file.ts> --symbol <Name> — perform ONE pure-core extraction”Reads the meter’s pureCore fact for the named method and, if the shape is supported, splits the
pure sub-expression into a new sibling method and rewrites the call site to delegate to it — a
refactor, never a behaviour change.
bun scripts/apply-extraction.cjs <file.ts> --symbol <Name> [--name <coreMethodName>] [--dry-run]- Naming is judgment, not the script’s.
apply-extraction.cjsproposes the meter’s own<method>Coreconvention; this skill body renames it to something that reads as domain vocabulary (damageAfterArmor, notapplyDamageCore) before the extraction is considered done. Pass the chosen name via--name. - Refuses rather than guesses. No pure core, an ambiguous candidate match, or a property read
through anything other than
thisall refuse with a stated reason on stderr, exit 1 — never a silent no-op and never a best-effort guess at a receiver the script cannot name. See the script’s own file header for the exact supported shape. - Must leave behaviour identical. The script itself refuses (writes nothing) if the rewritten file introduces new ts-morph diagnostics versus before the edit. Still run the project’s own typecheck pass before calling the extraction done — the script’s check is a fast, local proxy, not a substitute for the real gate.
- Modeled on (ported, not imported — a project-assembly file, not a package)
CocosBlastPartyPLA/extensions/package-manager/source/services/ComponentExtractService.ts’snonExtractableReason/toCoreMethod/rewriteToStub, scoped down from a whole-class split to one pure-core sub-expression.
--reuse — on demand, never per turn
Section titled “--reuse — on demand, never per turn”Before proposing a from-scratch --fix extraction, check whether an equivalent already exists
upstream. On demand only — this never runs from a hook and never runs per turn; per-turn MCP
calls are explicitly out of this skill’s design (theonekit-core/.claude/modules/t1k-engineering/rules/ai-driven-design.md,
rules/knowledge-sweep-cocos.md). Full contract: references/reuse-contract.md.
bun scripts/reuse-probe.cjs sweep assets/scripts # deterministic-only, no MCPbun scripts/reuse-probe.cjs drain # what still owes a corpus answerbun scripts/reuse-probe.cjs probe --hits <hits.json> [--assembly-prefix <name>] \ [--source-project <name>] [--candidate <key>] [--queue <path>]sweep narrows to methods whose externalRefs is empty — the honesty mechanism
(references/reuse-contract.md § “Only externalRefs-empty methods are swept”): this skill’s own
gate tests size+SRP, not purity, so a method can pass it while still failing the library’s
“survives being pasted alone” test outright. Sweeping only the purity-eligible subset is what
makes the reported candidate count mean something.
The knowledge-retrieval MCP call is yours to make, not the script’s. reuse-probe.cjs has no
MCP client — run doc_search yourself per rules/knowledge-sweep-cocos.md’s discovery order
(corpus first at limit: 25, reject TheOne.*/UITemplate.*/GameFoundation.*/PuzzleGame.*
by name regardless of score, treat a prefixed no_match as a signal to retry unprefixed rather
than absence, then local grep to ground a hit), then pass the raw hits to probe --hits. It
classifies deterministically into REUSE (with action: install|port|review) or
KEEP, matching t1k-cocos-playable-modularize-reuse-scan’s vocabulary rather than inventing a
parallel set. If the MCP is unreachable, probe --mcp-unreachable reports discovery: 'fallback'
— never a greenfield finding, per theonekit-core/.claude/modules/t1k-verification/rules/negative-result-scope.md.
Reading a report
Section titled “Reading a report”GameView.ts applyDamage() PASS (4 lines, 1 reason) INFO: pure core extractable -> damageAfterArmor(raw, armor, mult) externalRefs after extract: [] reuse-checkable: yes spawnTile() PASS (9 lines, 1 reason) INFO: no pure core detected legacyReset() FAIL (140 lines, 4 groups) <- only this affects the baselineINFO lines are always informational — they never affect the baseline and never require action.
Full rendering rules, why FAIL and INFO must look visibly different, and the risk they guard
against: references/report-format.md.
Extraction judgment
Section titled “Extraction judgment”What counts as “one reason to change” when a FAIL fires, and how to decide whether to decompose by
extracting a pure core (--fix), splitting by named collaborator group, or leaving a documented
exception: references/decomposition-rubric.md.
Meter ownership
Section titled “Meter ownership”This skill owns scripts/classify-method.cjs — the AST meter measuring lineCount, externalRefs,
pureCore and touchesEngine — together with its suite (tests/classify-method.test.cjs).
primitive-baseline.cjs, apply-extraction.cjs and reuse-probe.cjs require it directly by
relative path. There is no shim between them, because there is no longer a second skill to reach
across to. Contract and move constraints: references/meter-ownership.md.
Executed by
Section titled “Executed by”Classification and probes are scripts; extraction is judgment. Routing SSOT: theonekit-core/.claude/modules/t1k-orchestration/rules/orchestration-rules.md § “Task-Type → Agent Routing”.
| Step | Agent |
|---|---|
Run classify-method.cjs, primitive-baseline.cjs sweep and reuse-probe.cjs sweep and label each method per the entry rule | t1k-list-classifier |
apply-extraction.cjs | t1k-cocos-base-developer — write-capable; t1k-list-classifier has no Edit/Write |
| Extraction judgment (is this a primitive worth packaging) | stays on the reasoning tier |
Hard rules
Section titled “Hard rules”- Run
--sweepfromCocosBlastPartyPLA/, never the repo root. Both the meter’s ts-morph resolution and the baseline’sdocs/primitive-baseline.jsonwrite path are cwd-relative. pureCore/externalRefs/touchesEnginenever gate. They are informational meter facts, reported as INFO only. OnlylineCountand named-receiver-group count decide PASS/FAIL —references/baseline-contract.md§ 5 is a hard boundary, not a style preference.apply-extraction.cjs’s supported shape is deliberately narrow. A property access through any receiver other thanthisrefuses rather than guessing at correctness — the meter’spureCorefact does not carry enough information to reconstruct that call safely.reuse-probe.cjshas no MCP client.--reuse probeclassifies hits YOU fetched viadoc_search; it never calls the corpus itself, and it must never be called from a hook.- A corpus hit in the candidate’s own project assembly is not prior art. Pass
--source-project <name>toprobeso the candidate finding itself is excluded rather than read as a REUSE port — seereferences/reuse-contract.mdfor the measured case.
Related
Section titled “Related”references/baseline-contract.md— the pinned-baseline schema SSOT (Phase 3).references/decomposition-rubric.md— how to judge “one reason to change” and choose a fix.references/report-format.md— the FAIL/INFO rendering contract.references/reuse-contract.md— the--reusearm: honesty mechanism, discovery order, verdict vocabulary, provenance, and queue discipline (Phase 5).t1k-cocos-base-stdlib-contribute— the packaging question (scope gate, corpus sweep, decouple, PR) that is deliberately NOT this skill’s test.references/meter-ownership.md— the meter’s ownership contract and move constraints.t1k-cocos-base-code-conventions§ “Feature modules & testability” — why logic worth decomposing usually belongs outsidecc.Componentin the first place.theonekit-core/.claude/modules/t1k-verification/rules/pinned-baseline-test-companion.md(theonekit-core) — the governing rule this baseline applies; read there for the four pin shapes and the invert-never-re-pin doctrine.