Common sticking points
This collects the spots you commonly hit while writing a book. Find by symptom and read only the relevant item. For a symptom not here, copying the error message verbatim into Claude Code and asking is faster.
”command not found: git”
Section titled “”command not found: git””git isn’t installed. macOS: xcode-select --install. Linux and WSL2: sudo apt install -y git. After installing, check with git --version.
A chapter commit conflicts
Section titled “A chapter commit conflicts”Trying to commit several chapters at once sometimes conflicts. book-studio’s principle is one chapter, one commit. Committing chapters one at a time reduces conflicts and keeps rollback clean at the chapter level. If a conflict already happened, copy the error into Claude Code and ask “how do I resolve this conflict?”
Switching books
Section titled “Switching books”I’m writing a chapter in the wrong book
Section titled “I’m writing a chapter in the wrong book”The active book (active_slug) is pointing at a different book than you intended. Confirm the active book with “which book am I working on?” and move with “continue with book X.” It’s a spot where the active book sometimes gets confusing when running several.
Looking for a book not in the list
Section titled “Looking for a book not in the list”It’s a book not registered in books.json, or the slug has drifted. Check the registered books with “show me the book list.” If it’s a new book, register it again with “new book — with slug X.”
The chapter gate keeps failing
Section titled “The chapter gate keeps failing”The chapter’s AI-flavor score is over 61. Read the chapter and check whether the opening throws the result first, whether there are no concrete numbers or failure stories, and whether template phrases are baked in. The detailed way out is in when-ai-gets-stuck.
A contradiction got caught in the continuity report
Section titled “A contradiction got caught in the continuity report”continuity-check checked a chapter against the index and caught a setup mismatch. If it’s an intended change, update the index; if it’s a mistake, fix the chapter. See continuity.
Outputs
Section titled “Outputs”Markdown looks broken
Section titled “Markdown looks broken”A chapter file may have frontmatter or a code block closed wrong. Open it in a markdown viewer to see where it breaks, and say “fix the markdown in this chapter” to clean it up.
A chapter won’t commit to git
Section titled “A chapter won’t commit to git”_workspace/ is in .gitignore and drops out of git tracking. Chapter outputs aren’t meant to be committed in the first place. To back up a chapter separately, copy it outside _workspace/ or set up a separate git-tracked spot. The pre-commit hook blocking a _workspace/ commit is intended behavior.
If it still doesn’t resolve
Section titled “If it still doesn’t resolve”Open a GitHub issue or post in the team Slack. Write down three things together.
- Where you got stuck (which book, which chapter, which step)
- The full error message
- Environment info (operating system)