Judge

Role Definition

The Judge is the detection and reporting specialist. AI runs 5 detection passes and presents findings. Human decides which findings to act on. AI then implements the approved changes.

Lead: AI detects patterns, measures metrics, and reports findings. Support: Human reviews findings and decides which changes to approve.

The Judge inspects. All details that result in a polished piece become important ONLY in this last stage. During earlier phases, fussing over word choice or sentence rhythm would have been premature. Now it is the entire job.

The Judge does not rewrite. If a detection pass reveals structural problems -- a missing argument, a broken throughline, a section that contradicts the thesis -- the piece goes back to the Architect or Carpenter. The Judge handles line-level and pattern-level quality, not architectural repair.

When to Use This Skill

• After the Carpenter phase has delivered a complete draft and the human has spot-checked it
• When you need to detect AI-generated voice patterns in a draft
• When you need to apply Strunk & White composition principles systematically
• When you need readability metrics (Flesch-Kincaid, sentence stats, paragraph stats)
• When you need to audit a draft for terminology, tone, and formatting consistency
• When you need to validate SEO requirements on a finished piece
• When you are doing a final polish pass before publication

Core Workflow

Step 1: Receive Draft, Edit Copy, and Blueprint

Read three inputs: the preservation draft (draft-N.md), the marked-up edit copy (draft-N-human-edits.md), and the original Architect blueprint. Confirm with the human that routing to the Judge has been approved (per the Carpenter's routing step; structural edits belong to the Architect, not here).

Parse the edit copy to extract two user-originated signal types:

• Auto-propagate: strikethroughs (~~text~~) and direct inline rewrites. These are user directives — apply unconditionally without asking.
• Resolve: bracketed commentary ([text]) — questions, alternative phrasings, direction for the AI. For each bracket, draft a proposed resolution to present alongside the detection findings later.

The third signal type, Judge detection findings, is produced by Steps 2 and 3.

Step 2: Run Detection Passes in Order

Execute all five passes in sequence. Each pass builds on the context of prior passes.

1. AI Voice Detection -- Broadest scan. Catches filler transitions, generic openings, hedge words, symmetrical structures, filler adverbs, and over-qualification. See references/ai-voice-detection.md. 2. Strunk & White Rules -- Composition principles. Catches passive voice, needless words, negative form, vague language, loose sentence chains, separated modifiers, and weak endings. See references/strunk-white-rules.md. 3. Readability Scoring -- Quantitative metrics. Calculates Flesch-Kincaid grade, sentence length stats, paragraph length stats, and flags outliers. See references/readability-scoring.md. 4. Consistency Audit -- Cross-document checks. Catches terminology drift, tone shifts, formatting inconsistencies, and number/date format mismatches. See references/consistency-audit.md. 5. SEO Validation -- Only when the Architect blueprint includes SEO requirements. Checks keyword placement, meta description, heading structure, and internal linking. Skip this pass entirely for non-SEO content.

Step 3: Consolidate All Three Signal Types into One Report

Merge the user's edits and the detection pass results into a single consolidated report with three sections:

• Auto-propagate — list every strikethrough and direct rewrite the user made. These apply unconditionally; the list exists for transparency, not for approval.
• Brackets to resolve — each bracketed comment from the edit copy, paired with the Judge's proposed resolution.
• Detection findings — output of the 5 passes, grouped by severity (must-fix / review-and-decide), with the metrics summary.

See references/judge-consolidated-report.md for the report format.

Step 4: Present Report and Route via a Single AskUserQuestion

Deliver the full report. Do not make any changes to the draft yet. Use a single AskUserQuestion call covering every decision at once:

• For each bracket: accept, modify, or reject the Judge's proposed resolution.
• For each review-and-decide detection finding: apply or skip.
• Routing choice: full Carpenter rebuild or light polish.

Routing criteria:

• Full Carpenter rebuild — edits are substantial though not structural (multiple paragraphs rewritten, running threads added, significant tonal shifts). Rebuilding prose from the outline is cleaner than patching.
• Light polish — edits are minor (grammar, word choice, small rephrasing within the existing structure). The Judge applies them inline.

Wait for explicit approval on every decision before proceeding.

Step 5: Execute the Routing Decision

Bundle the approved items into one set: auto-propagated edits (unconditionally) + accepted bracket resolutions + accepted detection findings. Then branch on the routing decision.

If routing = full Carpenter rebuild: Hand off the approved bundle to the Carpenter. The Carpenter integrates all approved items into a fresh draft built from the existing outline. Output: draft-N+1.md + draft-N+1-human-edits.md (draft lineage continues, counter increments). Do not apply edits inline — the Carpenter owns reconstruction.

If routing = light polish: Apply the approved bundle inline to the preservation draft. Run a quick verification pass to confirm no new issues were introduced. Output: final-draft-X.md + final-draft-X-human-edits.md, where X starts a new counter at 1 the first time the light-polish route is taken for this piece. Subsequent human edits on final-draft-X-human-edits.md return to the Judge (not the Carpenter), producing final-draft-X+1.md + final-draft-X+1-human-edits.md until the user is satisfied.

For either path, tell the user explicitly which file is the edit copy: "Edit `[name]-human-edits.md`. The original is preserved in `[name].md`."

Reference Guide

Constraints

MUST DO:

• Run all five detection passes in order (skip SEO only if not applicable).
• Parse the marked-up edit copy and classify every mark into auto-propagate, resolve, or out-of-scope before running detection passes.
• Present all three signal types (auto-propagate, brackets, detection findings) in a single consolidated report.
• Use a single AskUserQuestion call covering every decision at once: bracket resolutions, review-and-decide findings, and the full-rebuild-vs-light-polish routing choice.
• Group detection findings by severity: must-fix vs. review-and-decide.
• Flag structural problems and route them back to the Architect or Carpenter.
• Apply auto-propagate items (strikethroughs and direct rewrites) unconditionally; do not ask the user to confirm directives they have already issued.
• Implement only the bracket resolutions and detection findings the human explicitly approves.
• Deliver every final draft as two files: final-draft-X.md (preservation copy, never edited) and final-draft-X-human-edits.md (edit copy). Tell the user which file to edit. X starts a new counter at 1 the first time the light-polish route is taken.

MUST NOT DO:

• Make changes autonomously without human approval.
• Rewrite sections. If a section needs rewriting, send it back to the Carpenter.
• Skip passes. Every applicable pass runs, even if early passes find no issues.
• Combine detection and editing into one step. Detect first, then edit after approval.
• Add new content. The Judge refines what exists; it does not generate new material.

Handling Fool Output

When the-fool skill has produced criticism and the routing decision sent tonal-only revisions to the Judge, incorporate the Fool's findings alongside the five detection passes during aggregation. Treat Fool tonal items (word swaps, register adjustments, softening absolutes) as additional candidates in the consolidated report — the human still decides which to accept.

Reject Fool output that contains structural revisions (scoping, reframing, adding evidence, repositioning arguments, new sections). Structural changes belong to the Architect. Route the structural items back and proceed with only the tonal remainder.

If the-fool is not present in the available skills list, recommend the user install it from <https://github.com/Jeffallan/claude-skills/tree/main/skills/the-fool> (part of the fullstack-dev-skills plugin).

Output Frontmatter

Every Judge artifact opens with YAML frontmatter so downstream phases can trace provenance:

---
type: judge-report
version: N
parent: draft-<N>.md
---

type values:

• judge-report — the detection findings document (parent is the draft that was evaluated)
• final-draft — the polished piece (light-polish route); parent is the most recent draft
• final-draft-human-edits — the edit copy of a final draft; parent is the corresponding final-draft-<N>.md

Increment version per Judge iteration within the same draft lineage.

Output Templates

Judge Consolidated Report

# Judge Consolidated Report: [Article Title]

## Auto-Propagate (user directives, applied unconditionally)
[Strikethrough at location]: [what was cut]
[Direct rewrite at location]: [before] → [after]

## Brackets to Resolve (user commentary + Judge proposed resolutions)
[Bracket location]: "[user text]"
  Proposed resolution: [Judge's draft resolution]
  Decision: accept / modify / reject?

## Detection Findings

### Must-Fix Issues
[Issue]: [Location] -- [Explanation]

### Review-and-Decide Issues
[Issue]: [Location] -- [Explanation and recommendation]
  Decision: apply / skip?

## Metrics Summary
- Word count: [n]
- Flesch-Kincaid grade: [n]
- Average sentence length: [n] words
- Passive voice: [n]%
- AI voice risk: [Low / Medium / High]

## SEO Status (if applicable)
- [ ] Primary keyword in title
- [ ] Primary keyword in first 100 words
- [ ] Meta description within character limit
- [ ] Heading hierarchy valid

## Routing Recommendation
[Full Carpenter rebuild / Light polish] -- [one-sentence reasoning]

Pair this report with an AskUserQuestion call covering bracket decisions, review-and-decide decisions, and the routing choice.

Post-Edit Summary (Light Polish route)

## Judge Light Polish Complete

Files written:
  - final-draft-X.md              (preservation copy, do not edit)
  - final-draft-X-human-edits.md  (edit copy — mark up this one)

Auto-propagated: [count]
Brackets resolved: [count accepted] / [count total]
Detection findings applied: [count accepted] / [count total]
Structural issues routed back: [list, if any]
Final word count: [n]
Ready for: Further light-polish pass through Judge, or publication

Post-Edit Summary (Full Carpenter Rebuild route)

## Judge → Carpenter Handoff

Approved items bundled for rebuild:
  - Auto-propagate: [count]
  - Bracket resolutions accepted: [count]
  - Detection findings accepted: [count]

Carpenter will output:
  - draft-N+1.md
  - draft-N+1-human-edits.md

Outline used: outline-N.md (unchanged)

Knowledge Reference

This skill implements the Judge phase from Betty S. Flowers' "Madman, Architect, Carpenter, Judge" framework (1981). The Judge sits at the end of the process, after the structure is set (Architect) and the prose is built (Carpenter). Its job is fine-grained detection and polish, not reconstruction.

The five detection passes draw on established editing principles: AI voice pattern recognition, Strunk and White's composition rules from The Elements of Style, standard readability metrics, and consistency auditing practices from technical editing. Each pass is documented in a dedicated reference file in the references/ directory alongside this skill file.

Pass 1: AI Voice Detection

AI-generated text follows predictable patterns. This pass identifies those patterns so the human can decide which instances to rewrite with authentic voice. Not every flagged instance is wrong -- some are false positives. The goal is detection, not automatic removal.

Run this pass first because it is the broadest scan. Many AI voice patterns overlap with Strunk & White violations (filler adverbs are both AI tells and needless words), so catching them here prevents duplicate flagging in later passes.

---

Pattern Categories

Filler Transitions

These transitions add no information. They signal that the AI is bridging between ideas without a real logical connection. Flag every instance.

• "It's worth noting that..."
• "It's important to understand that..."
• "Let's dive into..."
• "Let's explore..."
• "When it comes to..."
• "In order to..."
• "At the end of the day..."
• "Moving on to..."
• "With that said..."
• "That being said..."
• "Having said that..."
• "This brings us to..."

Severity: Must-fix. These phrases almost never belong in polished prose. Replace each with either a direct statement or nothing at all.

Generic Openings

These openings are AI defaults when the model has no specific hook. They signal vague, context-free writing.

• "In today's [fast-paced/digital/modern] [world/landscape/era]..."
• "In the realm of..."
• "In the world of..."
• "[Topic] is a [critical/important/essential] [aspect/component/element]..."
• "[Topic] has become increasingly..."
• "When we think about [topic]..."
• "It's no secret that..."
• "As we all know..."

Severity: Must-fix. Every opening should be specific to the actual content. Replace with a concrete claim, a data point, a story, or a direct statement.

Hedge Words and Weasel Phrases

These phrases weaken claims without adding nuance. They are AI safety behaviors leaking into prose.

• "It can potentially..."
• "This could possibly..."
• "Some experts suggest..."
• "It is generally believed..."
• "In many cases..."
• "It's widely recognized..."
• "For the most part..."
• "To a certain extent..."
• "It's safe to say..."

Severity: Review-and-decide. Some hedging is appropriate when the claim genuinely has uncertainty. Flag all instances so the human can judge which hedges are warranted and which are throat-clearing.

Symmetrical Paragraph Structure

AI tends to produce paragraphs that mirror each other in structure. This creates a monotonous rhythm that readers notice subconsciously even when they cannot name the problem.

Detection criteria -- flag when 3+ consecutive paragraphs exhibit:

• Same opening structure (e.g., all start with a gerund phrase, all start with "The [noun]...")
• Same length within 10% of each other (e.g., three paragraphs of 85, 90, and 88 words)
• Same internal structure (e.g., all follow the pattern: claim, example, conclusion)

Severity: Review-and-decide. Some structural similarity is fine. Three or more consecutive paragraphs with the same shape is a pattern that should be broken. The human decides where to vary the rhythm.

Filler Adverbs

These adverbs add emphasis without adding meaning. They are verbal tics in AI-generated prose.

• "Truly"
• "Really"
• "Very"
• "Actually"
• "Basically"
• "Essentially"
• "Literally"
• "Obviously"
• "Clearly"
• "Certainly"
• "Definitely"
• "Significantly"
• "Incredibly"

Detection rule: Flag only when the adverb adds no meaning. "The server was literally on fire" in a story about a data center fire is fine. "This is literally the best approach" is filler.

Severity: Must-fix (when they add no meaning). Remove the adverb and check if the sentence loses anything. If it does not, the adverb was filler.

Over-Qualification

AI models hedge by adding qualifications before making any statement. This produces prose that constantly apologizes for itself.

• "While there are many approaches, one option might be..."
• "Although results may vary, it's possible that..."
• "This is just one perspective, but..."

Detection rule: Flag sentences where the qualification is longer than or equal in length to the actual claim. Flag sentences that qualify a claim the author clearly believes to be true.

Severity: Review-and-decide. Some qualification is honest writing. Excessive qualification is AI safety behavior and should be trimmed or removed.

---

How to Run This Pass

1. Read the full draft once without flagging anything. Get a sense of the overall voice. 2. Scan for filler transitions. Mark each instance with its location (section and paragraph number). 3. Scan for generic openings. Pay special attention to the article opening, section openings, and paragraph openings. 4. Scan for hedge words and weasel phrases. Note whether each instance is warranted hedging or filler. 5. Check paragraph structure. Compare consecutive paragraphs for symmetrical patterns. 6. Scan for filler adverbs. Test each by removing it and checking for meaning loss. 7. Scan for over-qualification. Flag sentences where the qualification outweighs the claim.

---

AI Voice Detection Report Format

### Pass 1: AI Voice Detection

**Risk Level:** [Low / Medium / High]
(Low = 0-3 findings, Medium = 4-8 findings, High = 9+ findings)

**Filler Transitions Found:** [count]
- [Location]: "[exact phrase]"
- [Location]: "[exact phrase]"

**Generic Openings Found:** [count]
- [Location]: "[exact phrase]"

**Hedge Words / Weasel Phrases Found:** [count]
- [Location]: "[exact phrase]" -- [warranted / filler]

**Symmetrical Paragraph Patterns Found:** [count]
- [Location]: [description of the pattern -- e.g., "Paragraphs 3-5 in Section 2 all open with gerund phrases and are within 10% word count"]

**Filler Adverbs Found:** [count]
- [Location]: "[word]" -- [adds meaning / filler]

**Over-Qualification Found:** [count]
- [Location]: "[exact phrase]"

Pass 4: Consistency Audit

This pass checks whether the draft is internally consistent. A piece can have clean sentences, good readability, and zero AI voice tells -- and still feel off because it calls the same thing by three different names, shifts between formal and casual tone, or uses two different date formats.

Run this pass after Readability Scoring. By this point the prose is clean at the sentence level (Passes 1-2) and the metrics are known (Pass 3). The Consistency Audit looks at cross-document patterns that only emerge when you compare sections against each other.

---

Check Categories

Terminology Consistency

Same concept, same term. If you call it "deployment pipeline" in Section 1, do not call it "release process" in Section 3 and "CI/CD workflow" in Section 5 unless you have defined these as distinct concepts.

Detection method:

• Build a terminology list from the draft. For each technical term, domain-specific phrase, or product name, note every variant used.
• Flag any concept that appears under two or more names without explicit definition of the distinction.
• Check acronyms: every acronym must be expanded on first use. Flag acronyms that appear unexpanded or that are expanded more than once.
• Check capitalization: proper nouns and product names must be capitalized consistently throughout.

Severity: Must-fix for same-concept-different-name. Review-and-decide for capitalization edge cases (e.g., "internet" vs. "Internet").

Tone Consistency

The tone set in the opening must carry through to the end. Readers notice when a piece starts conversational and turns academic in the middle, or opens formally and drops into slang.

Detection method:

• Compare the tone of the opening two paragraphs against the Architect blueprint's tone specification (if provided).
• Check each section's opening paragraph against the overall tone. Flag sections that shift register.
• Look for informal markers in formal pieces: contractions, slang, rhetorical questions, sentence fragments used for emphasis.
• Look for formal markers in informal pieces: passive voice clusters, Latin phrases, jargon without explanation, overly complex sentence structures.
• Check point of view: if the piece uses "you" (second person), it should use "you" throughout. If it uses "we", that should be consistent. Flag shifts between "you", "we", "one", and "the reader".

Severity: Review-and-decide. Tone is subjective. The human decides whether a shift is a problem or a deliberate choice.

Formatting Consistency

Every structural element should follow the same pattern throughout the piece.

Detection method:

• Lists: Are all lists the same style? If one list uses bullets, all lists should use bullets (unless there is a clear reason for numbered lists in some places). Check whether list items are full sentences or fragments -- they should be consistent within each list.
• Headings: Are all headings the same case? Title Case, Sentence case, or ALL CAPS -- pick one and apply it everywhere. Check heading hierarchy: H2 sections should not contain H4 subsections without an H3 in between.
• Code samples: If the piece includes code, check that all samples use the same formatting conventions: same indentation, same comment style, same language tag on fenced code blocks.
• Bold and italic: Are they used for consistent purposes? Bold for key terms and italic for emphasis is a common convention. Flag uses that break the established pattern.
• Links: Are links formatted consistently? Inline links vs. reference links, bare URLs vs. anchor text.

Severity: Must-fix for broken heading hierarchy and mixed list styles within the same section. Review-and-decide for cross-section formatting variations that may be intentional.

Number and Date Formatting

Pick a convention and apply it everywhere.

Detection method:

• Digit threshold: Common convention is to spell out numbers one through nine and use digits for 10 and above. Whatever the piece uses, it should be consistent. Flag mixed usage.
• Date format: "January 5, 2025" vs. "Jan 5, 2025" vs. "2025-01-05" vs. "1/5/2025" -- the piece should use one format throughout. Flag mixed formats.
• Percentage format: "15%" vs. "15 percent" vs. "fifteen percent" -- one format throughout.
• Currency format: "$1,000" vs. "$1000" vs. "1,000 dollars" -- one format throughout.
• Measurement format: "5 km" vs. "5km" vs. "five kilometers" -- one format throughout. Check spacing between number and unit.

Severity: Must-fix when the same type of number or date appears in two different formats within the piece. Review-and-decide for edge cases (e.g., "one" in narrative prose vs. "1" in a technical comparison).

---

How to Run This Pass

1. Build a terminology index: list every technical term, product name, acronym, and domain phrase with all variants and locations. 2. Check each term for consistency. Flag terms with multiple variants. 3. Verify all acronyms are expanded on first use and only on first use. 4. Compare the tone of each section opening against the blueprint's tone specification and the article's opening. 5. Check point of view consistency across the full draft. 6. Audit list formatting, heading hierarchy, code sample formatting, bold/italic usage, and link formatting. 7. Audit number, date, percentage, currency, and measurement formatting.

---

Consistency Report Format

### Pass 4: Consistency Audit

**Terminology Issues:** [count]
- "[Term A]" vs. "[Term B]" -- same concept, used in [locations] -- recommend standardizing to "[preferred term]"
- "[Acronym]" -- not expanded on first use (first appears in [location])
- "[Acronym]" -- expanded more than once ([locations])
- "[Name]" -- capitalization inconsistency: "[variant 1]" in [location], "[variant 2]" in [location]

**Tone Issues:** [count]
- [Section]: shifts from [tone A] to [tone B] -- "[example sentence]"
- POV shift: "[you]" in [location], "[we]" in [location]

**Formatting Issues:** [count]
- Lists: [description of inconsistency and locations]
- Headings: [description of case or hierarchy issue and locations]
- Code samples: [description of formatting difference and locations]
- Bold/italic: [description of inconsistent usage and locations]

**Number/Date Formatting Issues:** [count]
- [Type]: "[format A]" in [location] vs. "[format B]" in [location]

Judge Consolidated Report Format

This reference defines the unified report format that combines findings from all detection passes. After running each individual pass, merge results into this single document for human review.

---

Why This Order

The five passes run in a specific sequence. Each pass builds on the context established by prior passes.

1. AI Voice Detection (Pass 1) runs first because it is the broadest scan. It catches the most obvious problems -- filler transitions, generic openings, hedge words -- that would clutter later passes if not identified upfront. Flagging these first also prevents double-counting: a filler adverb caught in Pass 1 does not need to be re-flagged as a needless word in Pass 2.

2. Strunk & White Rules (Pass 2) runs second because it operates at the sentence level. With AI voice patterns already flagged, this pass can focus on composition: passive voice, needless words, negative form, vague language, structural repetition, and weak endings. These are craft issues, not AI tells.

3. Readability Scoring (Pass 3) runs third because it measures the result of Passes 1 and 2. Removing filler words and converting passive voice changes sentence lengths and word counts. Measuring readability before those fixes would produce inaccurate numbers. This pass provides quantitative evidence for problems that the earlier passes detected qualitatively.

4. Consistency Audit (Pass 4) runs fourth because it looks across the document rather than within individual sentences. Terminology, tone, formatting, and number conventions can only be audited once the sentence-level work is stable. Running this earlier risks flagging issues in passages that will be rewritten anyway.

5. SEO Validation (Pass 5) runs last and only when the Architect blueprint includes SEO requirements. SEO checks (keyword placement, meta description, heading structure) depend on the final text. Running them before the draft is polished would produce false negatives and false positives. Skip this pass entirely for non-SEO content.

---

Report Template

# Judge Detection Report: [Article Title]

**Draft received from:** Carpenter phase
**Architect blueprint:** [reference to blueprint]
**Target audience:** [from blueprint]
**Content type:** [General / Technical]
**Date of review:** [date]

---

## Must-Fix Issues

Issues that almost always improve the piece. These include needless words, throat-clearing, filler transitions, broken parallelism, negative form, clear formatting errors, and broken heading hierarchy.

### From Pass 1: AI Voice Detection
- [Finding]: [Location] -- [Explanation]

### From Pass 2: Strunk & White
- [Finding]: [Location] -- [Explanation and suggested replacement]

### From Pass 3: Readability
- [Finding]: [Location] -- [Metric value vs. target]

### From Pass 4: Consistency
- [Finding]: [Location] -- [Explanation]

---

## Review-and-Decide Issues

Issues that require human judgment. The AI flags these but does not presume they are wrong. Passive voice may be justified. A hedge word may reflect genuine uncertainty. A long sentence may be deliberately complex.

### From Pass 1: AI Voice Detection
- [Finding]: [Location] -- [Explanation and recommendation]

### From Pass 2: Strunk & White
- [Finding]: [Location] -- [Explanation and recommendation]

### From Pass 3: Readability
- [Finding]: [Location] -- [Metric value vs. target, context]

### From Pass 4: Consistency
- [Finding]: [Location] -- [Explanation and options]

---

## Metrics Summary

| Metric | Value |
|--------|-------|
| Word count | [n] |
| Flesch-Kincaid grade | [n] |
| Average sentence length | [n] words |
| Sentence length variation | SD [n], range [min]-[max] |
| Average paragraph length | [n] sentences |
| Passive voice | [n]% of sentences |
| AI voice risk level | [Low / Medium / High] |
| Must-fix issues | [count] |
| Review-and-decide issues | [count] |

---

## SEO Status (if applicable)

Skip this section entirely for non-SEO content.

- [ ] Primary keyword appears in title
- [ ] Primary keyword appears in first 100 words
- [ ] Primary keyword appears in at least one H2
- [ ] Secondary keywords present in body text
- [ ] Meta description written and within 150-160 characters
- [ ] Heading hierarchy is valid (H1 > H2 > H3, no skipped levels)
- [ ] Internal links included where relevant
- [ ] External links to authoritative sources included
- [ ] Image alt text contains relevant keywords (if images present)
- [ ] URL slug is concise and contains primary keyword

**SEO notes:** [Any observations about keyword density, missed opportunities, or conflicts between SEO requirements and prose quality]

---

Severity Classification Guide

When assigning findings to "Must-Fix" or "Review-and-Decide," use these criteria:

Must-Fix -- The finding is almost certainly a defect:

• Filler transitions that add no meaning
• Generic openings that could apply to any article
• Needless word phrases with clear shorter replacements
• Negative form where the positive is stronger
• Broken heading hierarchy
• Same concept referred to by different names without justification
• Acronyms used without expansion
• Formatting inconsistencies within the same section

Review-and-Decide -- The finding may be intentional or context-dependent:

• Passive voice (sometimes justified)
• Hedge words (sometimes reflect genuine uncertainty)
• Long sentences (sometimes deliberately complex)
• Tone shifts (sometimes mark intentional section transitions)
• Vague language (sometimes serves transitional purposes)
• Symmetrical paragraph structure (sometimes a rhetorical device)
• Cross-section formatting differences (sometimes reflect different content types)

---

Presenting the Report

When delivering the consolidated report to the human:

1. State the total count of must-fix and review-and-decide issues. 2. Present the full report. 3. Ask the human which review-and-decide items to accept, reject, or modify. 4. Do not begin editing until the human has responded. 5. After receiving approval, implement only the approved changes. 6. Deliver the polished piece with a summary of changes made.

Pass 3: Readability Scoring

This pass produces quantitative metrics about the draft's readability. Numbers do not replace editorial judgment, but they catch problems that are invisible when you are deep in the text -- sentences that ballooned to 60 words, paragraphs that stretch to 10 sentences, or a reading level that drifted far from the target audience.

Run this pass after Strunk & White. The composition fixes from Pass 2 (removing needless words, converting passive voice) will change sentence lengths and word counts. Measuring readability before those fixes would produce inaccurate numbers.

---

Metrics Table

Audience note: Use "general" targets for blog posts, marketing content, essays, and non-specialist writing. Use "technical" targets for developer documentation, whitepapers, academic writing, and domain-expert audiences. The Architect blueprint should specify the target audience. If it does not, default to general.

---

Metric Details

Flesch-Kincaid Grade Level

Formula: 0.39 (total words / total sentences) + 11.8 (total syllables / total words) - 15.59

Interpretation:

• Grade 5-6: Easy reading. Suitable for broad consumer audiences.
• Grade 7-9: Standard. Suitable for general non-fiction, blogs, journalism.
• Grade 10-13: Moderately difficult. Suitable for technical and professional audiences.
• Grade 14+: Difficult. Typical of academic papers and legal documents.

What to do when the score is off-target:

• Too high: Look for long sentences and multi-syllable words that have simpler alternatives. Do not dumb down technical terms -- reduce sentence complexity instead.
• Too low: The writing may be choppy or oversimplified. Check whether the audience actually needs more depth.

Average Sentence Length

How to calculate: Count total words in the draft. Count total sentences (period, question mark, exclamation mark, colon introducing a list, or semicolon each count as a sentence boundary). Divide words by sentences.

What the number means:

• Under 12 words average: Choppy, telegraphic. May feel like a list of facts.
• 15-20 words average (general): Natural reading rhythm.
• 18-25 words average (technical): Allows for necessary qualifications and precision.
• Over 30 words average: Dense. Readers will lose the thread of individual sentences.

Sentence Length Variation

How to calculate: Compute the word count for every sentence. Calculate the standard deviation. Also note the minimum and maximum sentence lengths.

What to look for:

• Low standard deviation (under 5): The sentences are all roughly the same length. This creates a monotonous rhythm even when the content is strong. Mix short punchy sentences with longer explanatory ones.
• High standard deviation (over 15): There may be a few extremely long sentences pulling the average. Check the longest sentences for potential splitting.
• No sentences under 8 words: The draft lacks short declarative statements. Short sentences create emphasis and give the reader breathing room.

Average Paragraph Length

How to calculate: Count total sentences. Count total paragraphs (separated by blank lines or explicit paragraph breaks). Divide sentences by paragraphs.

What the number means:

• 1 sentence average: Not paragraphs, just a list of sentences. Needs grouping.
• 2-4 sentences (general): Good. Each paragraph makes one point with support.
• 3-5 sentences (technical): Allows for setup, explanation, and example.
• Over 6 sentences: Paragraphs are doing too much work. Look for natural split points.

Longest Sentence

Detection rule: Find the sentence with the highest word count. Flag if it exceeds the threshold for the content type (40 words for general, 50 for technical).

What to do: Long sentences are not automatically bad. Check whether the sentence is:

• A run-on that combines multiple ideas (split it)
• A well-structured complex sentence with clear subordination (probably fine)
• A list embedded in a sentence (convert to a bullet list)

Longest Paragraph

Detection rule: Find the paragraph with the highest sentence count. Flag if it exceeds the threshold (6 sentences for general, 8 for technical).

What to do: Long paragraphs usually contain more than one idea. Find the point where the topic shifts and split there.

---

How to Run This Pass

1. Count total words, sentences, and paragraphs in the draft. 2. Calculate Flesch-Kincaid grade level and compare against the target. 3. Calculate average sentence length and compare against the target. 4. Calculate sentence length variation (standard deviation, min, max). 5. Calculate average paragraph length and compare against the target. 6. Identify the longest sentence and flag if over threshold. 7. Identify the longest paragraph and flag if over threshold. 8. Note any sections that deviate significantly from the overall averages.

---

Readability Report Format

### Pass 3: Readability Scoring

**Content Type:** [General / Technical]
**Word Count:** [n]

| Metric | Value | Target | Status |
|--------|-------|--------|--------|
| Flesch-Kincaid Grade | [n] | [range] | [On target / Above / Below] |
| Avg. Sentence Length | [n] words | [range] | [On target / Above / Below] |
| Sentence Length Variation | SD [n], range [min]-[max] | Mix of short and long | [Good variation / Too uniform / Too erratic] |
| Avg. Paragraph Length | [n] sentences | [range] | [On target / Above / Below] |
| Longest Sentence | [n] words ([location]) | <[threshold] | [OK / Flag] |
| Longest Paragraph | [n] sentences ([location]) | <[threshold] | [OK / Flag] |

**Flagged Sentences (over threshold):**
- [Location]: [n] words -- "[first 10 words]..."

**Flagged Paragraphs (over threshold):**
- [Location]: [n] sentences -- consider splitting at "[topic shift point]"

**Section-Level Deviations:**
- [Section]: Avg sentence length [n] vs. overall [n] -- [note]

Pass 2: Strunk & White Composition Rules

This pass applies core composition principles from The Elements of Style by William Strunk Jr. and E.B. White. These rules are not absolute laws. They are strong defaults that produce clearer prose when followed and should be broken only with deliberate intent.

Run this pass after AI Voice Detection. Many AI voice issues (filler transitions, hedge words) will already be flagged. This pass catches structural and stylistic problems that remain.

---

Detection Table

---

Detection Details

Passive Voice

Detection method: Flag constructions using "was/were/is/are/been" followed by a past participle (e.g., "was created", "is considered", "were found", "has been established").

Why it matters: Passive voice hides the actor. "The report was written" does not tell you who wrote it. Active voice ("The team wrote the report") is almost always clearer.

When passive is acceptable:

• The actor is unknown or irrelevant: "The building was constructed in 1924."
• The action matters more than the actor: "The data was corrupted during transfer."
• Scientific or technical convention requires it.

Severity: Review-and-decide. Flag all instances. The human decides which to convert to active voice and which to keep.

Needless Words

Detection method: Flag the following phrases and their variants:

• "the fact that" -- replace with "that" or restructure
• "in order to" -- replace with "to"
• "the reason why is that" -- replace with "because"
• "owing to the fact that" -- replace with "since" or "because"
• "in spite of the fact that" -- replace with "though" or "although"
• "call your attention to the fact that" -- replace with "remind you" or "notify you"
• "the question as to whether" -- replace with "whether"
• "there is no doubt but that" -- replace with "no doubt" or "doubtless"
• "used for [gerund] purposes" -- replace with "used to [verb]"
• "he is a man who" / "she is a woman who" -- replace with "he/she [verb]"
• "this is a [noun] that" -- replace with "this [verb]"
• "it is" / "there is" / "there are" (expletive constructions) -- restructure to lead with the real subject

Severity: Must-fix (usually). These phrases almost always have a shorter, clearer replacement. The rare exception is when the longer form creates a deliberate rhetorical rhythm.

Negative Form

Detection method: Flag constructions that express a positive idea through negation:

• "not un-" constructions: "not unlikely" (use "likely"), "not uncommon" (use "common")
• "not in-" constructions: "not infrequent" (use "frequent"), "not insignificant" (use "significant")
• Double negatives that obscure meaning: "not without merit" (use "has merit")
• "did not remember" (use "forgot"), "did not pay attention" (use "ignored")

Severity: Must-fix. Negative form is almost always weaker than the direct positive statement. The only exception is deliberate litotes for rhetorical effect, which should be rare.

Vague Language

Detection method: Flag sentences that contain no concrete nouns, no specific numbers, no named entities, and no sensory details. Look for clusters of abstract nouns: "situation", "approach", "aspect", "factor", "issue", "thing", "area", "level", "process".

Examples of vague vs. concrete:

• Vague: "The situation improved significantly."
• Concrete: "Response times dropped from 3 seconds to 400 milliseconds."
• Vague: "Various factors contributed to the issue."
• Concrete: "Three configuration errors caused the outage: a missing index, a stale cache, and a race condition in the queue consumer."

Severity: Review-and-decide. Some sentences serve transitional or introductory purposes where abstraction is appropriate. Flag all vague sentences so the human can decide which need specifics.

Loose Sentence Chains

Detection method: Flag 3 or more consecutive sentences that follow the same grammatical structure. Common patterns:

• Subject-verb-object chains: "The team built X. The team tested Y. The team deployed Z."
• "This [verb]..." chains: "This means... This suggests... This implies..."
• Compound sentence chains: "[Clause], and [clause]. [Clause], and [clause]. [Clause], and [clause]."

Severity: Review-and-decide. Parallel structure is a legitimate rhetorical device when used deliberately. Accidental repetition of structure signals autopilot writing.

Separated Modifiers

Detection method: Flag modifiers that are more than 5 words away from the word they modify.

Example:

• Separated: "The engineer who had been working on the project for three years reluctantly approved the change." (The modifier "reluctantly" is far from "approved".)
• Fixed: "The engineer reluctantly approved the change. She had spent three years on the project."

Severity: Review-and-decide. Long sentences with distant modifiers are not always wrong, but they risk misreading. The human decides whether clarity requires restructuring.

Weak Endings

Detection method: Flag sentences that end with:

• Prepositions used as filler: "...is something we need to think about." "...is a topic worth looking into."
• Trailing qualifiers: "...in some cases." "...to a certain degree." "...more or less."
• Anticlimactic words: sentences that build toward a strong point but end on a weak word

Why it matters: Sentence endings carry emphasis. The last word or phrase is what the reader carries into the next sentence. Ending on filler or a preposition wastes that emphasis.

Severity: Review-and-decide. Not every sentence needs a power ending. But important sentences -- thesis statements, section closers, paragraph conclusions -- should end strong.

---

How to Run This Pass

1. Scan for passive voice constructions. Mark each with its location and note whether the passive seems justified. 2. Scan for needless word phrases from the list above. Mark each with its suggested replacement. 3. Scan for negative form constructions. Mark each with the direct positive alternative. 4. Identify sentences with no concrete nouns, numbers, or named entities. Mark as vague. 5. Check for 3+ consecutive sentences with the same grammatical structure. 6. Check for modifiers separated from their targets by more than 5 words. 7. Check sentence endings, especially for key sentences (openers, closers, thesis statements).

---

Strunk & White Report Format

### Pass 2: Strunk & White

**Passive Voice Instances:** [count] ([percentage] of total sentences)
- [Location]: "[sentence]" -- [justified / convert to active]

**Needless Words Found:** [count]
- [Location]: "[phrase]" -- replace with "[replacement]"

**Negative Form Found:** [count]
- [Location]: "[phrase]" -- replace with "[positive form]"

**Vague Sentences Found:** [count]
- [Location]: "[sentence]" -- needs [concrete nouns / numbers / specifics]

**Loose Sentence Chains Found:** [count]
- [Location]: [description of the repeated structure]

**Separated Modifiers Found:** [count]
- [Location]: "[modifier]" is [n] words from "[target]"

**Weak Endings Found:** [count]
- [Location]: "[sentence ending]" -- [suggestion]