[AIT-311] Add Claude skill for translating examples to Swift, and an example translation

.claude/skills/translate-examples-to-swift/SKILL.md

@@ -0,0 +1,303 @@
+---
+name: translate-examples-to-swift
+description: Translates inline JavaScript example code to Swift
+---
+
+## Usage
+
+Invoke this skill with `/translate-examples-to-swift` followed by a description of what to translate.
+
+### Examples
+
+```
+/translate-examples-to-swift translate the JavaScript examples in src/pages/docs/ai-transport/streaming.mdx
+```
+
+```
+/translate-examples-to-swift translate all JavaScript code blocks in the src/pages/docs/messages/ directory
+```
+
+```
+/translate-examples-to-swift translate the code block at line 45 of src/pages/docs/channels/index.mdx
+```
+
+### What to specify
+
+- **File or directory**: Which documentation file(s) contain the examples to translate
+- **Scope** (optional): Specific code blocks if you don't want to translate all examples in a file
+
+---
+
+## Architecture Overview
+
+This skill uses a **three-phase architecture** with independent translation, verification, and assembly:
+
+1. **Translation phase**: Spawn one sub-agent per MDX file. Each translates examples, self-checks compilation (for iteration), inserts into MDX, and writes translation metadata JSON.
+
+2. **Verification phase**: Spawn one sub-agent per MDX file. Each reads Swift code from the MDX (source of truth), compiles in a fresh harness, assesses faithfulness, and writes verification results JSON.
+
+3. **Assembly phase**: Run `consolidate.sh` to merge JSONs and generate review HTML.
+
+**Key principle**: Verification reads from MDX, not from translation output. This ensures verification tests what actually ships.
+
+**Verify-only mode**: When translations already exist in MDX but no translation JSONs are available, you can skip the translation phase and run only verification + assembly. See the "Verify-only workflow" section below.
+
+**Always delegate**: Spawn a sub-agent for each file, even for single-file tasks. This keeps behavior consistent and context isolated.
+
+---
+
+## Orchestrator Constraints
+
+The orchestrator (you, when running this skill) coordinates subagents but does NOT directly modify:
+- MDX documentation files
+- Translation JSON files (`swift-translations/translations/*.json`)
+- Verification JSON files (`swift-translations/verifications/*.json`)
+
+All modifications to these files must go through the appropriate subagent. The orchestrator may:
+- Read files to understand state
+- Run validation commands
+- Run the consolidation script
+- Spawn and coordinate subagents
+- Report results to the user
+
+This separation ensures that all code changes are tested before being written, and all verification results reflect actual verification.
+
+---
+
+## Output Directory Structure
+
+All intermediate files go in `swift-translations/` at the repo root:
+
+```
+swift-translations/
+    harness-{filename}/       # Test harness per translation subagent
+    verify-{filename}/        # Test harness per verification subagent
+    translations/
+        {filename}.json       # One per MDX file
+    verifications/
+        {filename}.json       # One per MDX file
+    consolidated.json         # Merged data for review app (generated by script)
+    review.html               # Human review interface (generated by script)
+```
+
+The `{filename}` is derived from the MDX filename without path or extension:
+- `src/pages/docs/ai-transport/messaging/citations.mdx` → `citations`
+- `src/pages/docs/ai-transport/token-streaming/message-per-token.mdx` → `message-per-token`
+
+---
+
+## Workflow
+
+### Step 1: Spawn translation subagents
+
+For each MDX file to translate, spawn a translation subagent.
+
+**Get the prompt from the file** `.claude/skills/translate-examples-to-swift/prompts/translation-subagent.md`:
+
+1. Read the file
+2. Replace `{FILEPATH}` with the full path to the MDX file being translated
+3. Replace `{FILENAME}` with the MDX filename without path or extension
+4. Pass the result as the subagent prompt
+
+**Do not paraphrase or rewrite the prompt.** Use the file contents with only the placeholders replaced. Launch a general-purpose subagent with the resulting prompt.
+
+#### Validate translation output
+
+After each translation subagent completes, validate its JSON output:
+
+```bash
+npx ajv-cli validate \
+  -s .claude/skills/translate-examples-to-swift/schemas/translation.schema.json \
+  -d swift-translations/translations/{filename}.json
+```
+
+If validation fails, report the error.
+
+### Step 2: Spawn verification subagents
+
+After translation subagents complete, spawn verification subagents for each file that was translated.
+
+**Important**: Spawn a verification subagent for EVERY file that had a translation subagent, even if that file had no examples. This ensures 1:1 matching between translation and verification outputs, avoiding special-case handling in the consolidation phase.
+
+**Get the prompt from the file** `.claude/skills/translate-examples-to-swift/prompts/verification-subagent.md`:
+
+1. Read the file
+2. Replace `{FILEPATH}` with the full path to the MDX file being verified
+3. Replace `{FILENAME}` with the MDX filename without path or extension
+4. Pass the result as the subagent prompt
+
+**Do not paraphrase or rewrite the prompt.** Use the file contents with only the placeholders replaced. Launch a general-purpose subagent with the resulting prompt.
+
+#### Why independent verification?
+
+- **Fresh perspective**: The verifier has no memory of translation decisions, so it approaches the code without bias
+- **Catches copy-paste errors**: Ensures the code in documentation matches what was actually tested
+- **Validates harness comments**: Confirms the test harness comments are complete and usable
+- **Faithfulness check**: Compares translations against originals with fresh eyes
+
+#### Validate verification output
+
+After the verification subagent completes, validate its JSON output:
+
+```bash
+npx ajv-cli validate \
+  -s .claude/skills/translate-examples-to-swift/schemas/verification.schema.json \
+  -d swift-translations/verifications/{filename}.json
+```
+
+If validation fails, report the error.
+
+#### Handling verification results
+
+When the verification subagent returns:
+
+1. **All passed**: Proceed to Step 3 (generate review file)
+2. **Compilation failures or faithfulness concerns**:
+   - Report the failures to the user with details
+   - Ask if they want you to attempt a fix
+   - If yes, spawn a **new translation subagent** (or resume the original one) to fix the issue
+   - After the fix subagent completes, spawn a **new verification subagent** to re-verify
+   - Repeat until verification passes or the user decides to skip
+
+**Important**: The orchestrator must NEVER directly edit MDX files or verification JSON files. All changes to translations must go through a translation subagent. All verification results must come from a verification subagent.
+
+### Step 3: Generate review file
+
+Run the consolidation script to merge JSONs and generate the review HTML:
+
+```bash
+.claude/skills/translate-examples-to-swift/scripts/consolidate.sh
+```
+
+This reads from `swift-translations/translations/` and `swift-translations/verifications/`, then produces:
+- `swift-translations/consolidated.json` - merged data
+- `swift-translations/review.html` - human review interface
+
+The review HTML provides:
+- Side-by-side comparison of JavaScript and Swift code
+- Syntax highlighting
+- Translation notes and decisions (collapsible)
+- Test harness context (collapsible)
+- Verification results (compilation status, faithfulness rating)
+- Interactive review controls (approve/flag/skip with comments)
+- Export functionality for review summary
+
+### Step 4: Report back to the user
+
+Report back to the user, explaining:
+
+- any important decisions that were made, such as deviations from the JavaScript code
+- the verification results summary
+- any issues that require human attention
+- the location of the review file for human review
+
+Example:
+
+```
+Translation complete.
+
+## Summary
+- Files processed: 2
+- Examples translated: 5
+- Compilation: 4 passed, 1 failed
+
+## Review file
+Open the review file to examine translations:
+  swift-translations/review.html
+
+## Issues requiring attention
+- src/pages/docs/messages/updates-deletes.mdx:78 - Compilation failed: `updateSerial` property not found
+```
+
+---
+
+## Handling user feedback
+
+When the user reviews the generated review file and provides feedback:
+
+1. Spawn a **translation subagent** (or resume the original one) to make the requested changes
+   - The subagent will update the test harness, verify compilation, and update the MDX
+2. Spawn a **verification subagent** to independently verify the changes
+3. Regenerate the review file with updated data
+4. Report back to the user
+
+**Important**: The orchestrator must NEVER directly edit MDX files, translation JSON, or verification JSON. All file modifications must go through the appropriate subagent. This ensures:
+- Every change is tested before being written
+- The verification JSON always reflects actual verification results
+- There's a clear audit trail of what each agent did
+
+**This is not optional.** Any change to a translation—whether from user feedback, verification comments, or your own corrections—must go through the full verify-and-review cycle before being considered complete.
+
+---
+
+## Verify-only workflow
+
+Use this workflow when Swift translations already exist in the MDX files but no translation JSON files are available. This happens when:
+- Re-verifying translations from a previous session
+- Manual edits were made directly to MDX files
+- Translation JSON output was discarded or lost
+
+### Step 1: Spawn verification subagents
+
+Same as the normal workflow Step 2 — spawn a verification subagent for each MDX file. Use the prompt from `.claude/skills/translate-examples-to-swift/prompts/verification-subagent.md` with placeholders replaced.
+
+### Step 2: Generate translation stubs
+
+After verification subagents complete, generate stub translation JSONs from the verification data:
+
+```bash
+.claude/skills/translate-examples-to-swift/scripts/generate-translation-stubs.sh
+```
+
+This reads each verification JSON and creates a matching translation JSON with a "verify-only" info note. It skips files that already have a translation JSON, so it's safe to run even if some real translations exist.
+
+### Step 3: Run consolidation
+
+Run `consolidate.sh` as normal:
+
+```bash
+.claude/skills/translate-examples-to-swift/scripts/consolidate.sh
+```
+
+### Step 4: Report back
+
+Report as normal, but note that translation notes are unavailable since the translation phase was skipped. The review HTML will show a "verify-only" info note in place of translation decision notes.
+
+---
+
+### The verification invariant
+
+**Never output code that hasn't been verified.** This is the core principle of the skill:
+
+- Every Swift code block inserted into documentation must have passed `swift build` in a test harness
+- Every change to existing Swift code must be re-verified before the task is complete
+- The review file must always reflect the current state of the translations
+
+If you find yourself about to report completion without having verified recent changes, stop and run verification first.
+
+---
+
+## Scripts
+
+Scripts are in `.claude/skills/translate-examples-to-swift/scripts/`:
+
+- `consolidate.sh` - Merges translation and verification JSONs, validates, generates review HTML
+- `generate-translation-stubs.sh` - Generates stub translation JSONs from verification data (for verify-only mode)
+
+Review app scripts are in `.claude/skills/translate-examples-to-swift/review-app/`:
+
+- `generate-review.sh` - Generates review HTML from consolidated JSON (called by consolidate.sh)
+
+## JSON Schemas
+
+Schemas are in `.claude/skills/translate-examples-to-swift/schemas/`:
+
+- `translation.schema.json` - Translation sub-agent output (notes and metadata)
+- `verification.schema.json` - Verification sub-agent output (code, harness, results)
+- `consolidated.schema.json` - Final merged data for review app
+
+Validate with:
+
+```bash
+npx ajv-cli validate -s {schema} -d {data}
+```