t1k:cocos:playable:preproduction

Auto-generated

🔒 Auto-generated from The1Studio/theonekit-cocos@0.0.0 — edit the source kit, not this page.

Field	Value
Module	playable
Version	2.14.4
Effort	medium
Tools	—

Keywords: breakdown, cost, dev effort, dev-days, effort, estimate, estimation, how long, legacy, modularize, module architecture, module slicing, phase 2.5, preproduction, quote, refactor, refactor mode, scope, system design, target design, target modules, timeline, to-be, work package

How to invoke

/t1k:cocos:playable:preproduction
<spec-file-or-brief> [--3d] | --refactor [--3d]

---

Cocos Playable — Dev-Effort Estimate

Turn a playable-ad spec into a reuse-grounded, risk-weighted, module-first effort estimate: a ready-to-build system design (module tree, communication flow, signal contracts, class reference, level-data schema) with each module estimated directly, plus a two-point Base / Worst-case total — one markdown report. Optimize for a base that matches an experienced estimator’s gut number, and for a design so complete that /t1k:cook can build straight off it with no separate planning pass.

Module-first, not WP-first. The internal effort taxonomy is still the WP catalog (work-packages.md) — but it is a sizing tool, not the output shape. The report is sliced by actual system-design module (the scripts/classes/signals a dev will write, per the system-design-template.md in the project’s docs/), so every estimate line traces to a class. Gameplay code → estimated per module; cross-cutting art/optimization/polish/QA → production packages. Reconcile: the module + production totals must equal the WP totals (same work, re-sliced).

Grill before you cost. This skill runs a mandatory clarification gate (step 2, <HARD-GATE-CLARIFY-FIRST>) that interrogates every material assumption via AskUserQuestion before any estimate is produced — see rules/workflow-gates.md for the universal HARD-GATE contract. Never emit an estimate that rests on unconfirmed assumptions.

Decision Tree

Intent	Path
”Estimate this playable spec” (2D or 3D)	Full workflow below
3D game (models/camera/optimization/env-polish)	Full workflow + work-packages.md §3D block, pass --3d
”Just the reuse discount — what’s already built?”	reuse-sweep.md only
”Why is X not billed?” / defaults question	estimation-rules.md § Default deliverables
”Re-price after a scope change”	Re-clarify any new unknowns (step 2), then re-run steps 4–8 on the changed WPs only
Old code → new gameplay (upgrade, not greenfield)	An as-is doc already describes the project. Ask t1k-cocos-base-system-design to author --state to-be against it, then cost only the new and changed modules — retained ones are built already
Legacy refactor — same gameplay, better modules (t1k-cocos-playable-modularize Phase 2.5)	Refactor mode — see § below. Slice the target from the as-is doc + architecture-audit.json + reuse-scan.json instead of from a spec. Steps 1, 3, 4, 5, 7 are skipped; no estimate unless one was asked for
”Just give me a number, skip the questions”	Only on explicit “proceed on stated defaults” — record each default in the report; otherwise the gate stands

Workflow

0. Pre-flight — Knowledge MCP registration. <HARD-GATE-CORPUS-PREFLIGHT> Before scouting the spec, check whether the Knowledge MCP (mcp__knowledge-retrieval__doc_search) is loaded this session. If it’s already loaded, continue straight to step 1. If not, register it in the background (see reuse-sweep.md § Step 0 pre-flight) and HALT — tell the user a session restart is required now, before the spec scout or the clarification gate spend anything on this run. Only an explicit “proceed on fallback” override continues past the halt (the run then proceeds on the lower-confidence fallback per reuse-sweep.md, and the report must say so). </HARD-GATE-CORPUS-PREFLIGHT>

1. Scout the spec. Read the brief/spec fully. List every feature, screen, transition, interaction, FX, and asset. Note engine (2D/3D), whether models arrive pre-rigged + pre-animated, and whether note/tile/level data is dynamic (runtime colors, JSON-driven). As you scout, keep a running list of every point where the spec is silent, ambiguous, or you’d otherwise fill a gap with a guess — that list feeds step 2.

2. Clarification gate — grill BEFORE costing. <HARD-GATE-CLARIFY-FIRST> Enumerate every material unknown (anything that moves the number) and batch it into AskUserQuestion (max 4 per call) until each is answered and the decoded core mechanic is read back to the user and confirmed (clarification-gate.md § Read-back). Walk the grill checklist in clarification-gate.md: engine 2D/3D · exact gameplay mechanic + full element inventory · reference authority (A exact / B original-GOAT / C mixed) · level-data ingestibility/format · art & model readiness (rigged? animated? final?) · dynamic-color · orientation set · (NOT ad networks / size cap — standing studio default, never asked) · reference-build/asset access · in/out-of-scope boundary. Do NOT run the reuse sweep or emit any estimate until this passes. </HARD-GATE-CLARIFY-FIRST> Override: if the user explicitly says “proceed on stated defaults” (or equivalent), record each still-unanswered item with its documented default (the checklist’s Default column) in the report’s Scoping-assumptions table, then continue — this override does not cover the mechanic read-back, which still requires explicit confirmation. A stated default under explicit override is legitimate; a silent assumption is a gate violation.

3. Reuse sweep (grounds every discount). Search the Knowledge MCP by capability keyword across the whole corpus — not one project — to find reusable framework code (game-flow, signals, params, CTA, audio, end-cards, juice/motion, pooling, timers, screen-adapt). Follow reuse-sweep.md. Fallback: skill catalog + code grep when MCP is unavailable. Tag each need ● inherited · ◐ framework-assisted · ○ custom.

4. Map to work packages (sizing pass). Slot every feature into WP0–WP9 (work-packages.md) to size the effort. Exclude studio default deliverables (do NOT bill): parameter dashboard, draw-call/batching, size-budget compliance, low-end perf profiling. Bill a param ONLY if it needs logic beyond gameplay or is a level-editor tool (e.g., JSON level generator). This pass produces the numbers; step 6 re-slices them into modules.

5. Apply the estimation rules (estimation-rules.md) — the studio heuristics: pre-rigged import rate (§4 3D asset rules); lighting default-first, look-dev → env polish scaled per distinct model (§5 environment & shading polish); dynamic-color surcharge; animated/skinned meshes cost more to optimize; VFX particle assets priced per effect (§ 6); pure gameplay carries no juice (juice authored once in the polish package); no double-counting.

6. Ask the service for the design, then estimate each module directly. <HARD-GATE-DESIGN-EMBEDDED> Invoke t1k-cocos-base-system-design to author the doc --state to-be, passing the spec, the decoded level-data samples, and the step-3 reuse sweep. That skill owns the design artifact — its template resolution, its section list, and its schema — so this skill does not restate any of it. Root the module tree at assets/scripts/[Name-Project]/ ([Name-Project] = placeholder, rename before build). Then re-slice the step-4 WP hours into (a) gameplay code modules (each row = a module + its classes, estimated directly) and (b) production packages (art / optimization / VFX / polish / QA / buffer — cross-cutting, not single classes). Do NOT emit an estimate whose lines are generic WPs instead of named modules. </HARD-GATE-DESIGN-EMBEDDED>

7. Set Base per module/package, then risk-weight the worst-case. Base = O = L — the lean, realistic plan number (no rosy floor below it). Worst-case P = Base + risk premium, applied ONLY to high-uncertainty items (bespoke gameplay module, camera framing, skinned-mesh optimization, feedback-juice authoring, dynamic-color polish), at the per-tag multipliers in estimation-rules.md § 1. Inherited/mechanical items: P ≈ Base (near-flat). Add the iteration buffer (§ 1a) as its own package.

8. Assemble + gut-check. Emit the report per report-template.md: project understanding + gameplay, scoping table, reuse-basis table, module architecture + communication flow + signal contracts + class summary + level-data schema + class reference (the embedded design), then the per-module + production-package estimate tables — state the object count behind every per-object-scaled row (WP8.2 env/shading, WP9 VFX) — the §9b client summary table (always), Base/Worst totals (8h=dev-day, 5d=week), headline, risk hotspots. Reconcile — two checks, not one: (a) module + production totals MUST equal the step-4 WP totals — if they don’t, a slice is missing or double-counted; (b) every row’s Scope billed hours must be consistent with its reuse tag (● near-zero unless justified, ◐ names the uncovered delta) — see report-template.md § 9 reuse-tag reconcile. Gut-check: the base should land near an experienced estimator’s number for the genre; if it drifts well above, per-task optimistic values are inflated — the base is the lean figure, risk lives only in the worst-case.

Refactor mode — slicing a target for an existing codebase

Invoked as Phase 2.5 of t1k-cocos-playable-modularize, which is the only place in that pipeline that decides what modules this system should have rather than what is wrong with it. Same step 6 procedure, different input, and most of the costing pass switched off.

What changes:

Step	Greenfield	Refactor mode
1 scout	read the spec	skip — read the as-is doc, reports/architecture-audit.json, reports/reuse-scan.json instead
2 clarify	grill the spec	keep — grill the target: which boundaries are deliberate, what is out of scope for this pass
3 reuse sweep	MCP sweep for prior art	skip — reuse-scan.json already carries per-subsystem verdicts, from two sources
4, 5, 7 WP sizing / rates / risk	the whole costing pass	skip unless a number was asked for — this is a refactor, not a quote
6 module slicing	slice a spec into modules	the deliverable — slice the target modules, invoke system-design --state to-be
8 assemble	estimate report	emit the to-be doc + regenerate docs/design-manifest.json

The three inputs are not interchangeable. The as-is doc says what exists; the architecture audit says which of those boundaries are wrong and which SRP splits expose a package-fillable seam (enablingExtraction + exposesSeamFor); the reuse scan says which modules should not survive at all because a @playablelabs package covers them. Drop any one and the target is wrong in a specific way: without the audit you re-document the god-class as if it were a design; without the reuse scan you carefully design modules a Tier 2 swap is about to delete.

The clarification gate still binds. Module boundaries are exactly the class of decision the gate exists for — a target nobody confirmed is the same guess as an estimate nobody confirmed, and it is more expensive because the whole refactor is planned against it.

Do not carry the WP taxonomy into the output. In refactor mode the report is the design doc, not an estimate; §9/§9b and the Base/Worst tables do not apply unless the caller explicitly wanted the refactor costed too.

Non-negotiables

• Module-first output — the design ships with the estimate. The report embeds a build-ready system design (module tree, communication flow, signals, class reference, level-data schema per system-design-template.md) and estimates each module directly. The goal is that /t1k:cook runs off it with no separate planning pass. An estimate whose line items are generic WPs (WP0/WP4/…) instead of named modules is a regression — WPs are the internal sizing tool, modules are the output.
• Scripts folder = assets/scripts/[Name-Project]/. The gameplay module tree lives under a project-named folder — [Name-Project] is a placeholder to rename before implementing (never ship the literal [Name-Project], and never use the template’s literal gameplay/ as the root). Matches the Cocos code-convention assets/scripts/{ProjectName}/.
• Always emit BOTH tables — detailed (§9) and client summary (§9b). §9 is the internal/dev breakdown; §9b is the business-facing overview that gets sent to the client: general modules only, plain English, no QA row, no iteration-buffer row, no per-row reuse tags or O/P columns. Those hours are redistributed into the highest-effort module rows, never deleted — §9b’s total must equal §9’s exactly, per playable and combined. Never ship a report with only one of the two. Shape + self-check: report-template.md § 9b.
• Reconcile module + production totals to the WP totals. Re-slicing WP hours into modules must not change the number — same work, different cut. A mismatch means a missing or double-counted slice.
• Reuse-first, evidence-grounded. Every discount cites the reusable code found in step 3. Never assume greenfield when a framework exists.
• Base = O = L. One plan number; risk is on the downside only. Do not carry an optimistic floor below the base.
• Default deliverables are never billed. Param dashboard, draw-call/batching, size-budget compliance, low-end profiling — always excluded; state so explicitly.
• No juice in gameplay tasks. Gameplay WPs = mechanic/logic only; feedback juice is authored once in WP8.1; VFX assets in WP9. Never double-count.
• Clarify before costing (HARD-GATE). Grill on every material assumption via AskUserQuestion before the reuse sweep or any output (step 2). Zero silent assumptions. The only way past an unanswered item is an explicit user “proceed on stated defaults”, which records the checklist’s documented default in the report — never a value you invented. If you catch yourself drafting an “Assumptions” list the user never confirmed, STOP and ask.

Gotchas

• Design AT estimate time, not after. The whole point of this skill’s output is that the module architecture, signals, and class reference are settled while costing — so estimation confidence is per-class and the build needs no re-plan. If you find yourself emitting an estimate and deferring “the modules will be defined in planning,” STOP — that IS the planning, do it now (step 6). Ground the module tree in the real level-data samples + the reuse sweep, not in a generic genre template.
• [Name-Project] is a placeholder — flag the rename. In the module tree, use assets/scripts/[Name-Project]/ and state once that it must be renamed to the actual project folder before implementing. Do not silently invent a final name, and do not copy the template’s literal gameplay/ as the root folder.
• Pre-rigged models cut two ways: import/rig ≈ 0 (WP1 cheap) BUT skinned-mesh decimation must preserve rig + weights (WP2 more expensive). Apply both signs.
• Dynamic-color games (runtime note/tile recolor) lengthen env/shading polish — the look must read across the whole palette, not one fixed set.
• The level generator is the classic estimable-param trap: a JSON that just swaps values = default (0h); a JSON that spawns/positions/recolors notes at runtime = billable custom work (it’s a level tool). Bands for placement-only vs. +runtime per-note colour: estimation-rules.md § 3 (SSOT, not restated here).
• The standalone visual level editor is near-universal — never forget it. Most level-based playables ship a separate HTML tool to author the level JSON from scratch (grid/board canvas, entity placement, per-entity props, JSON export). This is its own bespoke package (WP10, ○ — band in estimation-rules.md § 3), distinct from runtime JSON ingestion (WP4.3) and from the param dashboard (WP6 default). The clarification gate (row 12) MUST confirm it; bill it by default unless the client explicitly wants no authoring tool. Omitting it silently under-bills a whole deliverable.
• Scan EVERY provided level-data sample, not just the first — the entity vocabulary grows across levels. A later level’s JSON can introduce a whole new mechanic absent from level 1 (e.g. a pedestrian layer: PS/C/PE waypoints that a character walks, car-collision = lose). Before finalizing, diff all samples for new type codes / layers / id fields; each new entity type = a new bespoke gameplay sub-item, and any animated character (pedestrian, NPC) reintroduces the two-sided skinned-mesh penalty (cheap pre-rigged import BUT dearer skinned optimization + character shading) even when the rest of the art is rigid. Assuming the first sample shows the full vocabulary is the trap.
• When the spec cites a reference (game / video / image / GIF), FIRST decide which source is authoritative — then reconcile against it. A reference is not one thing: (A) reference-exact — “do exactly like the ref clip, ignore the original game” → reconcile against the ref only (and confirm the clip shows the full loop incl. the lose case; clips are usually partial); (B) original-authoritative — “the original game is the source of truth (GOAT), the ref is just clearer visuals” → reconcile against the ORIGINAL’s full cast (a separate character/avatar the brief’s prose skipped lives here); (C) mixed → per-element source × scope table, nothing assumed. The brief’s prose always UNDER-lists whichever source is authoritative — it names the headline loop and forgets secondary actors, NPCs, hazard layers, meta-timers. Each confirmed-IN secondary element is its OWN §5 module row. See clarification-gate.md row 1 + the “Reference reconciliation” section (Step 0 = pick A/B/C). This is the reference-driven twin of the “scan every level-data sample” gotcha.
• Env/shading polish scales per distinct model to shade (rate per estimation-rules.md § 5), not per scene. Count the models.
• Don’t inflate the base to “tighten the spread.” Close the Base↔Worst gap by keeping the base lean and only widening P on genuinely risky tasks — never by raising the base.
• MCP reuse sweep is keyword-across-corpus, not a single-project lookup — the index holds many codebases; search by capability and use whatever surfaces.
• Never output on first pass with buried assumptions. The #1 failure mode is emitting a polished report whose “Assumptions” section quietly guessed the gameplay mechanic, the level-data format, or art readiness. Those are exactly the items that swing the number most — they belong in step 2’s AskUserQuestion, not in a fait-accompli report. A stated default is legitimate ONLY after an explicit “proceed on defaults” override.
• The client summary is a re-slice, not a re-estimate. The failure mode on §9b is arithmetic: you drop the QA and buffer rows “because the client doesn’t need them” and the total silently falls by 15%, so the quote no longer matches the plan. Redistribute those hours into the biggest module rows and re-add the column before emitting. Equally wrong is spreading them evenly — put them where the risk is, so the largest line still reads as the largest risk.
• Batch the grill, don’t drip it. Group unknowns into as few AskUserQuestion calls as possible (max 4 questions/call) so the user answers in one or two passes — don’t ask one question, cost a little, ask another. Resolve the assumption set, then cost once.
• A bundled answer settles every row it bundled — re-read the answers before each grill round. Batching means one option can answer two rows at once (“Portrait only, multi-network” settles orientation and networks); the checklist is still tracked per row, so the second row reads as untouched and gets re-asked. Re-asking a settled sub-question is a gate violation. And row 8 (ad networks) is never asked at all — standing studio default (row 8 col 4 carries the values), with any unquantified answer resolving to it, never to a count. See the bundled-answer rule in clarification-gate.md, just under How to use it.

Security & scope: this skill estimates Cocos playable effort only; it does not implement. Full rules in estimation-rules.md.