team-polish skill

If no argument is provided, output usage guidance and exit without spawning any agents:

Usage: /team-polish [feature or area] — specify the feature or area to polish (e.g., combat, main menu, inventory system, level-1). Do not use AskUserQuestion here; output the guidance directly.

When this skill is invoked with an argument, orchestrate the polish team through a structured pipeline.

Decision Points: At each phase transition, use AskUserQuestion to present the user with the subagent's proposals as selectable options. Write the agent's full analysis in conversation, then capture the decision with concise labels. In collaborative mode, the user must approve before moving to the next phase. In guided mode the pipeline advances automatically unless a phase is BLOCKED; in autonomous mode it runs end to end, recording each phase outcome via logdecision. Decisions in automationalwaysask categories (isalwaysaskcategory helper) always prompt regardless of mode. See .claude/docs/automation-modes.md.

Phase 0: Resolve Config

!bash "${CLAUDESKILLDIR}/../../hooks/yaml-helper.sh" resolveconfig --keys reviewmode,automation,team.size

Resolved above — use as-is; --review overrides review_mode. No block → defaults in .claude/docs/config-resolution.md.

review_mode sets gate depth:

• full — spawn all director and lead gates as described
• lean — skip director gates unless they are PHASE-GATE type (CD-PHASE-GATE, TD-PHASE-GATE, PR-PHASE-GATE, AD-PHASE-GATE)
• solo — skip all director gate spawning entirely; run the skill without any agent gates

automation drives the Decision Points note above. See the Decision Points note above and .claude/docs/automation-modes.md for how each mode changes pipeline behavior.

team.size: which agents are active (orthogonal to review_mode gate-depth and workflow docs).

Directors (CD/TD/PR) still spawn at phase gates regardless of size; a non-core agent needed at individual routes through the nearest active core agent with an informational note. "Phase gate" means any phase that ends in an AskUserQuestion decision point before the pipeline advances — not every phase. Apply the test literally: if the phase below has no decision point, it is not a gate, and an agent restricted to "phase gates only" is not spawned for it. This active-set scoping applies throughout the pipeline below: any phase that names an agent outside the active set routes through the nearest core agent rather than spawning it.

• individual (default): performance-analyst + technical-artist. Other agents consulted via these two, not spawned separately.
• small: + sound-designer + qa-tester (the full pipeline as documented).
• studio: full pipeline + engine sub-specialists + an adversarial review pass.

Announce the active set before Phase 1 — never let the collapse be silent. Before spawning anything, state in one line which agents this run will actually spawn, and which the pipeline below names but will not spawn at the resolved team.size. For example:

Active set (team.size: ): .

Not spawned this run: — consulted

through . Raise team.size (or modes.rigor) to widen.

Fill it from the team.size list directly above and the agents this file's own pipeline names — not from an example. Both sets differ per orchestrator.

The pipeline below reads as a multi-agent fan-out and at the shipped default it is one or two agents — team-release names eight and runs one, team-narrative names six across five phases and runs writer alone. The collapse is correct: team.size is rigor-fronted and the narrow default is the token lever, measured at roughly 10x. What was wrong is that nothing said so, so a reader could not distinguish a correctly-collapsed run from a broken pipeline, and the per-agent "routes through the nearest core agent with an informational note" rule above fires at routing time and never states the shape of the run as a whole.

This is the same rule as the skipped-check reporting elsewhere in this file: a constraint that is enforced but never surfaced is indistinguishable, to the person reading the output, from one that was never enforced.

Director gate skip rule: Before spawning any Tier 1 director or lead for review (outside of PHASE-GATE triggers), apply the resolved mode: skip if solo mode; skip if lean mode and this is not a PHASE-GATE.

Team Composition

• performance-analyst — Profiling, optimization, memory analysis, frame budget
• engine-programmer — Engine-level bottlenecks: rendering pipeline, memory, resource loading (invoke when performance-analyst identifies low-level root causes)
• technical-artist — VFX polish, shader optimization, visual quality
• sound-designer — Audio polish, mixing, ambient layers, feedback sounds
• tools-programmer — Content pipeline tool verification, editor tool stability, automation fixes (invoke when content authoring tools are involved in the polished area)
• qa-tester — Edge case testing, regression testing, soak testing

How to Delegate

Use the Agent tool to spawn each team member as a subagent:

• subagent_type: performance-analyst — Profiling, optimization, memory analysis
• subagent_type: engine-programmer — Engine-level fixes for rendering, memory, resource loading
• subagent_type: technical-artist — VFX polish, shader optimization, visual quality
• subagent_type: sound-designer — Audio polish, mixing, ambient layers
• subagent_type: tools-programmer — Content pipeline and editor tool verification
• subagent_type: qa-tester — Edge case testing, regression testing, soak testing

Brief each agent — do not dump context. Read the shared inputs once and pass a distilled brief inline: the lines each agent actually needs, never a file path for a document you have already read (an agent handed a path re-reads the whole file). Pass a path only for a document you have not read and only that agent needs.

End every agent prompt with a return contract: "Write your full output to [path] — that named path is your write authorisation under the bounded exception below, so write it without a separate approval prompt. Return only (1) the path written, (2) a ≤5-bullet summary of decisions, (3) any BLOCKED/CONCERNS items, one line each. Do not restate the documents you read." Without it, an agent returns everything it read back into this session.

Substitute a real path for [path] — this skill's destination is production/polish/. Name it per agent, one file each:

Why production/ and not docs/. These are date-stamped measurements of

one run, the same shape as production/qa/smoke-[date].md — not durable

specifications like docs/architecture/. Keeping them beside the other

point-in-time process artifacts is what makes a later comparison possible.

The [path] contract above has a precondition: the path is one you named, so

a concrete destination must be stated here or every run invents one. Unlike

/team-qa and /team-narrative, whose destinations are fixed by their

consumers, this location has no reader in the repo and was chosen deliberately.

Nothing reads production/polish/ yet — say so when reporting, so the user

knows the report is a record rather than an input to a later gate.

Why this does not violate the Collaboration Protocol. CLAUDE.md requires an agent to ask "May I write this to [filepath]?" before Write/Edit. A subagent spawned here writes without asking, and that is a deliberate, bounded exception rather than an oversight — the same call already made for consistency-check appending to active.md. The exception holds only when all three are true: (1) the path is one you named in the prompt, so the user approved the destination when they approved the phase; (2) it is a new artifact under production/, docs/ or tests/, never an edit to existing source or config; (3) the phase that produced it is itself gated by an AskUserQuestion before the pipeline advances. Outside those three, the agent must ask. Do not "fix" this by asking per subagent — a prompt per agent per phase makes an orchestrator unusable, which is why the exception exists.

Launch independent agents in parallel where the pipeline allows it (e.g., Phases 3 and 4 can run simultaneously).

Pipeline

Phase 1: Assessment

Delegate to performance-analyst:

• Profile the target feature/area using /perf-profile
• Identify performance bottlenecks and frame budget violations
• Measure memory usage and check for leaks
• Benchmark against target hardware specs
• Output: performance report with prioritized optimization list

Phase 2: Optimization

Delegate to performance-analyst (with relevant programmers as needed):

• Fix performance hotspots identified in Phase 1
• Optimize draw calls, reduce overdraw
• Fix memory leaks and reduce allocation pressure
• Verify optimizations don't change gameplay behavior
• Output: optimized code with before/after metrics

If Phase 1 identified engine-level root causes (rendering pipeline, resource loading, memory allocator), delegate those fixes to engine-programmer in parallel:

• Optimize hot paths in engine systems
• Fix allocation pressure in core loops
• Output: engine-level fixes with profiler validation

Phase 3: Visual Polish (parallel with Phase 2)

Delegate to technical-artist:

• Review VFX for quality and consistency with art bible
• Optimize particle systems and shader effects
• Add screen shake, camera effects, and visual juice where appropriate
• Ensure effects degrade gracefully on lower settings
• Output: polished visual effects

Phase 4: Audio Polish (parallel with Phase 2)

Delegate to sound-designer:

• Review audio events for completeness (are any actions missing sound feedback?)
• Check audio mix levels — nothing too loud or too quiet relative to the mix
• Add ambient audio layers for atmosphere
• Verify audio plays correctly with spatial positioning
• Output: audio polish list and mixing notes

Phase 5: Hardening

Delegate to qa-tester:

• Test all edge cases: boundary conditions, rapid inputs, unusual sequences
• Soak test: run the feature for extended periods checking for degradation
• Stress test: maximum entities, worst-case scenarios
• Regression test: verify polish changes haven't broken existing functionality
• Test on minimum spec hardware (if available)
• Output: test results with any remaining issues

Phase 6: Sign-off