Claude-Code-Game-Studios/CCGS Skill Testing Framework/skills/team/team-polish.md

Skill Test Spec: /team-polish

Skill Summary

Orchestrates the polish team through a six-phase pipeline: performance assessment (performance-analyst, whose report carries the optimisation list with an owner per item) → optimization (the list implemented by its owners in the active set — engine-programmer for engine-level root causes, tools-programmer for a content tool; performance-analyst writes no game code) → visual polish (technical-artist, parallel with Phase 2) → audio polish (sound-designer, parallel with Phase 2) → hardening (qa-tester) → sign-off (orchestrator collects all results and issues READY FOR RELEASE, NOT ASSESSED or NEEDS MORE WORK — NOT ASSESSED when a budget is uncommitted or a phase did not run). Phase 0 resolves review_mode, automation and team.size and the skill announces the active set before Phase 1 — the default individual spawns performance-analyst + technical-artist only, so no programmer is active and the report names the optimisation list as handed to /dev-story; small adds sound-designer, qa-tester and engine-programmer (the full pipeline); studio keeps that set and adds an adversarial pass. Each agent writes a date-stamped report to a named path under production/polish/ under the bounded write exception (no per-write prompt), and the orchestrator states that nothing reads production/polish/ yet. The code, shader, audio and asset changes of Phases 2–4 are outside that exception: one ask covers the whole set. Uses AskUserQuestion at each phase transition. Engine-programmer is spawned conditionally only when Phase 1 identifies engine-level root causes.

---

Static Assertions (Structural)

• Has required frontmatter fields: name, description, argument-hint, user-invocable, allowed-tools
• Has ≥2 phase headings
• Contains verdict keywords: READY FOR RELEASE, NOT ASSESSED, NEEDS MORE WORK — and states that NOT ASSESSED ranks above READY FOR RELEASE and below NEEDS MORE WORK
• Contains "File Write Protocol" section
• File writes are delegated to sub-agents — orchestrator does not write files directly
• Names a destination per agent under production/polish/: [area]-report-[date].md (performance-analyst), [area]-render-notes-[date].md (technical-artist), [area]-engine-fixes-[date].md (engine-programmer), [area]-tool-fixes-[date].md (tools-programmer), [area]-audio-notes-[date].md (sound-designer), [area]-verification-[date].md (qa-tester)
• Sub-agents write those named production/ paths without a per-write prompt (bounded exception), and must ask for any write outside it; implementation files (code, shaders, audio, assets) are outside it — each agent lists the files it will create or change, and the skill asks once for the set before any is written — one ask for the whole Phase 2–4 set, never one per phase
• The small and studio sets include engine-programmer; at individual no programmer is active and the report names the optimisation list as handed to /dev-story
• Defines a phase gate as a decision point the pipeline itself lists, whatever the automation mode, and claims no director spawn at phase gates
• Has a next-step handoff at the end (references /release-checklist, /sprint-plan update, /gate-check)
• Error Recovery Protocol section is present: verify a named artifact is on disk, surface BLOCKED immediately, always produce a partial report, full procedure in .claude/docs/error-recovery-protocol.md
• AskUserQuestion is used at phase transitions before proceeding (collaborative mode)
• Phase 0 resolves team.size, and the skill requires a one-line active-set announcement before Phase 1
• Phase 3 (visual polish) and Phase 4 (audio polish) are explicitly run in parallel with Phase 2
• Phase 1's report carries the optimisation list with an owner per item; performance-analyst writes no game code in any phase
• engine-programmer is conditionally spawned in Phase 2 only when Phase 1 identifies engine-level root causes
• Phase 6 sign-off compares metrics against budgets before issuing verdict
• Phase 6 lists every remaining issue with its severity, the measured gap where there is one (e.g. "3 ms over budget") and a recommendation

---

Test Cases

Case 1: Happy Path — Full pipeline completes, READY FOR RELEASE verdict

Fixture:

• Resolved config block: team.size: small, automation: collaborative
• Feature exists and is functionally complete (e.g., combat system)
• Performance budgets are defined in project.yaml (performance.target_framerate: 60, performance.frame_budget_ms: 16.6, performance.draw_call_limit: 2000, performance.memory_ceiling_mb: 2048)
• No frame budget violations exist before polishing begins
• No audio events are missing; VFX assets are complete
• No regressions are introduced by polish changes

Input: /team-polish combat

Expected behavior:

1. Before any spawn, one line announces the active set for team.size: small (the full pipeline)
2. Phase 1: performance-analyst is spawned; profiles the combat system, measures frame budget, checks memory usage; writes production/polish/combat-report-[date].md showing all metrics within budget
3. AskUserQuestion presents performance report; user approves before Phases 2, 3, and 4 begin
4. Phase 2: the report's optimisation list holds only minor rendering items (e.g., draw call batching), owned by technical-artist, so they join its Phase 3 brief; no engine-level root cause was identified, so engine-programmer is not spawned; performance-analyst changes no code
5. Phases 3 and 4 are launched in parallel alongside Phase 2:
   • Phase 3: technical-artist reviews VFX for quality, optimizes particle systems, adds screen shake and visual juice; writes production/polish/combat-render-notes-[date].md
   • Phase 4: sound-designer reviews audio events for completeness, checks mix levels, adds ambient audio layers; writes production/polish/combat-audio-notes-[date].md
   • The agents changing shaders, VFX or assets first list the files; one AskUserQuestion covers the whole Phase 2–4 set, and nothing is edited before the yes
6. All three parallel phases complete; AskUserQuestion presents results; user approves before Phase 5 begins
7. Phase 5: qa-tester runs edge case tests, soak tests, stress tests, and regression tests; all pass; writes production/polish/combat-verification-[date].md
8. AskUserQuestion presents test results; user approves before Phase 6
9. Phase 6: orchestrator collects all results; compares before/after performance metrics against budgets; all metrics pass
10. The report says the production/polish/ files are a record that nothing in the repo reads yet
11. Verdict: READY FOR RELEASE

Assertions:

• Active-set line naming team.size: small appears before the first agent is spawned
• performance-analyst is spawned first in Phase 1 before any other agents
• AskUserQuestion appears after Phase 1 output and before Phases 2/3/4 launch
• Phases 3 and 4 Agent calls are issued at the same time as Phase 2 (not after Phase 2 completes)
• engine-programmer is NOT spawned when Phase 1 finds no engine-level root causes
• performance-analyst edits no code, shader or asset in any phase
• Implementation files of Phases 2–4 are listed by each agent and asked for in one AskUserQuestion for the whole set — not once per phase — before any is edited
• qa-tester (Phase 5) is not launched until the parallel phases complete and user approves
• Each agent writes to its named production/polish/[area]-…-[date].md path without a per-write prompt, and the orchestrator confirms the file exists before treating the phase as done
• Phase 6 verdict is based on comparison of metrics against defined budgets
• Summary report includes: before/after performance metrics, visual polish changes, audio polish changes, test results
• Summary states that nothing reads production/polish/ yet
• No files are written by the orchestrator directly
• Verdict is READY FOR RELEASE

---

Case 2: Performance Blocker — Frame budget violation cannot be fully resolved

Fixture:

• Resolved config block: team.size: small, automation: collaborative
• Feature being polished: particle-storm VFX system
• Phase 1 identifies a frame budget violation: particle-storm costs 12ms on target hardware (budget is 6ms for this system)
• Phase 1's optimisation list assigns the particle work to technical-artist and an engine-level particle-update hot path to engine-programmer; after both are applied the cost is 9ms — still over the 6ms budget
• Phase 2 cannot fully resolve the violation without a fundamental design change

Input: /team-polish particle-storm

Expected behavior:

1. Phase 1: performance-analyst identifies the 12ms frame cost vs. 6ms budget; reports "FRAME BUDGET VIOLATION: particle-storm costs 12ms, budget is 6ms", with an optimisation list naming each item's owner
2. AskUserQuestion presents the violation; user chooses to proceed with optimization attempt
3. Phase 2: engine-programmer implements the engine-level item and technical-artist the particle items (after the one ask for the set); the re-profile reads 9ms — reduced but still over budget: "Optimization reduced cost to 9ms (was 12ms) — 3ms over budget. No further gains achievable without design changes."
4. Phases 3 and 4 run in parallel with Phase 2 (visual and audio polish)
5. Phase 5: qa-tester runs regression and edge case tests; all pass
6. Phase 6: orchestrator collects results; frame budget violation (9ms vs 6ms budget) remains unresolved
7. Verdict: NEEDS MORE WORK
8. Report lists the specific unresolved issue with severity: "particle-storm frame cost (9ms) exceeds budget (6ms) by 3ms — requires design scope reduction or budget renegotiation"
9. Next Steps: schedule the remaining issue in /sprint-plan update; re-run /team-polish after fix

Assertions:

• Frame budget violation is flagged in Phase 1 with specific numbers (actual vs. budget)
• Phase 2 reports the post-optimization metric explicitly (9ms achieved, 3ms still over)
• Verdict is NEEDS MORE WORK (not READY FOR RELEASE) when a budget violation remains
• The specific unresolved issue is listed by name with the remaining gap quantified
• Next Steps references /sprint-plan update for scheduling the remaining fix
• Phases 3 and 4 still run (polish work is not abandoned due to a Phase 2 partial resolution)
• Phase 5 qa-tester still runs (regression testing is independent of the performance outcome)

---

Case 3: No Argument — Usage guidance shown

Fixture:

• Any project state

Input: /team-polish (no argument)

Expected behavior:

1. Skill detects no argument is provided
2. Outputs usage guidance: e.g., "Usage: /team-polish [feature or area to polish] [--review full|lean|solo] — specify the feature or area to polish (e.g., combat, main menu, inventory system, level-1)"
3. Skill exits without spawning any agents

Assertions:

• Skill does NOT spawn any agents when no argument is provided
• Usage message shows the full argument-hint — /team-polish [feature or area to polish] [--review full|lean|solo] — and argument examples
• Skill does NOT attempt to guess a feature from project files
• No AskUserQuestion is used — output is direct guidance

---

Case 4: Engine-Level Bottleneck — engine-programmer spawned conditionally in Phase 2

Fixture:

• Resolved config block: team.size: small, automation: collaborative
• Feature being polished: open-world environment streaming
• Phase 1 identifies a performance bottleneck with a root cause in the rendering pipeline: "draw call overhead is caused by the engine's scene tree traversal in the spatial indexer — this is an engine-level issue, not a game code issue"
• Performance budgets are defined; the rendering overhead exceeds target frame budget

Input: /team-polish open-world

Expected behavior:

1. Phase 1: performance-analyst profiles the environment; identifies frame budget violation; root cause analysis points to engine-level rendering pipeline (spatial indexer traversal overhead)
2. Phase 1 output explicitly classifies the root cause as engine-level
3. AskUserQuestion presents the performance report including the engine-level root cause; user approves before Phase 2
4. Phase 2: engine-programmer (in the small set) is spawned for the engine-level rendering item on the optimisation list, writing production/polish/open-world-engine-fixes-[date].md; performance-analyst writes no code
5. Phases 3 and 4 also run in parallel with Phase 2 (visual and audio polish); engine-programmer lists the engine files it will change along with the other agents' files, and one ask covers the set
6. engine-programmer addresses the spatial indexer traversal after the yes; provides profiler validation showing the fix reduces overhead
7. Phase 5: qa-tester runs regression tests including tests for the engine-level change
8. Phase 6: orchestrator collects all results; if metrics are now within budget, verdict is READY FOR RELEASE; if not, NEEDS MORE WORK

Assertions:

• engine-programmer is NOT spawned in Phase 2 unless Phase 1 explicitly identifies an engine-level root cause
• engine-programmer is spawned in Phase 2 when Phase 1 identifies an engine-level root cause
• engine-programmer's Phase 2 Agent call is issued alongside the Phase 3 and 4 calls (not sequentially), and performance-analyst is not re-spawned to change code
• engine-programmer edits nothing before the one ask for the Phase 2–4 implementation set is answered yes
• Phases 3 and 4 also run in parallel with Phase 2 (not deferred until Phase 2 completes)
• engine-programmer's output includes profiler validation of the fix
• qa-tester in Phase 5 runs regression tests that cover the engine-level change
• Verdict correctly reflects whether all metrics including the engine fix now meet budgets

---

Case 5: Regression Found — Polish change broke an existing feature

Fixture:

• Resolved config block: team.size: small, automation: collaborative
• Feature being polished: inventory-ui
• Phases 1–4 complete successfully; performance and polish changes are applied
• Phase 5: qa-tester runs regression tests and finds that a shader optimization applied in Phase 3 broke the item highlight glow effect on hover — an existing feature that was working before the polish pass

Input: /team-polish inventory-ui (Phase 5 scenario)

Expected behavior:

1. Phases 1–4 complete; polish changes include a shader optimization from technical-artist
2. Phase 5: qa-tester runs regression tests and detects "Item highlight glow on hover no longer renders — regression introduced by shader optimization in Phase 3"
3. qa-tester writes its findings to production/polish/inventory-ui-verification-[date].md (no per-write prompt) and returns the regression as a CONCERNS/BLOCKED line in its return contract
4. The orchestrator confirms the verification file exists, then at the Phase 5 → Phase 6 transition writes qa-tester's full analysis in conversation — naming the broken behavior and the Phase 3 shader change that caused it — and captures the decision via AskUserQuestion with qa-tester's proposals as options
5. Phase 6: the regression is listed among remaining issues with severity and a recommendation
6. Verdict: NEEDS MORE WORK
7. Next Steps: schedule the fix in /sprint-plan update and re-run /team-polish after fixes

Assertions:

• Regression is surfaced before Phase 6 sign-off
• The specific broken behavior and the responsible change are both named in the report
• qa-tester's findings are written to production/polish/inventory-ui-verification-[date].md without a separate approval prompt
• AskUserQuestion at the Phase 5 → 6 transition presents the regression and qa-tester's proposed resolutions as selectable options
• Phase 6 lists the regression as a remaining issue with severity
• Verdict is NEEDS MORE WORK when a regression is present and unresolved
• Next Steps directs the fix to /sprint-plan update and a /team-polish re-run — no in-session fix is reported as verified

---

Case 6: No Budgets Committed — NOT ASSESSED, not READY FOR RELEASE

Fixture:

• Resolved config block: team.size: small, automation: collaborative
• project.yaml sets none of performance.target_framerate, performance.frame_budget_ms, performance.draw_call_limit or performance.memory_ceiling_mb, and no design doc states a budget for the area
• Feature being polished: main-menu; every phase completes, and qa-tester finds no regressions

Input: /team-polish main-menu

Expected behavior:

1. Phase 1: performance-analyst profiles the menu via /perf-profile; each metric is reported as measured but NOT ASSESSED — no committed budget — never as within budget or with headroom against a placeholder such as 16.67 ms
2. Phases 2–5 run normally; nothing is found over budget and there are no regressions
3. Phase 6: no known problem, but the budget comparison could not run, so the verdict is NOT ASSESSED — not READY FOR RELEASE — and the report names each unset performance.* key
4. Next Steps: commit the budgets in project.yaml and re-run /team-polish; /release-checklist is not offered as the next step

Assertions:

• Verdict is NOT ASSESSED, not READY FOR RELEASE
• The report names each unset performance.* key as the reason
• No metric is described as within budget, and no headroom is computed against a placeholder budget
• Next Steps asks for the budgets and a re-run rather than handing off to /release-checklist
• A regression found in the same run would make the verdict NEEDS MORE WORK instead — the missing budgets do not mask a known problem

---

Case 7: Default individual — the optimisation list is handed to /dev-story

Fixture:

• Resolved config block: team.size: individual, automation: collaborative
• Budgets committed in project.yaml (as in Case 1)
• Feature being polished: crafting-menu; Phase 1 finds a draw-call overrun owned by technical-artist and a script hot path in the crafting logic owned by gameplay-programmer — no engine-level root cause

Input: /team-polish crafting-menu

Expected behavior:

1. The active-set line names performance-analyst + technical-artist; the not-spawned line names sound-designer, qa-tester, engine-programmer and tools-programmer
2. Phase 1: performance-analyst writes production/polish/crafting-menu-report-[date].md with the optimisation list, each item naming its owner
3. Phase 2: no programmer is active, so no agent implements the script item — performance-analyst does not implement it either; the draw-call item joins technical-artist's Phase 3 brief
4. The report lists the gameplay-programmer item under "Optimisation list handed to /dev-story: production/polish/crafting-menu-report-[date].md"
5. Phase 6: audio polish and hardening did not run; if the script hot path keeps a metric over budget the verdict is NEEDS MORE WORK, otherwise NOT ASSESSED
6. Next Steps: implement the handed-off items with /dev-story, then re-run /team-polish

Assertions:

• No agent changes code for the gameplay-programmer item in this run, and performance-analyst changes nothing
• The report names the optimisation list as handed to /dev-story, with the path and each item's owner
• Verdict is never READY FOR RELEASE at individual
• An over-budget metric the handed-off item targets makes the verdict NEEDS MORE WORK

---

Protocol Compliance

• At the default team.size: individual, the run opens with an Active set (team.size: individual): performance-analyst + technical-artist line and a Not spawned this run: line naming sound-designer, qa-tester, engine-programmer and tools-programmer — before any agent is spawned
• Phase 1 (assessment) must complete before any other phase begins
• In collaborative mode, AskUserQuestion is used after every phase output before the next phase launches
• Phases 3 and 4 are launched in parallel with Phase 2 whenever their agents are in the active set (not deferred)
• engine-programmer is only spawned when Phase 1 explicitly identifies engine-level root causes, and only at small or studio
• performance-analyst produces the optimisation list and never implements it; an item whose owner is not active is named as handed to /dev-story
• Phase 2–4 implementation files are asked for once, as a set — not once per phase
• No files are written by the orchestrator directly — all writes are delegated to sub-agents
• Sub-agents skip the per-write prompt only for their named production/polish/ paths; any other write requires a "May I write" ask
• A phase whose named artifact is missing on disk is treated as failed, not done
• BLOCKED status from any agent is surfaced immediately — not silently skipped
• A partial report is always produced when some agents complete and others block
• Verdict is exactly one of READY FOR RELEASE, NOT ASSESSED or NEEDS MORE WORK — a known problem is NEEDS MORE WORK even when something else went unchecked, and READY FOR RELEASE is reachable only when every measured metric had a committed budget and every phase ran
• At team.size: individual, sound-designer's audio polish and qa-tester's hardening are named as not run, so the verdict is NOT ASSESSED unless a known problem makes it NEEDS MORE WORK
• NEEDS MORE WORK verdict always lists specific remaining issues with severity, the measured gap where there is one, and a recommendation
• Next Steps handoff references /release-checklist (on success), /sprint-plan update and a /team-polish re-run (on failure), /gate-check before handing off to release, and, on NOT ASSESSED, supplying the missing budgets or phases before a re-run
• At team.size: studio, Phase 5's qa-tester is told to find how the polished feature breaks rather than confirm it holds, and the report says the adversarial pass ran; no engine specialist is added

---

Coverage Notes

• The tools-programmer optional agent (for content pipeline tool fixes) is not separately tested — it follows the same conditional spawn pattern as engine-programmer and is invoked in Phase 2, at small or studio, only when Phase 1 traces a cause to a content authoring tool.
• The "Retry with narrower scope" and "Skip this agent" resolution paths from the Error Recovery Protocol are not separately tested — they follow the same AskUserQuestion
  • partial-report pattern validated in Cases 2 and 5.
• Phase 6 sign-off logic (collecting and comparing all metrics) is validated implicitly by Cases 1 and 2. The distinction between READY FOR RELEASE and NEEDS MORE WORK is exercised in both directions across these cases, and NOT ASSESSED by Case 6.
• The individual path — audio polish and hardening not run, the optimisation list handed to /dev-story — is given Case 7.
• Soak testing and stress testing (Phase 5) are validated implicitly by Case 1's qa-tester output. Case 5 focuses on the regression detection aspect of Phase 5.
• The "minimum spec hardware" test path in Phase 5 is not separately tested — it follows the same qa-tester delegation pattern when the hardware is available.
• The studio addition (the adversarial review pass) is asserted in Protocol Compliance but not given its own case.