| name | preset-skill-op-troubleshooting-migration |
| description | Bounded first-pass triage for preset problems; routes deeper runtime/update/migration questions elsewhere instead of guessing. |
| version | 1.0.0 |
| last_changed_at | 2026-07-19T00:00:00Z |
| related_files | ["tui/internal/preset/preset.go","tui/internal/tui/preset_editor.go","tui/internal/tui/app.go","tui/internal/tui/codex_pool_store.go","tui/internal/preset/preset_skill_router_test.go"] |
| maintenance | If you find stale or incorrect information here, use the lingtai-issue-report skill to assemble evidence and obtain per-issue human consent before filing an issue. Never include secrets, credentials, tokens, or private paths. |
Troubleshooting / migration triage
This child is intentionally bounded: it covers the handful of
preset-specific symptoms this skill tree can explain from its own evidence,
and routes everything else rather than guessing at runtime, update, or
migration internals it doesn't own.
In scope here
- "My saved preset didn't update after a TUI upgrade." Expected —
RefreshTemplates only rewrites templates/, never saved/. See
reference/operations/saved-presets/SKILL.md. If the user wants the new
template's changes, they re-create the saved preset from the refreshed
template.
- "A template I used before is gone." Check whether it was pruned by
RefreshTemplates because it's no longer in BuiltinPresets() (a
retired template) — see reference/operations/saved-presets/SKILL.md,
Bootstrap section. A saved clone of a retired template is untouched and
still loads.
- "Save is stuck / won't go through." Check
reference/operations/availability-save-gate/SKILL.md first — pending,
hard-blocked, and retryable-warned are three different states with
different next actions.
- "I edited the preset/pool file but the running agent didn't change."
Expected — see
reference/operations/activation-session-refresh/SKILL.md:
saving alone never switches a running session; an explicit refresh,
relaunch, or new service construction is required.
- "codex-pool file looks wrong / refuses my edit." See
reference/codex-pool/SKILL.md — check whether the pool is
model-classified (a models key, even {}) before assuming a flat edit
should have worked.
Out of scope — route, don't guess
- Deeper runtime questions (kernel adapter registration, request-scoped
failover behavior beyond what's cited in
reference/codex-pool/SKILL.md,
live provider request/response shapes) belong to kernel-side skills or
direct kernel source reading — do not extrapolate kernel internals from
TUI-side evidence.
- Update/upgrade mechanics (how a TUI version bump itself is delivered,
migration numbering,
tui/internal/migrate/) belong to the migration
package's own ANATOMY.md and ownership, not this preset skill tree.
- A preset that looks structurally fine but the provider still rejects
every request is a live operational issue, not a documentation gap —
point at
reference/operations/availability-save-gate/SKILL.md for how
to read the live probe's classification, but do not invent a root cause
this skill's evidence doesn't support.
When a question falls outside the "in scope" list above, say so explicitly
and point at the narrower, correctly-owned skill or source location instead
of speculating from preset-package evidence alone.
