StoryForge Quality System

Deutsche Version

Back to StoryForge Main Page

Overview

StoryForge checks text in three layers:

The checks are not an extra. A strong author profile alone does not keep books free of AI patterns. The gates are the second layer of protection.

The gates at a glance

For a combined check there are run_quality_gates(book_slug) (all available checkers of a book in one result), validate_book_structure and run_pre_export_gates (see Technical Details).

The GateResult

Checker tools return a uniform result, usually under the key gate:

When several gates are combined, FAIL beats WARN beats PASS.

Before Writing

Instead of many single read steps, an MCP tool delivers the data for a chapter as JSON. The principle behind it: data arrives as a brief, not as a prompt instruction.

Chapter Writing Brief

get_chapter_writing_brief(book_slug, chapter_slug) is the main source of chapter-writer. The brief contains, among other things, the chapter and POV character, the story-time anchor, the time grids of recent chapters, the closing paragraphs of recent drafts, the characters present with profile, knowledge and tactical, inventory and state of the POV character, book rules, callbacks, banned phrases, the simile counts of recent chapters and the litmus questions from plot/tone.md. The tonal guidance from plot/tone.md includes, besides the litmus questions, the banned patterns as well (tone_banned_patterns), split into enforceable patterns and plain advisory notes. The full list and the error handling are under Technical Details.

Each component is protected separately. If one fails, it appears in errors and the brief still arrives with the remaining data.

Series context: If the book belongs to a series, each character in the brief carries a series_evolution field with the state from the series tracker (end state in the previous book, plan for the current book, development of relationships). The field is always present and null when there is no series context. More: Series Workflow.

Tactical Setup Verifier

verify_tactical_setup checks combat and travel scenes against the optional tactical block in character frontmatter. It warns when a protected character is at the rear or at the front of the group, when no protector is positioned or when the lead position does not fit movement_lead. It always returns questions for the writer as a checklist. The rules and the schema are under Technical Details.

Pre-Scene Logic Audit

Before every scene, chapter-writer in scene mode prints an audit block into the chat before prose lands in draft.md (in chapter mode once before the chapter). It is the counterweight to inventions under context pressure: for each category the model names the source in one sentence. If the source is silent, the gap is named and asked about, not bridged.

Recent Chapter Timelines

get_recent_chapter_timelines(book_slug, n) returns the time grids of the last N chapters that are at least at revision level. That anchors the context to established times and not to drafts. The continuity brief, by contrast, contains the grids of all chapters.

POV snapshot after the chapter

When a chapter is closed at Review or Final, chapter-writer extracts the POV character's end state (inventory, clothing, injuries, altered states, perception limiters), proposes it and, after your confirmation, saves it with update_character_snapshot into the series database (table character_snapshots). The character file stays unchanged. Later briefs read the snapshot as the most reliable source and otherwise fall back on timeline and draft heuristics.

Review Brief and Continuity Brief

get_review_brief(book_slug, chapter_slug) bundles for chapter-reviewer, among other things, the time grid of the chapter and its predecessor, the canonical calendar entries, the travel matrix, the canon facts including changed facts, tonal rules from plot/tone.md, active book rules and open callbacks. Banned patterns without backticks come along as plain advisory notes (banned_prose_unenforced) and never count as passed. For memoir, consent warnings are added. The chapter draft itself is deliberately not included, it is the content under review.

get_continuity_brief(book_slug) bundles for continuity-checker the canonical calendar, the travel matrix, the canon facts, the character index and the time grids of all chapters. In large books canon facts, calendar and grids are capped by size. The *_truncated fields show whether something is missing, and the checker says so in its report.

On Save: the Hooks

Two PostToolUse hooks run after every Write, Edit and MultiEdit, and a third hook secures rules from the chat at PreCompact. Alongside them, a hook called snapshot_draft quietly captures versions of fiction drafts on every write and edit; it is not a checker and never blocks. Structure, severities, example messages, linter_mode and the snapshot mechanics are described under Technical Details. The overview:

In strict mode (default) a block finding of the prose hook is reported back to the model with exit code 2 after the write, and the model has to fix it. In warn mode findings are only printed. The mode is per book and set as linter_mode in the frontmatter of the book CLAUDE.md. It affects only the prose hook: the character hook does not read linter_mode and always exits with code 2 on frontmatter blockers.

Markup in book rules

For the hook only what is in backticks in the book's rules counts:

For book rules the manuscript checker is deliberately more tolerant than the hook: soft findings can bear false alarms because you decide, hard blockers cannot.

Rules Hygiene

Book rules live in the database. So that they really take effect, there is a check layer of tools and a skill:

The check uses the same pattern extractor as the manuscript checker. What it reports, the scanner would also silently lose:

The same idea applies to author discoveries: write_author_discovery with validate=True attaches warnings and the extracted patterns to the response. There are two further codes, mixed_positive_negative_italics and bold_title_unscannable. Style principles deliberately produce no gap warnings because they are not scanned. The check never blocks, it only makes things visible.

/storyforge:rules-audit [book-slug] runs this interactively: scan, table of findings, a decision per finding (apply suggestion, edit manually, mark as narrative, skip), apply with re-check and a report. The skill never changes a rule without your confirmation. For books with quotation marks instead of backticks, the migration runs first (see Technical Details), then rules-audit for the remaining format problems.

Chapter Reviewer: 33 Points

/storyforge:chapter-reviewer <book> <chapter> checks a chapter against 33 numbered points and nine sub-points. The data comes from the review brief. For memoir there is chapter-reviewer-memoir.

Plus these sub-points:

The plot logic rests on analyze_plot_logic, see Technical Details. For 20f the chapter needs a ## Promises section in its README. chapter-writer fills it at the transition to Review. For older books /storyforge:backfill-promises adds it afterwards.

Chapter 1: 13 extra points

For chapter 1 a list of 13 points in three groups runs first:

• Set the stage: orient the reader, set the tone, establish the genre
• Spotlight the protagonist: in their element, wants something, normal world, problem, theme seeded, internal conflict
• Reason to keep reading: strong first sentence, curiosity sparked, dread established, first domino falls by the end of the chapter

Load-bearing points are 4, 5, 9, 10 and 13. A FAIL there turns the overall verdict into FAIL.

Verdict

The verdict is PASS, WARN or FAIL:

• PASS: no critical findings, no AI-tell hits, all load-bearing chapter 1 points fine.
• WARN: recommended improvements, but nothing that prevents moving on after one targeted pass.
• FAIL: at least one critical finding, a hit from the banned list, a violation of 9b or a load-bearing chapter 1 point at FAIL.

The report names strengths, findings by weight (Critical, Recommended, Minor) and a suggestion for the next step, usually chapter-fixer. With the run, reviewer_pass_done is set in chapter.yaml so that next-step knows the progress.

Author Check

/storyforge:author-check <book> <chapter> is the positive counterpart to the reviewer and manuscript checker, which only report negatives. The skill checks whether the author's style principles that fit the book's genres actually occur in the draft, and compares dialogue share, fragment share, single-sentence paragraphs and sentence length with the quantitative targets in the profile (otherwise with general defaults). The findings are hints and block nothing. The principles come from study-author and backfill-style-principles, see Author Profiles.

Chapter Voice Harvest

/storyforge:chapter-voice-harvest <book-slug> [chapter-slug] evaluates the logged review decisions from your corrections and turns confirmed voice patterns into style principles in the author profile. It runs after the review (and after the fixer or scene rewriter), before the humanizer, for fiction and memoir alike. It is a recommended but self-skipping step: if no pending feedback is logged, it says so in one line and ends.

Logging: chapter-writer, chapter-reviewer, chapter-fixer, chapter-scene-rewriter, chapter-humanizer and chapter-proofreader log checked decisions with log_review_feedback. The reviewer logs only what it executes itself, not what it hands off to the fixer. The humanizer logs findings it reworked and findings it discarded or deliberately kept, not replacements you simply approved. The proofreader logs only passages you explicitly confirm as intentional. Duplicate entries are ignored.

Classification: Before a candidate is promoted, every pending entry is classified against a closed vocabulary of dimensions and directions (reference/craft/voice-dimensions.md); two of the dimensions apply to memoir only. This is not the voice-checker's 7/8-dimension scoring, which remains unchanged and runs independently.

Candidates: get_voice_candidates requires weighted evidence of at least 3 from at least 2 chapters, with these weights:

Opposite directions with overlapping scope are reported as a conflict, not as a candidate. The scope is the intersection of the genres of the evidence; empty means universal.

Decision: For each candidate you answer explicitly: Promote, Edit and promote, Already in profile, Keep watching or Discard. Only then does the skill write with write_author_discovery(section="style_principles") and a genre scope. Never into donts or recurring_tics, which feed the enforced banlist. Exception: donts only when you name a concrete phrase, and only for fiction.

Memoir: Memoir never stores raw text, only the classification (dimension, direction) and a one-sentence rule (at most 240 characters), without the names of real people from the book. Memoir feedback must already be classified when it is logged. Style principles from memoir books get genres="memoir" and no example; they apply only in the author's memoir books, not in their fiction books.

Your own edits: Only when you say so ("I changed the text") does get_self_edit_hunks read your changes to draft.md against the baseline, never automatically. This is fiction-only, and the baseline is valid per machine.

Technical details for the individual tools are under MCP Tools.

Chapter Humanizer: AI-Construction Scan

/storyforge:chapter-humanizer <book> <chapter> is the surgical remover of AI patterns. In the standard path it sits after chapter-reviewer and before chapter-proofreader. For each finding it makes a suggestion in the author's voice and writes to draft.md only after your approval.

Pre-scan: The tool scan_chapter_ai_tells searches by machine for catalog patterns, flagged vocabulary and author bans, applies the density rules per scene and measures dash density, repeated sentence openers (only from six in a row), invisible characters and rhythm. The result is a candidate list, not a verdict. The skill also reads the draft itself, because the tool does not recognize judgment patterns or literal versus figurative use.

Pass 1: elegant-abstraction patterns from section 11 of anti-ai-patterns.md, among others:

• count-and-editorialize fragments (One word.)
• sentence as projectile (the words landed)
• room as receiver (the silence held)
• economic metaphors (the word cost him)
• near-miss body language (did not quite become, from the second hit per scene)
• body-part agency and trust split (trust his face)
• backward negation loops and repeated statements of the same fact
• negation-assertion loops (It wasn't X. It was Y.)
• hedge words from 12 per 1,000 narrative words (at least 4 hits in the scene)
• verb substitution, synonym cycling and mechanically identical sentence openers

Pass 2: flagged vocabulary from section 1 of the same catalog, only in figurative use, plus the author's donts.

Dashes in narration are only a tell at high density. The humanizer brings the chapter under the limit (adjustable with em_dash_per_1k_limit in the profile) and varies the replacements: comma, colon, restructured sentence, deletion, a full stop for at most a third. Parentheses are excluded as a replacement.

Flow:

• The report is a numbered hit list, at most 20 hits per batch.
• You answer for example apply 1, 2 / skip 3 / 4: shorter. Without an explicit decision nothing is written.
• Every suggestion is checked against the bans with check_replacement_text beforehand and must not change facts.
• All approved changes go into the draft in a single write. Then the scan runs again and the skill reports the change in the measured values.
• At most two scan passes per session.
• On completion humanizer_pass_done is set in chapter.yaml.

The catalog pre-scan (pass 1 and pass 2) applies only to books written in English; for any other book language it returns only a warning, while author bans and tonal rules are still checked. Findings the humanizer reworked or discarded feed into the voice harvest as feedback; replacements you simply approved do not.

Humanizer and voice checker

Chapter Proofreader

/storyforge:chapter-proofreader checks spelling, grammar and punctuation in the book's language and explains in the author's mother tongue (native_language). It runs after the humanizer, for fiction and memoir. Only passages you explicitly confirm as intentional are logged as feedback.

Voice Checker (optional)

/storyforge:voice-checker <book> [chapter] returns an authenticity score from 0 to 100. It is not a mandatory step but an overall check, for example before export or for critical chapters.

First the vocabulary scan runs as a hard gate: if a word from the AI-tell list hits in the flagged sense, the skill stops and outputs only the hit list with WARN (isolated hits) or FAIL (dense hits). Only after rewriting and a clean scan does the full report follow.

The full report scores seven dimensions, eight for memoir:

1. vocabulary
2. sentence-length distribution (human text has high variance, five consecutive sentences of nearly equal length are flagged)
3. paragraph structure
4. dialogue authenticity
5. emotional expression (named or shown)
6. specificity
7. match with the author profile
8. (memoir only) memoir-typical AI tells: life-wisdom platitudes, "looking back" hinges, tidy lesson endings, hedging as humility, therapeutic reframing, explanation after the image

The verdict: PASS at a score of 70 or more, WARN from 50 to 69, FAIL below 50 or with systemic patterns that call for a rebuild.

Chapter Fixer

/storyforge:chapter-fixer closes the gap between "a checker found something" and "it is fixed". chapter-writer only appends and would damage an existing draft. The fixer reads the flagged passage and replaces exactly that with the Edit tool.

graph LR
    A["chapter-writer: draft.md"] --> B["chapter-reviewer"]
    B --> C{"Verdict?"}
    C -->|PASS| V["chapter-voice-harvest"]
    V --> D["chapter-humanizer"]
    C -->|FAIL or WARN| E["chapter-fixer"]
    E --> B
    D --> F["chapter-proofreader"]
    F --> G["manuscript-checker"]
    G --> H{"Gate?"}
    H -->|FAIL or WARN with chapter finding| E
    H -->|PASS| I["Export"]

Rules:

• Change only the flagged passage, invent nothing, keep the author's voice.
• Never apply blindly: every fix needs your approval (batch approval by shorthand is possible).
• At most 20 hits per batch and at most three fixer rounds per session.
• If findings are so dense that single patches would reconstruct a scene, the skill suggests chapter-scene-rewriter.
• Findings come from the reviewer or manuscript checker of the session, from your paste, or from a passage that violates a rule according to rules-audit.
• Memoir: anonymization_leak is a pre-publication blocker and excluded from batch approval, as is book_rule_violation.

Manuscript Checker

/storyforge:manuscript-checker <book> [--interactive] scans the whole book for problems that only show when reading from start to end. It runs at the end of the revision, after every chapter has gone through reviewer, humanizer and proofreader. For memoir there is manuscript-checker-memoir; each variant points to the other when the book category is wrong.

The tool scan_manuscript(book_slug) writes the report to research/manuscript-report.md and returns a gate: FAIL if there is a book_rule_violation finding whose rule documents no exception of its own. WARN for all other findings, PASS without findings.

Categories

Report order: first the meta findings book_rules_unreadable and callbacks_unreadable, then book rules, then the author bans (author_rule_violation, author_vocab_violation, writing_discovery_violation), then the catalog tier (global_shape_violation, ai_tell_violation), then anonymization leaks, plot holes, clichés, then the rest by weight. A finding already covered by a hard author hit produces no additional catalog warning on the same line.

The thresholds for density categories (for example filter words and adverbs) are fixed in code, the details are in the report.

Memoir categories

Only in manuscript-checker-memoir:

On its own, anonymization_leak raises the gate to WARN, not FAIL, but is marked in the headline as a privacy blocker. For memoir plot_hole runs only with causality_inversion.

Interactive mode

With --interactive the skill goes through the heavy findings one by one, shows hits with context, proposes replacements and asks: apply all, adjust individually, skip or quit. It respects the author's style principles and tics, so deliberate quirks are not "corrected". Questions with a period ("Who.") are a legitimate style choice in small doses. For each hit there are two options: convert to a question mark (default) or keep the period and pair it with a narrative beat.

Callbacks

You register callbacks with /storyforge:register-callback. For the callback status alone there is verify_callbacks(book_slug), without the whole scan.

Timeline Validator

validate_timeline_consistency(book_slug) compares the chapters' time anchors and relative time phrases in the text with the event calendar in plot/timeline.md. It is the batch counterpart to the time-anchor hook, useful after several chapters and before the revision, especially in discovery writing.

For each chapter with a parsable ## Chapter Timeline it derives the date for phrases such as yesterday, tomorrow, last week, last night, this morning, tonight or an hour ago and compares it with the chapter's event. Deviations of more than zero days are reported. Chapters without a parsable block are listed under missing_anchors. If plot/timeline.md is missing, calendar_built is false and there are no findings. The result is also stored under {book}/reports/timeline-validation.json.

Continuity Checker

/storyforge:continuity-checker <book> checks the whole book against:

• Timeline (plot/timeline.md): temporal consistency
• Travel matrix (world/setting.md): spatial consistency. Memoir has no matrix, spatial statements are checked for real-world plausibility.
• Canon facts (database, add_canon_fact): fact consistency, with a special eye on changed facts and chapters that still use the old version

Typical findings: a weekday that does not fit the timeline; a travel time shorter than in the matrix; an age that deviates from canon; a location description that drifts between chapters. The report is saved at research/continuity-report.md.

Reconstruction: If the timeline or travel matrix is missing, the skill proposes them from the drafts and writes them with the marker [RECONSTRUCTED] to plot/timeline.md and world/setting.md so you can verify them. This is the most common use for discovery writers. If calendar entries exist but were cut off by the size cap, the skill does not reconstruct, to avoid duplicates.

The tool get_current_story_anchor(book_slug, chapter_slug) returns the mapping of relative phrases to dates directly, see Technical Details.

Memoir Checks

Memoir books have two checks that do not exist for fiction.

Emotional Truth Pass

/storyforge:emotional-truth-prompt checks a chapter draft for gaps in felt experience, places where the text is smooth but the experience is missing. It runs after the draft and before chapter-reviewer-memoir. The skill works through seven dimensions and returns questions and revision hints, never rewritten prose:

Verdicts: PASS (continue to the review), DEEPEN (work the flagged dimensions, then a second pass) and REWRITE (structural revision). For fiction books the skill points to chapter-reviewer.

Memoir Ethics Gate

/storyforge:memoir-ethics-checker has two passes.

Consent: The tool check_memoir_consent rates each person in people/ by consent_status and person_category:

A missing or unknown person_category turns a PASS into a WARN. Valid values are public-figure, private-living-person, deceased and anonymized-or-composite.

Defamation risk in the text: The skill reads the drafts and searches for four patterns for every person (regardless of consent status):

The skill's verdict: EXPORT BLOCKED for a refused consent or a D4 finding, RESOLVE BEFORE EXPORT for WARN or D1 to D3, otherwise EXPORT CLEAR.

For memoir, export-engineer calls check_memoir_consent before the export. On FAIL it stops, on WARN it asks. The defamation scan belongs to the memoir-ethics-checker skill and does not run automatically.

Recommended Sequence

Before writing

chapter-writer loads the chapter writing brief and prints the pre-scene logic audit. For combat or travel scenes verify_tactical_setup runs.

While writing

The prose hook runs automatically on every Write and Edit.

After a draft

1. /storyforge:chapter-reviewer (memoir: emotional-truth-prompt first)
2. fix findings, with /storyforge:chapter-fixer if needed
3. optionally /storyforge:author-check
4. optionally /storyforge:chapter-voice-harvest (after the review and fixes, before the humanizer)
5. /storyforge:chapter-humanizer
6. /storyforge:chapter-proofreader
7. optionally /storyforge:voice-checker for critical chapters

Before the revision

1. validate_timeline_consistency
2. /storyforge:continuity-checker
3. /storyforge:manuscript-checker --interactive (memoir: manuscript-checker-memoir)

Before export

1. optionally /storyforge:sensitivity-reader for sensitive topics
2. memoir: /storyforge:memoir-ethics-checker
3. all chapters at Final
4. /storyforge:export-engineer

Troubleshooting

The hook blocks although the phrase is intended

Causes: the phrase is a backtick pattern in the book rules or in the author's donts or tics. Remove or change the entry. As an emergency measure, set linter_mode: warn in the frontmatter of the book CLAUDE.md. That applies to the whole book and cannot be set per pattern. See also Author Profiles.

The POV warning is too aggressive

The domain is listed in the character's knowledge block as none or layperson but should be competent. Move it there, or remove the knowledge block and the character is not checked. You can add your own domains as a file under reference/craft/knowledge-domains/.

The voice checker reports nothing but the text still sounds like AI

Usually the author profile is too vague, there are no bans in the writing discoveries, the writing was not scene by scene, or no work was analyzed with study-author. Sharpen the profile, see Author Profiles.

The manuscript checker reports hundreds of findings

That is normal for discovery books after the first draft and for long books. Concentrate on the heavy findings and leave the medium ones in the first pass.

The time-anchor warnings are too frequent

The warning is a checklist, not a blocker: if the derived date is right, ignore it. linter_mode: warn does not switch it off, because that mode only demotes blockers to notices, and the hook prints the findings in warn mode as well (up to 10 lines). The warnings disappear only when the chapter README has no parsable ## Chapter Timeline section with a start time, or when the text contains no relative time phrases.

The continuity checker reports a conflict that is none

Example: the chapter says "three days later", the timeline "two days later". Check whether a day was counted as intra-day. Record the semantics, for example with /storyforge:register-callback and a rule ("timeline days are calendar days, not 24-hour blocks"), so that it is in the book rules.

The voice harvest reports nothing to harvest

The log is empty. Entries are only created by checked decisions in the reviewer, fixer, rewriter or writer, and, when you say so, by your own edits. Write a few chapters through the review round before you expect anything from the voice harvest.

The catalog reports nothing in my non-English book

The global AI-tell catalog (anti-ai-patterns.md) applies only to books written in English, see Technical Details. Book rules, author bans, tics and tonal rules still apply regardless.

← Back to StoryForge Main Page