Troubleshooting
Based on the framework’s troubleshooting guide. Each row gives what to inspect within authorized scope, the next action, and the limit you should not cross.
| Symptom | Inspect | Next action and limit |
|---|---|---|
| Skill does not appear | Actual host and surface, enabled plugin source, manifest location, and the eight skills/<slug>/SKILL.md files |
Use the selection table; confirm the Kiyo source, not a built-in command. Don’t invent aliases or enable broad or global permissions |
| Resources missing after install | The installed entry and its references/kiyo/ tree; package identity; complete extraction |
Reinstall from the complete prepared package. Report the missing file and stop dependent Kiyo actions. Don’t fetch a guessed replacement |
| Core not loaded | Whether the Skill was actually selected and its bootstrap read | Explicit selection and automatic Core loading are separate. Select the Skill explicitly; propose a managed project block only if needed and authorized |
| Wrong workflow | Your intent, the selected Skill, the allowed mutation | Review and explanation stay read-only; fixes need Implement intent. “Take a look” is not write permission |
| Memory is stale | The canonical index, record type, scope, evidence, last_verified |
Use Memory check; sync only authorized observation deltas. Code conflicting with an approved decision is drift, not permission to revise it |
| Version unsupported or unknown | Actual host version, help, and extension metadata | One observed version does not establish a minimum. Keep NOT_TESTED or UNKNOWN; don’t force an upgrade or assume CLI success covers the IDE |
| Codex IDE cannot install Kiyo | Official native-plugin support | UNSUPPORTED, not a transient failure; no fallback has been approved |
| Validation warns or fails | The exact diagnostic and candidate bytes | Claude strict validation fails for the missing version and author; Codex public ingestion lacks version, author, and developerName. These are owner inputs; don’t fill in fake values |
| Host reports version 1.0.0 | Manifest version versus host-derived metadata | Codex’s fallback is not a Kiyo release |
| Tests cannot run | The inspected command, environment, target | BLOCKED or NOT_RUN with a reason. A missing environment is not NOT_APPLICABLE or PASS. Don’t use production or install tools implicitly |
| Policy or host denies an action | Actual authority, scope, prohibition | Preserve the denial; request an authorized decision where applicable. Don’t change policy or native settings to pass the task |
Host runs its own /init or /review |
Which command was invoked | Use the Kiyo-qualified selector for your host |
| Two Memory stores | Declared locators and directories | Decide which store is canonical; Kiyo won’t merge or pick one by timestamp |
Framework static test fails with a missing kiyo-compass-*.zip |
The default inventory in the framework repository | Pass --inventory docs/evidence/packaging/artifact-inventory-axiom-rename.json --archives dist/archives (see Testing strategy) |
Reporting an issue
Section titled “Reporting an issue”A useful report contains:
- the target and the observed host and plugin version (or Unknown);
- the package source and the install method and scope;
- the sanitized exact error;
- the selected Skill;
- expected versus observed behavior;
- the resource paths you inspected.
Include actual evidence only. Redact sensitive values. Never attach credentials, environment dumps, or raw private logs. Do not delete a whole cache or instruction file as a generic fix.
Issues can be filed on the framework repository.