Skip to content

t1k:cocos:playable:primitive-decompose

FieldValue
Moduleplayable
Version4.33.13
Effortmedium
Tools—

Keywords: baseline, decomposition, method-length, primitive-decompose, pure-core-extraction, single-responsibility, srp

/t1k:cocos:playable:primitive-decompose
[--sweep] | --fix <file.ts> --symbol <Name> [--name <coreName>] | --reuse sweep <rootDir> | --reuse drain | --reuse probe --hits <file>

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).

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”
SkillTests
t1k-cocos-base-stdlib-contributeIs this capability worth packaging at all — scope gate, corpus sweep, then decouple/package/PR
This skillShort, 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”.

--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.

Terminal window
cd CocosBlastPartyPLA
bun ../.claude/skills/t1k-cocos-playable-primitive-decompose/scripts/primitive-baseline.cjs sweep assets/scripts

Render 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.

Terminal window
bun scripts/apply-extraction.cjs <file.ts> --symbol <Name> [--name <coreMethodName>] [--dry-run]
  • Naming is judgment, not the script’s. apply-extraction.cjs proposes the meter’s own <method>Core convention; this skill body renames it to something that reads as domain vocabulary (damageAfterArmor, not applyDamageCore) 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 this all 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’s nonExtractableReason / toCoreMethod / rewriteToStub, scoped down from a whole-class split to one pure-core sub-expression.

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.

Terminal window
bun scripts/reuse-probe.cjs sweep assets/scripts # deterministic-only, no MCP
bun scripts/reuse-probe.cjs drain # what still owes a corpus answer
bun 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.

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 baseline

INFO 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.

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.

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.

Classification and probes are scripts; extraction is judgment. Routing SSOT: theonekit-core/.claude/modules/t1k-orchestration/rules/orchestration-rules.md § “Task-Type → Agent Routing”.

StepAgent
Run classify-method.cjs, primitive-baseline.cjs sweep and reuse-probe.cjs sweep and label each method per the entry rulet1k-list-classifier
apply-extraction.cjst1k-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
  • Run --sweep from CocosBlastPartyPLA/, never the repo root. Both the meter’s ts-morph resolution and the baseline’s docs/primitive-baseline.json write path are cwd-relative.
  • pureCore / externalRefs / touchesEngine never gate. They are informational meter facts, reported as INFO only. Only lineCount and 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 than this refuses rather than guessing at correctness — the meter’s pureCore fact does not carry enough information to reconstruct that call safely.
  • reuse-probe.cjs has no MCP client. --reuse probe classifies hits YOU fetched via doc_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> to probe so the candidate finding itself is excluded rather than read as a REUSE port — see references/reuse-contract.md for the measured case.
  • 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 --reuse arm: 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 outside cc.Component in 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.