Gaik Sync

GAIK Sync — keep the Solution Wizard in step with gaik

The Solution Wizard (implementation_layer/solution_wizard/) drives PoC generation from four assets that mirror the gaik API. When gaik changes, these drift and the wizard silently produces wrong blueprints or PoCs that fail at runtime:

Operating principle (same as the wizard itself): Python detects, the agent decides. The scan is deterministic; mapping each finding to the right edit — and judging whether a change is intentional — is your job. Never blind-delete a finding.

This skill does not modify gaik. It only edits the four wizard assets above.

Mandatory approval gate (applies in BOTH modes — never skip)

Regardless of mode, the order is always scan → present findings → wait for approval → sync only what was approved → test. Concretely:

1. Always present the findings first. After the scan (and, in discovery mode, the diff reconstruction), show the user the full change table from Phase 3 before editing anything. This holds even in informed mode where the user already named the change, and even when there is only one finding.
2. Never edit a wizard asset until the user has approved it. The user may approve all findings, approve a subset, amend rows, or reject. Apply (Phase 4) only the approved rows; leave everything else untouched.
3. If the user approves nothing (or there are zero findings), stop after presenting — make no edits, run no sync, change no pin.
4. Only after applying the approved subset do you run the tests and re-scan (Phase 5). Tests run against the synced changes, not before approval.

Do not batch-apply, do not "fix while scanning", and do not assume approval from the fact that the user invoked the skill. Invoking the skill authorizes the scan and the proposal, not the edits.

Inputs

Run in one of two modes. Prefer informed mode when the user tells you what they changed — it is faster and avoids false positives.

• Informed mode — the user names the change ("I renamed model_provider to provider on LLMJudge", "I added a diarization option to Transcriber", "I added a new FormUnderstander component"). Treat that as the hypothesis and confirm it against gaik + the scan.
• Discovery mode — the user just says "sync the wizard" or "check what changed". Reconstruct the change set yourself from the git diff and the scan.

Phase 1 — Scan (deterministic backbone)

Always start here. From the repo root, after uv sync --all-extras (components swallow a missing optional dependency, so a missing extra makes a class silently absent and shows up as false removed drift):

uv run python .claude/skills/gaik-sync/scripts/audit_registry.py --json

This introspects the installed gaik and returns structured findings. Categories:

• version — installed gaik vs the wizard's last-validated pin (gaik_validated_version.txt). Informational; it is the trigger, not a defect.
• removed — a reference-card import no longer resolves (class gone or moved).
• api_drift — a construct kwarg or call method no longer exists on the gaik class.
• options — a card option name is not a real constructor parameter (often it moved to a method argument, or was renamed/removed).
• parity — a registry component has no reference card.
• new — a gaik subpackage no card references (a new component family, an internal helper to ignore, or an unrecognized public alias).

Read the human-readable report too for a quick overview:

uv run python .claude/skills/gaik-sync/scripts/audit_registry.py

The scan only sees what introspection exposes. It cannot see subsumes relationships, install_extra packaging, input/output_artifact_types, or selection semantics — those need the diff (Phase 2) and your reading of gaik source.

Phase 2 — Reconstruct the change set

Informed mode: start from what the user told you. For each named change, open the relevant gaik source under implementation_layer/src/gaik/ and the matching card/registry entry to confirm the exact new signature, option, or path.

Discovery mode: find what changed in gaik since the last validated point.

# What does the wizard consider its last-validated state?
cat implementation_layer/solution_wizard/gaik_validated_version.txt 2>/dev/null

# Local source changes (when gaik is edited in-repo):
git log --oneline -15 -- implementation_layer/src/gaik/
git diff HEAD~1 -- implementation_layer/src/gaik/

If gaik arrived as a dependency bump (no local source diff), the introspection scan in Phase 1 is your only signal — lean on it and read the installed source directly via the module paths in the findings.

For every scan finding, and every diff hunk, read the actual gaik class to establish ground truth before proposing an edit. Pay special attention to changes the scan can't detect on its own:

• a component now provides a capability internally → a new subsumes entry (so the wizard stops adding a redundant step);
• a new install_extra / pip extra → registry entry + pip_requirements will pick it up;
• changed input/output artifact types → registry *_artifact_types;
• a new option that should be auto-inferred from a blueprint field (e.g. human_review == yes) → SKILL.md Phase 5.

Phase 3 — Classify and propose (no edits yet)

Map every finding to a concrete edit and present a change table for approval. Use this exact shape (it mirrors the wizard's own Phase 11.1 change table):

| # | Finding | Category | File | Field / location | Current | Proposed | Confidence |
|---|---------|----------|------|------------------|---------|----------|------------|
| 1 | LLMJudge construct kwarg 'model_provider' gone | api_drift | component_reference_cards.json | LLMJudge.construct | model_provider= | provider= | high |
| 2 | parallel_transcriber subpackage untracked | new | gaik_component_registry.json + cards | new entry | (none) | add ParallelTranscriber | needs decision |

Rules for the table:

• One row per finding. Group obviously-related rows (a rename usually touches construct + call + an option + SKILL.md).
• For new findings, always ask whether it is a user-facing component to add, an internal helper to ignore, or a public alias of an already-registered component — do not assume. llm-style provider layers are usually internal. Approved aliases belong in ALIAS_SUBPACKAGES, mapped to their canonical package, and must not receive duplicate registry or card entries.
• For options findings, check whether the option moved to a method argument before deleting it from the card; the wizard may still need to document it, just not as a constructor option.
• Mark confidence. Anything below "high" gets an explicit question to the user before Phase 4.
• If a finding is an intentional gaik deprecation with no wizard-side equivalent, say so and propose removing the registry/card entry (and any SKILL.md reference).

STOP here and present the table. Do not proceed to Phase 4 until the user responds. Explicitly ask them to approve all rows, approve a subset (by number), amend, or reject. If they approve nothing, end the run cleanly with no edits.

Phase 4 — Apply (approved rows only — requires explicit approval from Phase 3)

Edit only the four wizard assets, only the approved rows:

• registries/gaik_component_registry.json — add/remove/modify entries; keep input_artifact_types, output_artifact_types, required_parameters, supported_providers, subsumes, install_extra correct.
• registries/component_reference_cards.json — fix import, construct, call, returns, options; add cards for newly-tracked components.
• SKILL.md (Phase 5/6, and Phase 4 schema constraints if the extraction contract changed) — selection rules, option inference, subsumption, provider/model consistency. For approved new software module findings, also check whether the Phase 5 module-first rule table (| Pattern | Module to try first |) needs a new row mapping the module's primary use-case pattern to its name. For approved new software module findings whose output_artifact_types is not structured_json (e.g. a report, audio, answer), also check whether Phase 2 Round 3 in SKILL.md has an explicit requirement-collection branch for that pattern — if not, add one describing what the wizard must ask the user about the target output (e.g. section titles, per-section instructions, and dependency relationships for a report module). For approved new software component findings, also check whether the Phase 5 Step 2 composition bullets (e.g. "Input is audio → Transcriber") need a new bullet for any input→output transformation the new component introduces that is not already covered.
• CLAUDE.md in the wizard dir — only if a schema/field_type constraint changed.

Keep edits surgical and in the existing JSON/markdown style. Do not reformat whole files.