Symptom: The /storyforge:... commands are missing, or skills report that no MCP tools are reachable.
claude plugin list.~/.storyforge/venv/bin/python3 (Windows: %USERPROFILE%\.storyforge\venv\Scripts\python.exe)./storyforge:setup
The setup recreates the virtual environment, installs dependencies and tests the MCP import. Restart Claude Code afterwards.
This is usually the Microsoft Store placeholder (exit code 49 with no output). /storyforge:setup therefore tries py -3 and known install paths. See Installation.
Cause: The hook runs after the write. On a block-level finding it exits with code 2 and feeds the message back to Claude, which has to correct the text. The message names file, line and source. Blockers come from four sources:
list_book_rules, change or delete with update_book_rule.delete_discovery.Ch 5, callback, as established and similar). Reword the sentence.plot/tone.md. Change or remove the pattern there.For a book-rule hit with a limit (max N per chapter), the hook reports the number of hits and the scaled limit for the current draft length. Shorten the passage or wait until the draft is longer.
Emergency: Set linter_mode: warn in the frontmatter of the book's CLAUDE.md. Blockers are then only reported. See Configuration.
Symptom: A don't or recurring tic from the author profile does not block on write, even though it is in the database.
Cause: The hook finds no author for the book. It first looks for the line - **Author:** Name in the Book Facts section of the CLAUDE.md, then the author: field in the YAML frontmatter of the README.md. For books created through /storyforge:new-book, create_book_structure always writes that field — a missing CLAUDE.md line alone is no longer a problem there. Check instead whether the author: field in the README itself is missing or empty, for example in very old books or after a manual edit of the README. Without a resolvable author slug the hook silently returns no findings.
Fill in the author slug in the README (or the line in the CLAUDE.md), then the banlist takes effect on the next write.
The warning appears for every relative time phrase (yesterday, tomorrow, an hour ago) and names the resulting date. It is a checklist and never blocks. If the stated date is right, ignore it. Individual warnings cannot be switched off.
If the chapter README has no ## Chapter Timeline section, there is no time-anchor check.
The hook warns when specialist vocabulary of a domain appears that is none or layperson for the POV character.
competent or expert in the character's knowledge block.knowledge block, then this character is not checked.reference/craft/knowledge-domains/. The file name is the domain name.Possible causes: There is no or only a thin author profile, the author's banlist is empty, or no works of your own were analysed.
/storyforge:create-author
/storyforge:study-author ~/my-previous-book.epub
/storyforge:chapter-humanizer my-book chapter-01
/storyforge:voice-checker my-book chapter-01
study-author derives the style from your texts. chapter-humanizer finds AI constructions in the chapter and proposes alternatives. voice-checker scores the text across seven dimensions (eight for memoir) and compares it with the author profile.
Cause: Canon facts or timeline are not maintained.
/storyforge:continuity-checker my-book
The skill loads calendar, travel matrix, canon and all chapter time grids through get_continuity_brief and lists the contradictions. Record new facts with add_canon_fact.
Cause: The rule was not registered by one of the routes that store it permanently.
Write it with a prefix, for example:
Regel: No flashbacks before chapter 5.
Before compaction, the PreCompact hook stores lines with Regel: (also Rule:), Workflow: and Callback:. Note:
CLAUDE.md exists.Alternatively use /storyforge:register-callback or append_book_rule. Check with list_book_rules(book_slug).
Symptom: list_books returns nothing although projects exist, or a status does not fit.
Call the tool rebuild_state (for example by asking "rebuild the state cache"). It re-reads all books and authors from the file system. Also check that paths.content_root in the config points to the right directory.
| Message | Fix |
|---|---|
| Gate "All chapters Final" fails | Set all chapters to Final, or export an ARC with --arc. |
Front matter missing or contains [Author Name] |
Fill in export/front-matter.md, set the author field. |
| Review comments in the draft | Resolve or delete the lines with {review_handle}:. |
Memoir: consent_status: refused |
Rewrite the passage, anonymize the person or clarify consent, then run /storyforge:memoir-ethics-checker. |
pandoc or ebook-convert not found |
Install the program and add it to the PATH. |
create_book_structure refuses the book slugSymptom: Creating a series volume with series_slug returns Book slug '{slug}' already exists at {path}. Choose a different title or resolve the collision first.
Cause: A book with the same title slug already sits at projects/{slug} or in another series at series/{series}/{slug}. Without this refusal, a later call to add_book_to_series would find the wrong, pre-existing book and overwrite its README.
Check: The path is in the message. Alternatively look for projects/{slug} and series/*/{slug} under content_root. If a book that does not belong to the new series volume is there, that is the collision.
Fix: Pick a different title for the new series volume, or resolve the collision first, for example by renaming the existing standalone book or moving it into the series yourself.
analyze_plot_logic reports Chekhov elements without payoffCause: The ## Promises sections of the chapters are incomplete or missing. Run /storyforge:backfill-promises <book-slug> once and start the check again.
Cause: The global AI-tell catalog (reference/craft/anti-ai-patterns.md) only applies to books whose language (the language field in the README frontmatter) is English. For any other language, scan_chapter_ai_tells and check_replacement_text return a warning instead of catalog hits, because no catalog exists for that language.
Book rules, author bans (donts, recurring_tics) and the tone rules from plot/tone.md keep working regardless. More on this: Technical Details.
Symptom: /storyforge:chapter-voice-harvest reports in one line that there is nothing to harvest and ends.
Cause: The log (review_feedback) is empty or has no classifiable candidates. Entries are only created by verified decisions from the writer, reviewer, fixer and rewriter, plus your own edits via get_self_edit_hunks when you say you made them. Humanizer and proofreader decisions are logged too, but only feed into candidate building starting with the next chapter. For memoir books, an entry needs a classification (dimension, direction, a one-sentence rule) already at logging time; without it, no candidate is formed.
get_self_edit_hunks reports no baselineStatus no_baseline or stale: This chapter has no reliable comparison baseline. The baseline is only created by Claude's own writes with the plugin active, and it applies per machine — text changed on another machine, by a shell command or by git would otherwise show up incorrectly as your own edit. Call refresh_draft_baseline(book_slug, chapter_slug) to set the current version as the new baseline; changes made before that point can no longer be attributed afterward.
Status memoir_unsupported: There is no comparison baseline for memoir chapters, so the tool never returns hits.
get_chapter_writing_brief reports errors in single componentsThat is not a crash. The brief arrives with the remaining data, the faulty parts are listed in the field errors. Most common cause: world/setting.md or plot/timeline.md does not exist yet.