<!-- AUTO-GENERATED from SKILL.md.tmpl — do not edit directly --> <!-- Regenerate: bun run gen:skill-docs -->

Telemetry (run last)

After workflow completion, log telemetry with ONE command. OUTCOME is success/error/abort/unknown; SESSION_ID and TEL_START are the values the preamble's skill-start output echoed. It also drains the artifacts-sync queue (the former skill-end sync step — do not run gstack-brain-sync separately).

PLAN MODE EXCEPTION — ALWAYS RUN: This writes telemetry to $GSTACK_STATE_ROOT/analytics/, matching preamble analytics writes.

~/.claude/skills/gstack/bin/gstack-skill-end --skill "ios-sync" --outcome OUTCOME \
  --session-id "SESSION_ID" --tel-start "TEL_START" --used-browse USED_BROWSE \
  --error-message "ERROR_MESSAGE" --failed-step "FAILED_STEP" 2>/dev/null || true

Replace OUTCOME and USED_BROWSE (yes/no) before running; substitute SESSION_ID/TEL_START from the skill-start echoes. ERROR_MESSAGE/FAILED_STEP are "" unless outcome is error. If the command is missing (stale install), skip telemetry — it never blocks the workflow.

Resync the iOS debug bridge

After /ios-qa is installed in an app, the user may:

1. Add new @Observable classes or properties that need accessor coverage.
2. Upgrade gstack to a newer version with hardening fixes.
3. Move the // @Snapshotable generator marker comment to a different field.

This skill regenerates the relevant artifacts in place.

Templates live in upstream gstack. The installed gstack-ios-qa-regen launcher resolves its own gstack root and copies only the supported bridge files from ios-qa/templates/.

Phase 1: Detect installed version

1. Read <app>/DebugBridgeGenerated/.gstack-version (written by /ios-qa during install). If missing, treat the install as "unknown old version".
2. Read upstream version from $GSTACK_ROOT/VERSION.
3. If versions match AND no new @Observable classes were added, exit early with "already up to date".

Phase 2: Regenerate codegen output

Run the deterministic regenerator once. --app-source is the directory the accessor scanner should inspect; --bridge-dir is the local Swift package that the app links in Debug builds:

~/.claude/skills/gstack/bin/gstack-ios-qa-regen \
  --app-source "$APP_SOURCE_DIR" \
  --bridge-dir "$APP_SOURCE_DIR/DebugBridge"

The command removes only the known obsolete generated files from the former flat DebugBridgeGenerated/ layout before emitting the current accessor. Generation accepts file-scope observable classes and JSON-native scalar, array, String-keyed dictionary, and Optional field types. It rejects custom types, implicitly unwrapped Optionals, nested observable classes, and duplicate snapshot keys before writing a completion marker.

The composite-hash cache key handles whether anything actually needs regenerating; if Swift version, generator git rev, lockfile, source content, and platform triple all match the cache, this is a ~50ms no-op.

Phase 3: Review the generated diff

1. Review changes under <app>/DebugBridge/ and <app>/DebugBridgeGenerated/StateAccessor.swift.
2. Confirm the command did not modify the app's handwritten Swift files.
3. Keep app-specific wiring in the app target; canonical bridge package files are regenerated from upstream and should not be hand-edited.

Phase 4: Verify

1. swift build succeeds against the app's package.
2. xcodebuild -scheme <SchemeName> succeeds.
3. Re-launch the app on the device; daemon connects + rotates token.
4. GET /state/snapshot returns the new accessor schema hash.

Failure modes