Troubleshooting

Start with the specific failed step. The app checkout and the private voice home serve different purposes, so check which folder a message names.

Clone or marketplace access fails

The plugin repository is private. Confirm that your GitHub account has access and that Git or Claude Code is authenticated for it. The public website does not make the repository public or grant installation rights.

If you already have the app, keep local changes safe before pulling. Voice Forge's voice-home sync is separate from updating the app checkout.

A shortcut is missing

From the app checkout, preview its registration:

python3 scripts/build.py install --dry-run

Run install to add missing links, and start a new agent session. If you used --copy, refresh the copies after updates. Claude plugin installations use /voice-forge:vf-train, while linked Claude skills use /vf-train. Codex uses $vf-train.

An existing ordinary skill directory may be skipped. Inspect it before deliberately replacing it. Installer reference.

The wrong voice home or profile was selected

python3 ~/voice-forge/skills/voice-forge/scripts/vf.py home
python3 ~/voice-forge/skills/voice-forge/scripts/vf.py profiles

Check VOICE_FORGE_HOME, then the per-computer config, then the default folder. Name a profile explicitly if its brief overlaps another. One active profile plus base rules is the intended model.

Validation fails

python3 ~/voice-forge/skills/voice-forge/scripts/vf.py validate --profile explainer-en

Inspect the named field, ID or heading. Nonfiction needs exact section headings and order, status lines, required rule fields and approval dates. TODOs and adaptation markers must be resolved. Unknown sections can stay empty.

An old Brief / Rules / Never layout needs /vf-migrate. A derived proposal needs adaptation and approval before it passes. Fiction uses a free layout and rule-field validation. Profile reference and schema.

Analysis cannot read a source

Ask which pages or parts were accessible. Provide readable Markdown or plain text when the agent cannot extract a format. Do not accept confident findings about an unread file. The full record should document coverage gaps.

Several chapters of one project are not several independent works. If an analysis proposes a lesson from a local pattern, ask for its recurrence scope and counterexamples.

Sync is offline, unverified or conflicted

Check /vf-status. An offline commit can wait for the next connection. A public or unverified remote cannot receive a helper push. A conflict needs resolution before the agent changes more voice-home files.

Do not force push or overwrite history to clear a conflict. Setup can check the linked private repository and explain what remains unverified. Sync and privacy.

A valid profile still sounds wrong

Validation checks file structure. Review checks rule compliance. Neither proves fidelity. Use real rewrites and blind holdout comparisons, then refine the particular rules that fail.

An automatic check marked as a lead needs a scope and exception decision. A same-agent review is useful but must not be called independent.

Log a problem

/vf-feedback the agent counted two chapters as independent works; both belong to the same project

Feedback goes to your private voice home. Describe public issues without private source text. Read the full skill reference for exact behavior.