--- name: prose-mechanics description: "Use when auditing prose at the sentence level on stabilized drafts. Trigger on: 'audit prose', 'active voice', 'sentence variance', 'passive voice pass', 'parallel structure check', 'readability audit', 'prose mechanics', or sentence-level diagnostic work on fiction or nonfiction." --- # Prose Mechanics Diagnostic audits for sentence-level prose quality on near-final drafts. Each audit is a focused pass that produces a flagged-issues report; the author reviews and applies fixes before moving to the next audit. Works for fiction or nonfiction. ## Session Continuity Audit work is iterative across multiple sessions. Claude has no memory between them, so the audit tracker is your persistent state. - **At session start:** Read `audit-tracker.md` in the project directory (copy from `assets/audit-tracker-template.md` if it doesn't exist). Check which audits have run on which chapters and what's still outstanding. - **At session end:** Update the tracker with what was audited, what was flagged, and what was resolved. Note the stopping point. - **Surface unresolved questions:** If prior audits flagged issues the author hasn't addressed, list them at session start so the user can decide what to take on. ## Core Concept Audits are diagnostics, not edits. Each pass scans for one specific class of failure, produces a list of flagged passages, and stops. The author—not the audit—decides whether each flag is a real problem and how to fix it. ## When to Use This skill is for: - ✅ Sentence-level audits on finished or near-finished drafts (fiction or nonfiction) - ✅ Final polish before submission, query, or publication - ✅ Catching the mechanical failures that survive developmental editing - ✅ Complementing `fiction-workshop` or `narrative-nonfiction` work after structural editing is done ## When NOT to Use This skill is NOT for: - ❌ Early drafting—audits are for revision, not generation - ❌ Developmental editing tasks—use `fiction-workshop` or `narrative-nonfiction` instead - ❌ Manuscripts that haven't stabilized structurally yet (you'll audit prose that's about to be cut) - ❌ Single scenes or short passages where eyeballing is faster than running a pass - ❌ Heavy stylistic departures (e.g., experimental prose) where the audits' assumptions don't hold ## Audit Passes Run audits **one at a time, in order**. Order matters because earlier audits change what later audits flag. Recommended sequence: frequency-family first (they inform the crutch-words config), mechanical passes next, semantic passes last (judgment-expensive; don't run on prose about to be reworked). | # | Audit | Class | Invocation | Catches | |---|-------|-------|------------|---------| | 1 | Active/Passive | hybrid | "Run active/passive audit on..." | Unjustified passive, hidden agency | | 2 | Parallel Structure | semantic | "Run parallel-structure audit on..." | Broken grammatical parallels | | 3 | Sentence Variance (file: `sentence-length-variance.md`) | deterministic | "Run sentence-variance audit on..." | Flat rhythm, narrow length bands | | 4 | Readability (file: `accessibility-audit.md`) | deterministic | "Run readability audit on..." | Grade-level spikes, paragraph bloat | | 5 | Echoes | deterministic | "Run echoes audit on..." | Word repeated within 100 words | | 6 | Frequency | deterministic | "Run frequency audit on..." | Manuscript-wide word overuse | | 7 | Crutch Words | deterministic | "Run crutch-words audit on..." | Author-specific overused words | | 8 | Filter Words | deterministic | "Run filter-words audit on..." | felt/saw/heard/realized/noticed/watched | | 9 | Adverb Audit | deterministic | "Run adverb audit on..." | -ly density, dialogue vs. narration | | 10 | Dialogue Tags | hybrid | "Run dialogue-tags audit on..." | Said-bookisms, adverb-modified tags | | 11 | Sticky Sentences | deterministic | "Run sticky-sentences audit on..." | Glue-word density | | 12 | Sentence Starters | deterministic | "Run sentence-starters audit on..." | Repeated opener patterns | | 13 | Tense Consistency | hybrid | "Run tense-consistency audit on..." | Unintentional tense flips | | 14 | Invented-Term Consistency | deterministic | "Run invented-term-consistency audit on..." | Capitalization/spelling drift | | 15 | Clichés | hybrid | "Run cliches audit on..." | Well-worn phrases | | 16 | Pronoun Clarity | semantic | "Run pronoun-clarity audit on..." | Ambiguous antecedents | | 17 | Show vs. Tell | semantic | "Run show-vs-tell audit on..." | Named vs. dramatized emotion | | 18 | POV Consistency | semantic | "Run pov-consistency audit on..." | Head-hopping, knowledge violations | | 19 | AI-Isms | hybrid | "Run ai-isms audit on..." | Cross-lists `avoid-ai-writing` | Load only the reference file matching the currently invoked audit. Do not preload all references at session start — it wastes context budget. If switching audits mid-session, load the new reference file and treat the prior one as out-of-scope. ## Finding Format Every audit emits findings conforming to `../../references/finding-schema.json`: `audit`, `technique`, `severity` (note/suggestion/warning), `location` (file/line/quote), `issue`, `exemplar` (optional), `confidence` (deterministic/judgment). Render findings grouped by severity, resolving any `exemplar` reference against `references/exemplars/.md`. ## Engine Hook Before running any audit, check `command -v scriptorium`. If it succeeds: - **Deterministic audits:** run `scriptorium prose audit ` and treat its JSON as authoritative — do not re-derive findings by hand. - **Hybrid audits:** run `scriptorium prose prepare ` to get code-detected candidates, judge each per that audit's reference file, then `scriptorium prose submit-findings --findings-file `. - **Semantic audits:** run `scriptorium prose prepare ` (no candidates — pure judgment over the raw chapter), judge per the embedded instructions, then `submit-findings`. If `scriptorium` is unavailable, perform the audit conversationally using the reference file's detection rules directly — this is the audit's full specification, not an abbreviated fallback. ## Workflow For each audit: 1. **Scope:** Confirm which chapter(s) or passage(s) to audit. Audit one chapter at a time unless the user asks for broader scope. 2. **Run the pass:** Read the prose looking for the specific patterns named in the relevant reference file. Do **not** look for other classes of issue—keep the lens narrow. 3. **Produce a flagged-issues report:** For each flagged passage, output: - File and approximate location - The flagged text (short excerpt) - Why it was flagged (which detection pattern matched) - A suggested fix or two—not a mandate, just options 4. **Stop. Wait for author review.** Do not apply fixes automatically. The author decides which flags are real and which are stylistic choices. 5. **Apply approved fixes:** Use `str_replace` for surgical edits on the flags the author confirms. Skip the rest without comment. 6. **Update the tracker:** Note which audit ran, on which chapter, what was flagged, and what was resolved. 7. **Move to the next audit.** Repeat. ## Common Mistakes | Mistake | Why It Happens | Fix | |---------|---------------|-----| | **Running all audits simultaneously** | Wanting to be thorough in one pass | Each audit has a different lens. Stacked, they produce a noise-flood the author can't act on. One pass at a time. | | **Applying fixes mechanically** | Treating flags as instructions, not diagnostics | Every flag needs a judgment call. A flagged passive may be the right passive. Surface the flag; let the author choose. | | **Treating audits as line edits** | Conflating diagnostics with revision | Audits identify candidate issues; line editing is the craft of resolving them. Run the audit, then do the line edit—not both at once. | | **Auditing unstable drafts** | "Polish as I go" instinct | If chapters are still being cut or reordered, audited prose is wasted work. Wait for structural stability. | | **Skipping the report step** | Wanting to be efficient by fixing in place | The report is the deliverable. It teaches the author to see the pattern themselves, which is the long-term value of the audit. | | **Running audits out of order** | Convenience or user request | Each audit changes what the next will flag. If the user insists on a different order, note that downstream audits may need a re-run. | | **Auditing during developmental work** | Mistaking line-mechanical issues for structural ones | Prose mechanics are downstream of structure. If the chapter's purpose isn't clear, the prose isn't the problem. Use the developmental skills first. | ## Self-Check: Is This Working? Use these checkpoints to verify you're running audits correctly. **Before starting an audit:** - [ ] Is the manuscript structurally stable (no pending major cuts or reorders)? - [ ] Have prior developmental and character-work passes been completed? - [ ] Is the audit scope clearly defined (which chapter, which passages)? **During an audit:** - [ ] Are you using only the patterns from the relevant reference file? - [ ] Are you producing a flagged-issues report rather than applying fixes directly? - [ ] Are you ignoring issues outside the audit's scope, even when you notice them? **After producing the report:** - [ ] Can the author act on each flag without re-reading the audit reference? - [ ] Did you include a short excerpt and a suggested fix for each flag? - [ ] Did you stop and wait for review rather than continuing to the next audit? **After applying fixes:** - [ ] Did you use `str_replace` for surgical changes only? - [ ] Did you skip the flags the author didn't confirm, without re-raising them? - [ ] Did you update the tracker before ending the session? **Before moving to the next audit:** - [ ] Is the current audit's flags fully resolved (applied, dismissed, or deferred with a note)? - [ ] Have you confirmed the author wants to proceed? If you answered "no" to any checkpoint, stop and resolve it before continuing. ## Stopping Points Each audit has a defined end. Stop at it. Do not auto-advance to the next audit, do not silently expand the audit's lens, do not apply fixes without explicit author confirmation. | Tool / Phase | Stop when... | Then | |--------------|--------------|------| | **Active/Passive audit** | Flagged-issues report for the requested scope is delivered | Wait for author review. Do not apply fixes. Do not start the next audit. | | **Parallel Structure audit** | Flagged-issues report is delivered | Same as above. Do not roll forward into variance. | | **Sentence Length Variance audit** | Flagged-issues report is delivered (with std-dev numbers and flagged runs) | Wait. Variance fixes ripple, so confirmation matters. | | **Readability audit** | Flagged-issues report is delivered (with FK grade, paragraph-length, jargon flags) | Wait. Don't pivot into developmental editing if structural concerns surface—surface them and stop. | | **Approved-fixes pass** | All author-confirmed flags resolved via `str_replace` | Update the tracker. Do not start the next audit without confirmation. | | **Audit sequence** | Author defers, OR a later audit reveals the manuscript needs structural work | Stop. Note in tracker. Recommend the author switch to `fiction-workshop` or `narrative-nonfiction` for the structural pass. | | **Session** | Stopping point reached or context window is filling | Update `audit-tracker.md`; write a `sessions/` note; stop. | If the author explicitly asks you to continue past a stopping point (e.g., "just apply the obvious fixes"), fine—but name which flags you're acting on and which you're skipping, so the scope shift is visible. ## Quick Reference Commands | Need | Command | |------|---------| | Start audit sequence | "Run the prose-mechanics audits on [chapter]" | | Active/passive only | "Run active/passive audit on [chapter]" | | Parallel structure only | "Run parallel-structure audit on [chapter]" | | Sentence variance only | "Run sentence-variance audit on [chapter]" | | Readability only | "Run readability audit on [chapter]" | | Check audit status | "What audits have run on [chapter]?" | --- ## Files - `references/active-passive-audit.md` - Voice and agency at the sentence level - `references/parallel-structure-audit.md` - Grammatical parallelism in lists, comparisons, series - `references/sentence-length-variance.md` - Rhythm diagnostics for paragraphs - `references/accessibility-audit.md` - Readability scoring and structural accessibility - `assets/audit-tracker-template.md` - Per-project tracker for audit runs and findings