Claude-Code-Game-Studios/CCGS Skill Testing Framework/skills/utility/localize.md

Skill Test Spec: /localize

Skill Summary

/localize runs the localization pipeline through one required subcommand: scan, extract, validate, status, brief, cultural-review, vo-pipeline, rtl-check, freeze or qa. It works on a single source string table under assets/data/strings/ (strings-en.json is the English source; the other locales sit beside it) and writes reports under production/localization/.

scan, validate and status are read-only. extract shows a diff of new keyed entries and asks "May I write these new entries to assets/data/strings/strings-en.json?" before appending only the diff; its verdict is COMPLETE. With no subcommand the skill prints usage and stops with verdict FAIL — missing required subcommand. A scan whose code root cannot be resolved reports NOT ASSESSED — code root unresolved; a status run with no string table reports NOT ASSESSED — no string table found. cultural-review and qa spawn localization-lead; qa issues a per-locale PASS / PASS WITH CONDITIONS / NOT ASSESSED / FAIL verdict, first match FAIL → NOT ASSESSED → PASS WITH CONDITIONS → PASS. Its checks are playthrough-based, so a locale nobody has played is NOT ASSESSED, and the release gate does not count it as passed. No director gates apply.

---

Static Assertions (Structural)

Checked against the SKILL.md by /skill-test spec — no fixture needed.

• Has required frontmatter fields: name, description, argument-hint, user-invocable, allowed-tools
• Has ≥2 phase headings
• Contains verdict keywords: COMPLETE, FAIL, NOT ASSESSED, PASS WITH CONDITIONS
• Contains "May I write" collaborative protocol language before writing the string table or a report
• Has a next-step handoff (the Recommended Workflow chain ending in /gate-check release)
• The QA gate note is tiered: at workflow: full the Polish → Release gate requires PASS or PASS WITH CONDITIONS for every translated locale being shipped (recommended at standard, dropped at minimal)
• The freeze question names the file it writes — "This writes production/localization/freeze-status.md" — before the user answers

---

Director Gate Checks

None. /localize is a pipeline utility and spawns no director. The only agent it spawns is localization-lead (an operations-tier agent), and only in the cultural-review and qa modes.

---

Test Cases

Case 1: Extract — New Strings Keyed and Appended After Approval

Fixture:

• project.yaml has engine.name: Godot, so the code root is src/
• src/ui/hud.gd wraps three strings in tr() that have no entry in assets/data/strings/strings-en.json
• No production/localization/freeze-status.md exists

Input: /localize extract

Expected behavior:

1. Skill scans source files for localized string references and compares them against the table in assets/data/strings/
2. Skill proposes one new entry per unkeyed string, with a key in the form [category].[subcategory].[description] (e.g. ui.hud.health_label)
3. Each new entry carries a context field: where it appears, maximum length, placeholder meaning
4. Skill presents the diff and asks "May I write these new entries to assets/data/strings/strings-en.json?"
5. On approval it writes only the new entries (not a full replacement); verdict is COMPLETE

Assertions:

• Proposed keys follow [category].[subcategory].[description]
• Every new entry includes a context field
• The diff is shown and "May I write" names assets/data/strings/strings-en.json before any write
• Only the three new entries are written — existing entries are not rewritten
• Verdict is COMPLETE

---

Case 2: No Subcommand — Usage and FAIL

Fixture:

• Any project state

Input: /localize

Expected behavior:

1. Skill finds no subcommand in the argument
2. Skill outputs usage (the ten modes) and stops
3. Verdict is FAIL — missing required subcommand

Assertions:

• Usage listing the available modes is printed
• Verdict is FAIL with the reason "missing required subcommand"
• No scan, extract or validation work is performed
• No file is written and no "May I write" ask appears

---

Case 3: Validate — Gaps Reported by Locale, Nothing Written

Fixture:

• assets/data/strings/ holds strings-en.json, strings-fr.json and strings-de.json
• strings-de.json lacks 4 keys present in the English source
• One French entry omits the {playerName} placeholder its English source has

Input: /localize validate

Expected behavior:

1. Skill reads every string table file in assets/data/strings/
2. For de it reports the 4 keys as Completeness gaps
3. For fr it reports a Placeholder mismatch on the affected key
4. Results are grouped by locale and severity
5. Skill writes nothing — validate is read-only

Assertions:

• The 4 missing keys are named and attributed to the de locale
• The placeholder mismatch is reported against the fr locale and its key
• Output is grouped by locale and severity
• No file is written or modified, and no "May I write" ask appears

---

Case 4: Status With No String Table — NOT ASSESSED

Fixture:

• assets/data/strings/ does not exist

Input: /localize status

Expected behavior:

1. Skill looks for the source string table and finds none
2. The whole status output is NOT ASSESSED — no string table found
3. Skill does not produce a coverage matrix of zeros, and does not pre-fill the source row as 100%

Assertions:

• Output is NOT ASSESSED — no string table found
• No coverage matrix with zero counts is produced
• The source locale is not reported as 100% coverage
• No file is written (status is read-only)

---

Case 5: Director Gate Check — None; Cultural Review Uses localization-lead

Fixture:

• assets/data/strings/strings-en.json exists with player-facing strings
• Any review mode

Input: /localize cultural-review

Expected behavior:

1. Skill spawns localization-lead to audit strings and assets for cultural sensitivity
2. Findings are presented as a table with a severity of BLOCKING, ADVISORY or NOTE per finding
3. Skill asks "May I write this cultural review report to production/localization/cultural-review-[date].md?"
4. No director agent is spawned and no gate ID appears in output

Assertions:

• localization-lead is the only agent spawned
• No director gate (creative, technical, producer, art) is invoked and no gate skip message appears
• Each finding carries BLOCKING, ADVISORY or NOTE severity
• "May I write" names production/localization/cultural-review-[date].md before the report is written

---

Case 6: Scan With an Unresolved Code Root — NOT ASSESSED, never "no hardcoded strings"

Fixture:

• project.yaml has no engine.name; .claude/docs/technical-preferences.md reads [TO BE CONFIGURED]
• Both src/ and Assets/ exist and hold UI code with hardcoded strings (ambiguous tree)

Input: /localize scan

Expected behavior:

1. Skill tries to resolve the code root and cannot (no engine, two candidate roots)
2. It reports NOT ASSESSED — code root unresolved for the hardcoded-string search and says which checks did not run
3. It does not guess src/, and does not report zero hits or "no hardcoded strings found" — that would read as "nothing to localize"
4. Nothing is written — scan is read-only

Assertions:

• Output reads NOT ASSESSED — code root unresolved for the code search
• No "no hardcoded strings" or zero-hit result is reported
• The code root is not assumed to be src/
• No file is written and no "May I write" ask appears

---

Case 7: QA on a Locale Nobody Has Played — NOT ASSESSED

Fixture:

• assets/data/strings/strings-en.json and strings-fr.json exist and validate cleanly
• No one has played the French build: there are no in-game observations for the functional, overflow, contextual-accuracy or VO checks

Input: /localize qa

Expected behavior:

1. Skill spawns localization-lead for the QA plan
2. The playthrough-based checks have no results, and no BLOCKING finding is open, so the French verdict is NOT ASSESSED, naming each check that did not run
3. The verdict is not PASS or PASS WITH CONDITIONS on the strength of the string tables alone
4. Skill asks "May I write this localization QA report to production/localization/loc-qa-fr-[date].md?"; the report says the locale has not passed QA for the release gate

Assertions:

• The French Status is NOT ASSESSED, with the unrun checks named
• No PASS or PASS WITH CONDITIONS is issued for an unplayed locale
• "May I write" names the loc-qa report path before it is written
• The report does not present the locale as cleared for the Polish → Release gate

---

Protocol Compliance

• Stops with usage and verdict FAIL when no subcommand is given
• scan, validate and status write no files
• Asks "May I write" with the target path before writing the string table (extract) or any report (brief, cultural-review, vo-pipeline script, rtl-check, qa)
• Extract writes only the diff of new entries, never a full replacement of the table
• Reports NOT ASSESSED instead of zero results when the code root or the string table is missing
• qa issues PASS, PASS WITH CONDITIONS, NOT ASSESSED or FAIL per locale, first match FAIL → NOT ASSESSED → PASS WITH CONDITIONS → PASS
• Ends with the Recommended Workflow chain / /gate-check release handoff

---

Coverage Notes

• scan with a resolved code root (findings with file paths and line numbers) is not separately tested; Case 6 covers the unresolved root.
• extract while freeze-status.md shows Status: ACTIVE (new keys appended to ## Post-Freeze Changes with a freeze-violation warning) is not tested.
• freeze (pre-freeze checklist and AskUserQuestion [A]/[B]), brief, vo-pipeline and rtl-check are not exercised by a dedicated case; qa is covered only for its NOT ASSESSED branch (Case 7).
• The qa gate note — a FAIL blocks release for that locale only — needs a live run with multiple locales to verify.