socratic-method

Socratic method: text audit with visual companion

Overview

Audit a multi-section text on three axes (duplication, format, flow), then render every finding as a visual before/after page the author can review at a glance. Two principles carry the whole skill:

1. The author's words are sacred. You find problems and rearrange sentences; you never write the author's prose.
2. The companion design is fixed. Copy the <style> block from companion-template.html verbatim. Do not invent palettes, fonts, layouts, or components; the template is the design. example-companion.html is a finished page from a real audit: read it before building and match its structure and density; its content belongs to one project, so copy nothing from it.

When to use

• A document set has grown by accretion and ideas repeat across sections
• The author rejects prose-only audit reports ("I can't see what you are telling me")
• You need to check whether a guide/tutorial teaches in the right order
• NOT for single short texts, and NOT for line-editing grammar or diction. In scope from three sections (two seams) up, whether the sections live in one file or several; a multi-file set is audited as one document in reading order, with one chain across the whole set

Workflow

1. Inventory. Read every section. Record word counts per section (headings and footnotes excluded); note which formatting patterns the document already uses (run-ins, bullets, tables); those are house style to extend, not replace.

2. Duplication scan (findings D1..Dn). Same idea in two or more places: pick one owning home per concept; every other occurrence becomes a trim or a cross-reference. Evidence is verbatim quotes with file:line (or section:paragraph) references, duplicated phrases marked. Classify each finding by decision type, not severity:

chip	meaning
mechanical trim	pure deletion, no rewriting; apply without asking
judgment call	defensible either way; the author decides
leave as is	checked and cleared; stays as written (includes real repetition serving two different arguments)
fixed by Fn/Sn	another finding resolves it for free

leave as is is a verdict, not a suggestion. An occurrence cleared because it serves a different argument is not also offered to the author as an optional cut; offering the cut anyway reopens a decision the audit already made.

Also record deliberate non-findings (repetition you checked and cleared), so the author knows it was looked at: render them as one final card in the duplication section, idx —, chip leave as is, one line per item. The cleared card belongs to the duplication section only; a format or flow section with zero findings says so in its secsub line instead of growing a card.

3. Format upgrades (F1..Fn). Hunt walls of prose hiding several rules. Fixes, in order of preference: paragraph split; bold run-in lead; bullets; table (last resort; do not over-table). Hard rules:

• Run-in text is lifted from an existing sentence in the paragraph, never coined. If headings already state each section's one rule, run-ins may be unnecessary; do not manufacture findings.
• Bullets come from enumerations already inside a sentence, items kept verbatim; dropping conjunctions and splice words is allowed, disclosed in the card's note.
• Find buried verdict sentences (short, declarative, quotable) and promote them to block-final position; do not write new ones.

For pattern recommendations beyond the document's own house style, read prose-patterns.md (bundled). Render document-dependent patterns as pattern cards and apply its conflict rule: the author's standing rules outrank the taste reference.

4. Socratic seam check (S1..Sn). For each section, write two lines: ANSWERS (the one question this section exists to answer) and ENDS RAISING (the question its final paragraph leaves the reader holding). A seam is ok when a section ends raising exactly the question the next section answers; weak only when the right question is raised but mid-section instead of at the close; mismatch when the ending points at the wrong section or at nothing. An ending that raises no question at all is a mismatch, never weak: weak means the hand-off exists, mislocated. Mismatch verdicts render with seam class bad; the template has no class named mismatch. Two fixes, in order of preference: (a) rearrange: relocate or reorder the author's existing sentences so the section closes on the right question; (b) bridge slot: when no existing sentence can close the seam, a dashed-blue placeholder describing what the bridge sentence must do, citing raw material already in the text if any exists. Never draft the bridge; the author writes it. Either fix is a judgment call and belongs in edit-order step 3: seam fixes change what a section ends on, so the author signs off even when the mechanics are a pure move. Chip wording follows the fix type, both styled judg: "rearrange — author signs off" for pure moves, "bridge — author's words" for slots.

5. Render the companion. Copy the template's <style> verbatim; assemble from its components only (size strip, section heads, D cards with quote panels, F/S cards with NOW/PROPOSED panes, question chain, optional pattern cards, edit-order steps). Every F and S finding is shown as before/after; the PROPOSED pane contains only the author's sentences rearranged, plus dashed slots. Never nest <mark> elements; mark sibling spans separately. When findings touch the same paragraph, pick one card to show the combined after-state and say so in its .note; co-located findings keep their own chips. The fixed by chip is reserved for a finding another finding resolves outright, and it applies on any axis (a D trimmed by an F's rewrite-free split, an S closed by another S's relocation). Verify rendering with a screenshot (any browser, headless is fine) before declaring done.

Small calls, settled:

• Precedence when sources disagree: SKILL.md, then the example (assembly order, density), then the template's comments. The <style> block always comes from the template.
• Section order: duplication, format, patterns (if used), flow, edit order; number the section heads continuously.
• Chips on F and S cards only when the finding needs an author decision; when fixed by and judgment call both apply, fixed by wins the chip and the judgment routes through the resolving finding.
• Drop legend clauses for glyphs the page does not use; trimming inside a clause is allowed when only half of it applies.
• Size strip scale: the longest section's bar spans the full strip width; every other bar proportional to it. Mark hot for the sections that absorb edit work, not merely the largest.
• With zero findings on every axis, the edit order is one honest no-action step; nothing to do is a legitimate audit result.

6. Edit order. Close with the steps grid: mechanical trims first, format-only moves second, judgment calls with the author third, then whatever verification the document's project requires, if any.

Red flags - stop and re-read the rules

• "I'll design something nicer for this content" → the template is the design
• "The author probably wants a checklist like this" → lift their words or leave a slot
• "This rewrite is better prose" → not yours to write
• "Severity: high/medium/low" → classify by decision type; effort, not importance
• A fix shown as a prose suggestion instead of a before/after pane
• A flow problem reported without the full question chain around it

Common mistakes

• Skipping the question chain because the seams "look fine"; the chain is how you find out
• Marking the duplicated phrase in only one of its locations; mark all, decide one owner
• Forgetting the size strip; the author should see at a glance which section absorbs most of the work
• Companion references findings by ID only; every card restates its point in place