# Book Fix

> Generates or executes a remediation prompt for a book flagged YELLOW or RED by /book-audit, writing a fix-<book-slug>.md that enumerates defects with verbatim PDF source text and verification commands, then optionally executes the fixes to bring the book to GREEN.

- Skill: `joshuashepherd/book-fix` (Agent Skill)
- Install (CLI): `npx skillmds add joshuashepherd/book-fix`
- Raw SKILL.md: https://api.skillmd.com/api/skills/joshuashepherd/book-fix/raw
- Safety review: CAUTION (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML, Docs & Writing, Prompt Engineering, Technical Writing
- Tags: Book Audit, Content Restoration, Grep, Markdown, Pdf, Prompt Generation, Remediation
- Author: JoshuaShepherd (https://skillmd.com/u/joshuashepherd)
- Updated: 2026-08-22
- Page: https://skillmd.com/skills/joshuashepherd/book-fix

---


# Book Fix — Remediation Prompt Generator + Executor

## Purpose

Take the findings from a `/book-audit` and convert them into a one-shot, end-to-end remediation prompt that another agent (or this one) can execute to bring the book to GREEN. Or, if the user prefers, execute the fix in place.

The output prompt MUST follow the structure established by [fix-on-the-verge.md](../../../docs/build/prompts/fix-on-the-verge.md) and [fix-reframation.md](../../../docs/build/prompts/fix-reframation.md):

1. **Header** — RED/YELLOW status declared, rationale, what's distinctive about this book's defects.
2. **INPUTS** — PDF path, target MD files, scratch dirs, archive dir.
3. **OPERATING PRINCIPLES** — verbatim only, PDF is source of truth, no fabrication.
4. **ISSUES TO FIX** — numbered, each with: file path, problem, current (wrong) text, PDF source (correct) text inlined, fix instructions, verification grep commands.
5. **EXECUTION ORDER** — strict dependency-ordered sequence.
6. **ACCEPTANCE CRITERIA** — checkbox list of every condition that must hold post-fix.
7. **DELIVERABLES** — what the executing agent must return.
8. **OUT OF SCOPE** — explicitly excluded items (summaries, vector store re-upload, translations).

## Invocation

`$ARGUMENTS` should specify:

- **`<book-slug>`** — Required.
- **`--audit <path>`** — Path to the prior `/book-audit` report. Default: most recent file under `docs/build/audits/<book-slug>-*.md`.
- **`--mode <generate|execute|both>`** — Default: `generate` (write the prompt without executing).
  - `generate` — write `docs/build/prompts/fix-<book-slug>.md` and stop.
  - `execute` — read existing fix prompt and execute every issue.
  - `both` — generate and execute back-to-back.
- **`--archive-dir <path>`** — Where to pre-archive the current MD before edits. Default: `corpus/alan_hirsch/_archive/<book-slug>-<YYYY-MM-DD>-<reason>/`.

## Process

### Generate mode

1. **Read the audit report.** Extract every numbered Sample with its findings, severity, and suggested fix.
2. **Group findings by class.** The exemplar prompts use these stable issue groupings (renumber as needed for the new book):
   - **CRITICAL correctness** — fabricated content, rewritten paragraphs, placeholder text, content rewrites.
   - **Notes-chapter restoration** — missing footnote prefixes, mislabeled chapters, missing chapter blocks, fabricated quotations.
   - **Multi-paragraph blockquote continuation drops.**
   - **Alternate-line content drops** in long-form quotations.
   - **Heading hierarchy collapse** (book-wide pass).
   - **Footnote-syntax standardization** (bracketed `[N]`, caret `^N`, Markdown `[^N]`).
   - **Page-header / page-footer bleed.**
   - **Kerning artifacts** (letter-spaced caps, joined words).
   - **Stray spaces / italic markup loss.**
   - **Misplaced section dividers.**
   - **Frontmatter integrity** (canonical_title, opening_excerpt, content_sha256, word_count).
   - **Comprehensive un-audited-chapter sweep.**
3. **Inline verbatim PDF source text** for every CRITICAL fix. Run `grep` against the source PDF text to copy the exact original passage. This is non-negotiable — the executing agent cannot restore content it cannot see.
4. **Provide verification commands** for every issue using `grep -c`, `grep -nE`, or Python one-liners. Each issue must have a binary pass/fail check.
5. **Write the prompt** to `docs/build/prompts/fix-<book-slug>.md`.
6. **Render a summary** to the user listing every issue number with its one-line description.

### Execute mode

1. **Read the prompt.** Verify it exists at `docs/build/prompts/fix-<book-slug>.md`.
2. **Pre-archive** the current MD to `corpus/alan_hirsch/_archive/<book-slug>-<YYYY-MM-DD>-pre-fix/`.
3. **Extract PDF reference text** to `/tmp/<book-slug>-fix/source.txt`.
4. **Walk the issues in execution order** as specified by the prompt. For each:
   - Apply the fix using `Edit` or `Write` tools.
   - Run the verification command immediately after.
   - If verification fails, do **not** advance — investigate and re-apply.
5. **After all issues are fixed:**
   - Re-run universal sweeps: trailing whitespace, kerning artifacts, word-joining, page-header bleed.
   - Recompute frontmatter `content_sha256`, `word_count`, `char_count`, `estimated_reading_time` for every edited file.
   - Update `book.json` totals.
6. **Run final acceptance verification.** Walk every checkbox in the prompt's Acceptance Criteria; report PASS/FAIL per item.
7. **Recommend the next skill.** If all PASS, advance to `/book-frontmatter` (Phase 02 schema validation) or directly to `/book-ingest` (Phase 03).

## Operating Principles

1. **The PDF is the source of truth.** Every restoration must be character-faithful to the PDF.
2. **Inline verbatim source text in the prompt.** The executing agent cannot restore what it cannot see; do not write "look up the original passage" — copy it.
3. **Provide verification commands for every fix.** Every issue gets a `grep -c` or equivalent that returns 0 or 1, not "review the diff".
4. **Issue ordering matters.** Fabrication fixes first (so the body is correct before structural passes run), Notes rebuild before footnote-syntax standardization (so refs can match definitions), heading hierarchy book-wide before per-chapter spot fixes.
5. **No speculative restoration.** If the PDF is unclear, leave a `<!-- TODO: verify against print PDF p.NN -->` and document it in the deliverables. Do not invent text.
6. **Pre-archive every time.** The current MD may contain hand-edits; preserve them under `_archive/` before any sed/script run.

## Anti-patterns

- ❌ Writing a fix prompt without inlining the verbatim PDF source text for fabrication fixes.
- ❌ Issuing fixes in non-dependency order (e.g., footnote-syntax conversion before Notes-chapter rebuild).
- ❌ Running automated sweeps (sed across all files) before the critical correctness fixes — sweeps may collide with hand edits or paraphrase content the script can't distinguish.
- ❌ Marking the book GREEN without re-running `/book-audit` against the post-fix MD.

## References

- [docs/build/prompts/fix-on-the-verge.md](../../../docs/build/prompts/fix-on-the-verge.md) — RED-status exemplar with 20 issues.
- [docs/build/prompts/fix-reframation.md](../../../docs/build/prompts/fix-reframation.md) — RED-status exemplar with 17 issues, footnote-syntax pivot.
- [docs/build/prompts/fix-fast-forward-to-mission.md](../../../docs/build/prompts/fix-fast-forward-to-mission.md) — YELLOW-status exemplar with 13 issues.