@lvlup-sw/axiom 0.2.5 → 0.2.7

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "axiom",
-  "version": "0.2.5",
-  "description": "Backend code quality skills for Claude Code. Six skills that audit, critique, harden, and simplify your architecture — the backend half of impeccable.",
+  "version": "0.2.7",
+  "description": "Backend code quality skills for Claude Code. Seven skills that audit, critique, harden, simplify, and humanize your architecture — the backend half of impeccable.",
   "author": {
     "name": "LevelUp Software"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lvlup-sw/axiom",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "Backend code quality skills for Claude Code",
   "type": "module",
   "scripts": {

package/skills/audit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: audit
-description: "Run a comprehensive backend quality audit across all seven dimensions. Orchestrates scan, critique, harden, distill, and verify skills, deduplicates findings, and produces a unified report with verdict. Use when assessing overall codebase health. Triggers: 'audit backend', 'full quality check', 'run audit', or /axiom:audit. Do NOT use for targeted checks — use individual skills instead."
+description: "Run a comprehensive backend quality audit across all eight dimensions. Orchestrates scan, critique, harden, distill, verify, and humanize skills, deduplicates findings, and produces a unified report with verdict. Use when assessing overall codebase health. Triggers: 'audit backend', 'full quality check', 'run audit', or /axiom:audit. Do NOT use for targeted checks — use individual skills instead."
 user-invokable: true
 metadata:
   author: lvlup-sw
@@ -14,7 +14,7 @@ metadata:
 
 ## Overview
 
-The anchor skill that orchestrates all other axiom skills to produce a comprehensive backend quality report. Runs deterministic checks and qualitative assessments across all 7 dimensions, deduplicates findings, computes per-dimension metrics, and delivers a unified verdict.
+The anchor skill that orchestrates all other axiom skills to produce a comprehensive backend quality report. Runs deterministic checks and qualitative assessments across all 8 dimensions, deduplicates findings, computes per-dimension metrics, and delivers a unified verdict.
 
 ## Triggers
 
@@ -52,6 +52,7 @@ Run each specialized skill in sequence, passing the scope:
 2. **`axiom:harden`** — Observability (DIM-2) + Resilience (DIM-7)
 3. **`axiom:distill`** — Hygiene (DIM-5) + Topology (DIM-1)
 4. **`axiom:verify`** — Test Fidelity (DIM-4) + Contracts (DIM-3)
+5. **`axiom:humanize`** — Prose Quality (DIM-8)
 
 Each skill produces findings in the standard format: `@skills/backend-quality/references/findings-format.md`
 
@@ -65,7 +66,7 @@ Merge findings from all skills using these rules:
 
 ### Step 5: Coverage Check
 
-Verify all 7 dimensions were assessed. If any dimension has zero findings and zero checks:
+Verify all 8 dimensions were assessed. If any dimension has zero findings and zero checks:
 - **Warning:** "DIM-N ({name}) was not assessed — no checks or findings produced"
 - This may indicate the scope doesn't contain code relevant to that dimension
 

package/skills/audit/references/composition-guide.md

@@ -13,6 +13,7 @@ The audit skill invokes a fixed set of specialized skills:
 | 3 | `axiom:harden` | Observability, Resilience |
 | 4 | `axiom:distill` | Hygiene, Topology |
 | 5 | `axiom:verify` | Test Fidelity, Contracts |
+| 6 | `axiom:humanize` | Prose Quality |
 
 **Execution order matters:** `scan` runs first so specialized skills can reference its deterministic findings when layering qualitative assessment.
 
@@ -41,7 +42,7 @@ When `scan` and a qualitative skill both flag the same issue, merge them. The de
 After deduplication, compute the coverage matrix:
 
 ```text
-For each dimension (DIM-1 through DIM-7):
+For each dimension (DIM-1 through DIM-8):
   - deterministic_checks: count of scan checks run for this dimension
   - qualitative_assessed: was a specialized skill invoked for this dimension?
   - finding_count: total findings (post-dedup)
@@ -83,7 +84,7 @@ const verdict = (HIGH_count > 0 || MEDIUM_count > 5)
 ### Finding Ordering
 
 Within each severity tier, order findings by:
-1. Dimension (DIM-1 first, DIM-7 last)
+1. Dimension (DIM-1 first, DIM-8 last)
 2. Evidence file path (alphabetical)
 3. Evidence line number (ascending)
 

package/skills/backend-quality/SKILL.md

@@ -15,7 +15,7 @@ This skill defines the shared foundation for all axiom backend quality skills. I
 
 ## Dimension Taxonomy
 
-Seven canonical quality dimensions: `@skills/backend-quality/references/dimensions.md`
+Eight canonical quality dimensions: `@skills/backend-quality/references/dimensions.md`
 
 | ID | Name | What it assesses |
 |----|------|-----------------|
@@ -26,6 +26,7 @@ Seven canonical quality dimensions: `@skills/backend-quality/references/dimensio
 | DIM-5 | Hygiene | Dead code, vestigial patterns, evolutionary leftovers |
 | DIM-6 | Architecture | SOLID, coupling, cohesion, dependency direction |
 | DIM-7 | Resilience | Resource management, timeouts, failure handling |
+| DIM-8 | Prose Quality | AI-writing patterns, documentation authenticity |
 
 ## Finding Format
 

package/skills/backend-quality/references/deterministic-checks.md

@@ -170,6 +170,68 @@ Each check has: ID, pattern, what it detects, severity, and false-positive guida
 - **Detects:** Retry logic that could loop forever
 - **False positives:** Loops with break conditions that aren't pattern-matched
 
+## DIM-8: Prose Quality
+
+### PQ-8.1: AI vocabulary clustering
+- **Pattern:** Count of `(additionally|crucial|delve|foster|garner|intricate|landscape|pivotal|tapestry|testament|underscore|vibrant)` per paragraph; flag if >=3
+- **Severity:** MEDIUM
+- **Detects:** Clustering of words disproportionately used by language models
+- **False positives:** Technical contexts where "landscape" means literal landscape, or "crucial" is genuinely appropriate
+
+### PQ-8.2: Chatbot collaborative artifacts
+- **Pattern:** `(I hope this helps|Of course!|Certainly!|You're absolutely right|Would you like|let me know if|here is a)`
+- **Severity:** HIGH
+- **Detects:** Chatbot correspondence language left in shipped content
+- **False positives:** Legitimate user-facing chat interfaces; FAQ sections
+
+### PQ-8.3: Knowledge-cutoff disclaimers
+- **Pattern:** `(as of (my|this|the) (last|latest)|up to my last training|based on available information|while specific details are (limited|scarce))`
+- **Severity:** HIGH
+- **Detects:** AI model disclaimers about incomplete knowledge left in documentation
+- **False positives:** Legitimate date-scoped statements ("as of the latest release")
+
+### PQ-8.4: Sycophantic openers
+- **Pattern:** `^(Great question|That's a great|Excellent point|Absolutely[!,]|What a (great|wonderful|fantastic))`
+- **Severity:** HIGH
+- **Detects:** People-pleasing language inappropriate for technical documentation
+- **False positives:** None in technical docs; rare in any professional writing
+
+### PQ-8.5: Em dash density
+- **Pattern:** Count of `\u2014` (em dash) per file; flag if density > 1 per 100 words
+- **Severity:** LOW
+- **Detects:** Overuse of em dashes mimicking punchy sales writing
+- **False positives:** Quoted dialogue; style guides that favor em dashes
+
+### PQ-8.6: Superficial -ing analyses
+- **Pattern:** `(highlighting|underscoring|emphasizing|ensuring|reflecting|symbolizing|contributing to|cultivating|fostering|encompassing|showcasing)\s+(the|its|a|an)`
+- **Severity:** MEDIUM
+- **Detects:** Present participle phrases tacked on for fake depth
+- **False positives:** Active voice descriptions of ongoing processes
+
+### PQ-8.7: Inflated significance
+- **Pattern:** `(serves as a testament|stands as a reminder|pivotal (role|moment)|indelible mark|key turning point|evolving landscape|setting the stage|focal point of)`
+- **Severity:** MEDIUM
+- **Detects:** Inflated language that elevates mundane topics to cosmic importance
+- **False positives:** Historical or genuinely significant events
+
+### PQ-8.8: Promotional language
+- **Pattern:** `(boasts a|in the heart of|groundbreaking|renowned|breathtaking|must-visit|stunning|nestled)`
+- **Severity:** MEDIUM
+- **Detects:** Loss of neutral tone, especially on cultural/heritage topics
+- **False positives:** Marketing copy where promotional tone is intentional
+
+### PQ-8.9: Filler phrases
+- **Pattern:** `(in order to|due to the fact that|at this point in time|in the event that|has the ability to|it is worth noting that|it is important to note)`
+- **Severity:** LOW
+- **Detects:** Wordy phrases that can be simplified
+- **False positives:** Legal or formal contexts where precision requires verbosity
+
+### PQ-8.10: Generic positive conclusions
+- **Pattern:** `(the future looks bright|exciting times|looking forward to|great potential|paving the way|on the right track)`
+- **Severity:** MEDIUM
+- **Detects:** Vague upbeat endings without substance
+- **False positives:** Genuine forward-looking statements with specific plans attached
+
 ## Extensibility
 
 Projects can add custom checks via `.axiom/checks.md` at the repo root. Format matches this file — one section per dimension, each check with pattern, severity, description, and false-positive guidance. Custom checks are loaded alongside the built-in catalog by the `scan` skill.

package/skills/backend-quality/references/dimensions.md

@@ -1,6 +1,6 @@
 # Backend Quality Dimensions
 
-Seven canonical dimensions for assessing backend architectural health. Each dimension is independently assessable — no dimension requires another's output to produce findings.
+Eight canonical dimensions for assessing backend architectural health. Each dimension is independently assessable — no dimension requires another's output to produce findings.
 
 ## DIM-1: Topology
 
@@ -196,11 +196,40 @@ Seven canonical dimensions for assessing backend architectural health. Each dime
 
 ---
 
+## DIM-8: Prose Quality
+
+**Definition:** The absence of detectable AI-writing patterns in documentation, comments, user-facing strings, and prose content. Prose quality violations erode trust, signal unreviewed AI output, and make content feel generic rather than purposeful.
+
+**Invariants:**
+- Documentation reads as written by a domain expert, not generated by a language model
+- No chatbot correspondence artifacts (sycophantic openers, "let me know" closers)
+- Technical writing is direct and specific, not padded with filler phrases or hedging
+
+**Detectable Signals:**
+- AI vocabulary clustering (additionally, crucial, delve, landscape, tapestry, testament, underscore, vibrant)
+- Collaborative communication artifacts ("I hope this helps", "Certainly!", "Would you like...")
+- Knowledge-cutoff disclaimers ("as of [date]", "based on available information")
+- Structural tells (em dash overuse, rule of three, inline-header vertical lists, title case headings)
+- Content inflation (inflated significance, promotional language, superficial -ing analyses)
+- Filler and hedging (generic positive conclusions, excessive hedging, wordy phrases)
+
+**Severity Guide:**
+- **HIGH:** Chatbot artifacts or knowledge-cutoff disclaimers left in shipped content
+- **MEDIUM:** AI vocabulary clustering (3+ AI-typical words in a paragraph) or structural tells
+- **LOW:** Isolated filler phrases or mild hedging
+
+**Examples:**
+- Violation: "This crucial module serves as a testament to the team's commitment to fostering robust architecture. It delves into the intricate tapestry of event-sourced workflows."
+- Healthy: "This module handles event-sourced workflow state. It stores events in SQLite and rebuilds state on read."
+
+---
+
 ## Dimension Independence
 
 Each dimension can be assessed in isolation. However, some findings may span multiple dimensions:
 
 - A lazy fallback constructor (DIM-1: Topology) may also be a silent error (DIM-2: Observability)
 - Dead code (DIM-5: Hygiene) may also be a test fidelity issue if tests reference it (DIM-4)
+- AI-generated prose (DIM-8: Prose Quality) may also be a hygiene issue if it contains dead documentation (DIM-5)
 
 When a finding spans dimensions, it should be reported under the **primary** dimension (the one most directly violated) with a cross-reference note. The `audit` skill handles deduplication when the same evidence appears under multiple dimensions.

package/skills/humanize/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: humanize
+description: "Scan for AI writing patterns in markdown, docs, comments, and user-facing strings. Detects 24 cataloged AI-writing tells across content, language, style, communication, and filler categories. Triggers: 'check prose', 'AI writing', 'humanize', or /axiom:humanize. Do NOT use for code quality — use other axiom skills."
+user-invokable: true
+metadata:
+  author: lvlup-sw
+  version: 0.1.0
+  category: assessment
+  dimensions:
+    - prose-quality
+---
+
+# Humanize — Prose Quality Assessment
+
+## Overview
+
+Detects signs of AI-generated writing in prose content. Based on Wikipedia's "Signs of AI writing" guide maintained by WikiProject AI Cleanup. Covers 24 patterns across 5 categories: content, language/grammar, style, communication, and filler/hedging.
+
+## Triggers
+
+**Use when:**
+- Reviewing documentation, README files, or user-facing copy
+- Checking comments and docstrings for AI tells
+- User says "humanize", "check prose", "AI writing patterns", "de-slop"
+
+**Do NOT use when:**
+- Reviewing code logic or architecture (use `axiom:critique`)
+- Checking error handling (use `axiom:harden`)
+- Running full quality audit (use `axiom:audit`, which includes humanize)
+
+## Process
+
+### Step 1: Scope Resolution
+
+Determine assessment scope:
+- **File:** Assess a single file
+- **Directory:** Assess all prose-containing files (recursive)
+- **Codebase:** Assess the entire project
+
+Default file scope: `*.md`, `*.txt`, `*.mdx`, plus comments and user-facing strings in source files (`*.ts`, `*.js`, `*.py`, etc.).
+
+Exclude: `node_modules/`, `dist/`, `.git/`, `CHANGELOG.md`, lock files, binary files, generated files.
+
+### Step 2: Deterministic Scan
+
+Run `axiom:scan` with `dimensions: prose-quality` for the resolved scope. This executes the PQ-* check catalog against the content.
+
+### Step 3: Qualitative Assessment
+
+Layer qualitative assessment on top of scan results:
+- Read flagged sections in context -- some patterns are acceptable in certain contexts
+- Check for pattern clustering (multiple AI tells in the same paragraph/section is worse than isolated occurrences)
+- Assess overall tone -- does the content read as expert-written or machine-generated?
+- Apply false-positive filtering per guidance in `@skills/humanize/references/ai-writing-patterns.md`
+
+### Step 4: Produce Findings
+
+Output findings in standard format: `@skills/backend-quality/references/findings-format.md`
+
+Each finding includes:
+- `dimension: "prose-quality"`
+- `severity: HIGH | MEDIUM | LOW` per `@skills/humanize/references/severity-guide.md`
+- `title`: Pattern name and location
+- `evidence`: File path and line numbers
+- `explanation`: What pattern was detected and why it matters
+- `suggestion`: Concrete rewrite suggestion
+
+## Error Handling
+
+- **No prose files in scope:** Return "No prose content found in scope" with no findings
+- **Binary/generated files:** Skip silently
+- **Large files (>10K lines):** Sample first 1000 and last 1000 lines
+
+## References
+
+- Pattern catalog: `@skills/humanize/references/ai-writing-patterns.md`
+- Severity mapping: `@skills/humanize/references/severity-guide.md`
+- Finding format: `@skills/backend-quality/references/findings-format.md`
+- Dimension taxonomy: `@skills/backend-quality/references/dimensions.md`

package/skills/humanize/references/ai-writing-patterns.md

@@ -0,0 +1,243 @@
+# AI Writing Patterns Catalog
+
+24 cataloged patterns for detecting AI-generated prose, organized into 5 categories. Based on Wikipedia's "Signs of AI writing" guide maintained by WikiProject AI Cleanup.
+
+---
+
+## Category 1: Content Patterns
+
+### PQ-1.1: Inflated Significance
+
+- **Detection keywords/regex:** `(serves as a testament|pivotal (role|moment)|indelible mark|setting the stage|key turning point|evolving landscape)`
+- **Problem:** Elevates mundane topics to cosmic importance. AI models default to grandiose framing because training data over-represents formal and promotional writing.
+- **Before:** "This module serves as a testament to the team's commitment to fostering robust architecture."
+- **After:** "This module handles event routing."
+- **False-positive guidance:** Historical or genuinely significant events may warrant strong language. If the subject is a literal turning point (e.g., a major version migration), the phrase may be appropriate.
+
+### PQ-1.2: Notability Emphasis
+
+- **Detection keywords/regex:** `(independent coverage|leading expert|active social media presence|widely recognized|notable for)`
+- **Problem:** Asserts notability without evidence. AI models insert Wikipedia-style notability markers to make subjects sound important.
+- **Before:** "The library has received independent coverage from leading experts in the field."
+- **After:** "The library is used by 200+ projects on GitHub."
+- **False-positive guidance:** Legitimate when backed by specific citations. Flag only when the claim is vague or unsourced.
+
+### PQ-1.3: Superficial -ing Analyses
+
+- **Detection keywords/regex:** `(highlighting|underscoring|emphasizing|ensuring|reflecting|symbolizing|contributing to|cultivating|fostering|encompassing|showcasing)\s+(the|its|a|an)`
+- **Problem:** Present participle phrases tacked on to create an illusion of depth. The -ing verb adds no information -- it just restates the obvious in fancier terms.
+- **Before:** "The error handler catches exceptions, ensuring the application remains stable while highlighting the importance of robust error handling."
+- **After:** "The error handler catches exceptions and returns a 500 status code."
+- **False-positive guidance:** Active voice descriptions of ongoing processes are fine ("the service is currently processing requests"). Flag when the -ing phrase adds no new information.
+
+### PQ-1.4: Promotional Language
+
+- **Detection keywords/regex:** `(boasts a|vibrant|rich\s+(history|tradition|culture|ecosystem)|profound|nestled|in the heart of|groundbreaking|renowned|breathtaking|must-visit|stunning)`
+- **Problem:** Loss of neutral, technical tone. AI models default to promotional language especially for cultural, geographic, or heritage topics.
+- **Before:** "The framework boasts a vibrant ecosystem of plugins and a rich tradition of community-driven development."
+- **After:** "The framework has 340 plugins maintained by 50+ contributors."
+- **False-positive guidance:** Marketing copy where promotional tone is intentional. Technical docs should almost never use these words.
+
+### PQ-1.5: Vague Attributions
+
+- **Detection keywords/regex:** `(Industry reports|Observers have cited|Experts argue|Some critics argue|Many believe|It is widely believed|According to sources)`
+- **Problem:** Creates false authority by attributing claims to unnamed experts. AI models use vague attribution when they lack specific sources.
+- **Before:** "Experts argue that this approach represents a paradigm shift."
+- **After:** "Martin Fowler's 2019 article 'Microservices Trade-Offs' argues this approach reduces deployment coupling."
+- **False-positive guidance:** Legitimate when the vagueness is intentional (e.g., summarizing a debate without taking sides). Flag when used to bolster a specific claim.
+
+### PQ-1.6: Formulaic Sections
+
+- **Detection keywords/regex:** `(Despite its.*faces several challenges|Despite these challenges|Future Outlook|Looking Ahead|In Conclusion)`
+- **Problem:** Template-like section transitions that signal generated structure. Real writers don't mechanically alternate between positive and negative sections.
+- **Before:** "Despite its many strengths, the framework faces several challenges. Despite these challenges, the future looks bright."
+- **After:** "Two open issues affect production use: memory leaks under high concurrency (#234) and missing ARM64 support (#567)."
+- **False-positive guidance:** "In Conclusion" is conventional in academic writing. Flag primarily in technical documentation and README files.
+
+---
+
+## Category 2: Language/Grammar Patterns
+
+### PQ-2.1: AI Vocabulary Words
+
+- **Detection keywords/regex:** `(additionally|align with|crucial|delve|emphasizing|enduring|enhance|fostering|garner|highlight\b|interplay|intricate|intricacies|key\s+(aspect|component|feature|element)|landscape\b|pivotal|showcase|tapestry|testament|underscore\b|valuable|vibrant)`
+- **Problem:** These words appear far more frequently in AI output than in human writing. Individually they are fine; clustered together they create an unmistakable AI fingerprint.
+- **Before:** "This crucial module delves into the intricate tapestry of event-sourced workflows, highlighting the interplay between producers and consumers."
+- **After:** "This module stores events in SQLite and rebuilds state on read."
+- **False-positive guidance:** Any single occurrence is fine. Flag when 3+ appear in the same paragraph. In technical writing, "key" as an adjective and "landscape" as a metaphor are the most common false positives.
+
+### PQ-2.2: Copula Avoidance
+
+- **Detection keywords/regex:** `(serves as|stands as|marks a|represents a|constitutes a|functions as|acts as a)\s+(a |an |the )`
+- **Problem:** AI models avoid simple "is/are" constructions in favor of fancier verbs. This makes prose feel stilted and over-formal.
+- **Before:** "This module serves as a bridge between the event store and the query layer."
+- **After:** "This module is the bridge between the event store and the query layer." (Or better: "This module connects the event store to the query layer.")
+- **False-positive guidance:** "Acts as" and "functions as" are sometimes genuinely clearer than "is" when describing behavior rather than identity.
+
+### PQ-2.3: Negative Parallelisms
+
+- **Detection keywords/regex:** `(Not only.*but (also)?|It's not just about.*it's (also)?|more than just|goes beyond)`
+- **Problem:** Formulaic rhetorical structure that AI uses to build artificial momentum. Rarely adds meaning.
+- **Before:** "It's not just about handling errors, it's about building a culture of reliability."
+- **After:** "The error handler retries transient failures and circuits open after 3 consecutive timeouts."
+- **False-positive guidance:** Legitimate in persuasive writing (blog posts, conference talks). Flag in technical docs and code comments.
+
+### PQ-2.4: Rule of Three Overuse
+
+- **Detection keywords/regex:** Three comma-separated items in a row, especially adjectives or abstract nouns. Manual check -- no single regex.
+- **Problem:** AI models force ideas into groups of three for rhetorical effect, even when only two points exist or four would be more accurate.
+- **Before:** "The system is fast, reliable, and scalable." (when only speed was measured)
+- **After:** "The system handles 10K requests/second with p99 latency under 50ms."
+- **False-positive guidance:** Three items is often natural. Flag only when items feel padded to reach three, or when the third item is vague/generic.
+
+### PQ-2.5: Elegant Variation
+
+- **Detection keywords/regex:** Manual check -- look for excessive synonym cycling within a paragraph (e.g., "users"/"individuals"/"people"/"stakeholders" all referring to the same group).
+- **Problem:** AI models cycle through synonyms to avoid repetition, creating confusion about whether different terms refer to different things.
+- **Before:** "Users configure the system. Individuals can customize their preferences. People set up notifications. Stakeholders manage access."
+- **After:** "Users configure the system, customize preferences, set up notifications, and manage access."
+- **False-positive guidance:** Technical writing should use consistent terms. Some variation is natural in longer prose. Flag when variation creates ambiguity.
+
+### PQ-2.6: False Ranges
+
+- **Detection keywords/regex:** `(from\s+\w+\s+to\s+\w+|range from|spanning from)`
+- **Problem:** AI creates artificial ranges where the endpoints are not on a meaningful scale. "From beginners to experts" or "from development to production" are usually filler.
+- **Before:** "The tool serves everyone from beginners to seasoned professionals."
+- **After:** "The tool requires no prior experience with event sourcing."
+- **False-positive guidance:** Legitimate when describing an actual continuum with meaningful endpoints. Flag when the range is vague or the endpoints are not comparable.
+
+---
+
+## Category 3: Style Patterns
+
+### PQ-3.1: Em Dash Overuse
+
+- **Detection keywords/regex:** Count of `\u2014` (em dash) per file; flag if density > 1 per 100 words.
+- **Problem:** ChatGPT overuses em dashes to create punchy, sales-copy-like rhythm. Natural writing uses them sparingly.
+- **Before:** "The system handles events -- all of them -- in real time -- no exceptions."
+- **After:** "The system handles all events in real time."
+- **False-positive guidance:** Quoted dialogue and some editorial styles favor em dashes. Check overall density rather than flagging individual occurrences.
+
+### PQ-3.2: Boldface Overuse
+
+- **Detection keywords/regex:** Count of `\*\*[^*]+\*\*` per section; flag if >3 bold phrases per paragraph.
+- **Problem:** AI models mechanically emphasize phrases. Too much boldface reduces its impact and creates visual noise.
+- **Before:** "The **event store** provides **reliable** persistence with **guaranteed** ordering and **automatic** compaction."
+- **After:** "The event store provides reliable persistence with guaranteed ordering and automatic compaction."
+- **False-positive guidance:** Reference docs and API documentation often use bold for parameter names. Flag only in prose paragraphs, not in structured reference material.
+
+### PQ-3.3: Inline-Header Vertical Lists
+
+- **Detection keywords/regex:** `^\s*[-*]\s+\*\*[^*]+\*\*:` (bulleted items with bolded headers followed by colons)
+- **Problem:** AI defaults to this format for any list, even when a simple bulleted list or a paragraph would be clearer. The pattern creates unnecessary visual weight.
+- **Before:**
+  ```
+  - **Performance:** The system is fast
+  - **Reliability:** The system is reliable
+  - **Scalability:** The system scales
+  ```
+- **After:** "The system is fast, reliable, and scales horizontally."
+- **False-positive guidance:** This format is appropriate for glossaries, API parameter docs, and reference material. Flag when used for simple lists that would read better as prose.
+
+### PQ-3.4: Title Case Headings
+
+- **Detection keywords/regex:** Headings where all major words are capitalized (e.g., `^#+\s+([A-Z][a-z]+\s+){2,}[A-Z]`)
+- **Problem:** AI defaults to title case headings. Most modern style guides (Google, Microsoft, AP) recommend sentence case for headings in technical writing.
+- **Before:** `## Getting Started With Event Sourcing`
+- **After:** `## Getting started with event sourcing`
+- **False-positive guidance:** Title case is correct for proper nouns, product names, and some style guides (APA). This is a style preference, not a hard rule. Flag only when the project's own style guide prefers sentence case.
+
+### PQ-3.5: Emojis in Prose
+
+- **Detection keywords/regex:** Unicode emoji characters in headings or bullet points (excluding code blocks and quoted strings).
+- **Problem:** AI models decorate headings and lists with emojis. Professional technical writing almost never uses emojis in headings or body text.
+- **Before:** "## Features", "- Fast performance", "- Easy setup"
+- **After:** "## Features", "- Fast performance", "- Easy setup" (identical but without emojis)
+- **False-positive guidance:** Some projects intentionally use emojis (changelogs, README badges). Check project conventions before flagging.
+
+### PQ-3.6: Curly Quotation Marks
+
+- **Detection keywords/regex:** `[\u2018\u2019\u201C\u201D]` (Unicode curly single and double quotes)
+- **Problem:** ChatGPT uses curly (typographic) quotation marks instead of straight quotes. In code-adjacent documentation, straight quotes are standard.
+- **Before:** \u201CThis is a string\u201D
+- **After:** "This is a string"
+- **False-positive guidance:** Curly quotes are correct in published prose (books, articles). Flag only in technical documentation and code-adjacent content.
+
+---
+
+## Category 4: Communication Patterns
+
+### PQ-4.1: Collaborative Artifacts
+
+- **Detection keywords/regex:** `(I hope this helps|Of course!|Certainly!|You're absolutely right|Would you like|let me know if|here is a|feel free to|don't hesitate to|happy to help)`
+- **Problem:** Chatbot correspondence language left in shipped content. These phrases only make sense in a conversation between a user and an AI assistant.
+- **Before:** "I hope this helps! Let me know if you'd like me to explain anything else."
+- **After:** (Delete entirely -- this is chatbot conversation, not documentation.)
+- **False-positive guidance:** Legitimate in user-facing chat interfaces and FAQ sections where conversational tone is intentional. Flag in all other documentation.
+
+### PQ-4.2: Knowledge-Cutoff Disclaimers
+
+- **Detection keywords/regex:** `(as of (my|this|the) (last|latest)|up to my last training|based on available information|while specific details are (limited|scarce)|at the time of (writing|this response))`
+- **Problem:** AI model disclaimers about incomplete knowledge left in documentation. These reveal unreviewed AI output.
+- **Before:** "As of my last training update, the API supports three endpoints."
+- **After:** "The API supports three endpoints (v2.3.0)."
+- **False-positive guidance:** "As of the latest release" or "at the time of writing" with a specific date are legitimate. Flag only when the phrasing reveals an AI knowledge cutoff.
+
+### PQ-4.3: Sycophantic Tone
+
+- **Detection keywords/regex:** `(Great question|That's a great|Excellent point|Absolutely[!,]|What a (great|wonderful|fantastic)|You're right to|Good thinking)`
+- **Problem:** People-pleasing language that is inappropriate in technical documentation. Signals unreviewed AI output pasted directly from a chat session.
+- **Before:** "Great question! The event store uses SQLite for persistence."
+- **After:** "The event store uses SQLite for persistence."
+- **False-positive guidance:** None in technical docs. Rare in any professional writing. Almost always an AI tell.
+
+---
+
+## Category 5: Filler/Hedging Patterns
+
+### PQ-5.1: Filler Phrases
+
+- **Detection keywords/regex:** `(in order to|due to the fact that|at this point in time|in the event that|has the ability to|it is worth noting that|it is important to note|it should be noted that|needless to say)`
+- **Problem:** Wordy phrases that can be simplified without losing meaning. AI models use them to pad output length.
+- **Before:** "In order to ensure that the system has the ability to handle errors, it is important to note that..."
+- **After:** "To handle errors..."
+- **Simplification table:**
+  | Filler | Replacement |
+  |--------|-------------|
+  | In order to | To |
+  | Due to the fact that | Because |
+  | At this point in time | Now |
+  | In the event that | If |
+  | Has the ability to | Can |
+  | It is worth noting that | (delete or rephrase) |
+  | It is important to note | (delete or rephrase) |
+- **False-positive guidance:** Legal or formal contexts where precision requires verbosity. "In order to" is sometimes clearer than "to" when the infinitive could be misread.
+
+### PQ-5.2: Excessive Hedging
+
+- **Detection keywords/regex:** `(could potentially|might possibly|may potentially|it could be argued|one might suggest|there is a possibility|to some extent|in some cases|it is possible that)`
+- **Problem:** Over-qualifying statements strips them of usefulness. Technical docs should be direct.
+- **Before:** "It could potentially be argued that this approach might possibly offer some advantages in certain scenarios."
+- **After:** "This approach reduces memory usage by 40%."
+- **False-positive guidance:** Some hedging is appropriate when genuinely uncertain (e.g., "performance may vary depending on hardware"). Flag stacked hedges (2+ qualifying phrases in one sentence).
+
+### PQ-5.3: Generic Positive Conclusions
+
+- **Detection keywords/regex:** `(the future looks bright|exciting times|looking forward to|great potential|paving the way|on the right track|poised for|well-positioned)`
+- **Problem:** Vague upbeat endings without substance. AI models default to optimistic conclusions that say nothing specific.
+- **Before:** "The future looks bright for this framework, and we look forward to exciting times ahead."
+- **After:** "The v3.0 roadmap includes WebSocket support (Q2) and horizontal scaling (Q3)."
+- **False-positive guidance:** Genuine forward-looking statements with specific plans attached are fine. Flag only when the conclusion is vague and could apply to anything.
+
+---
+
+## Frequency-Based Escalation
+
+Not all occurrences warrant the same severity. Use these escalation rules:
+
+| Pattern Type | 1 occurrence | 3+ in paragraph | 5+ in paragraph | 3+ in file |
+|-------------|-------------|-----------------|-----------------|------------|
+| AI vocabulary (PQ-2.1) | Ignore | MEDIUM | HIGH | MEDIUM |
+| Structural tells (PQ-3.x) | LOW | MEDIUM | MEDIUM | MEDIUM |
+| Filler phrases (PQ-5.1) | Ignore | LOW | MEDIUM | LOW |
+| Communication (PQ-4.x) | HIGH | HIGH | HIGH | HIGH |

package/skills/humanize/references/severity-guide.md

@@ -0,0 +1,98 @@
+# Prose Quality Severity Guide
+
+Severity mappings for each AI-writing pattern, with rationale and frequency-based escalation rules.
+
+---
+
+## HIGH Severity
+
+Dead giveaways of unreviewed AI output. These should never appear in shipped content.
+
+| Pattern ID | Pattern Name | Rationale |
+|-----------|-------------|-----------|
+| PQ-4.1 | Collaborative artifacts | Chatbot language ("I hope this helps") in documentation is an obvious copy-paste from an AI session |
+| PQ-4.2 | Knowledge-cutoff disclaimers | "As of my last training update" in docs reveals AI-generated content that was never reviewed |
+| PQ-4.3 | Sycophantic tone | "Great question!" in technical docs is inappropriate in any context |
+| PQ-2.1 | AI vocabulary (5+ cluster) | Five or more AI-typical words in one paragraph creates an unmistakable AI fingerprint |
+
+---
+
+## MEDIUM Severity
+
+Patterns that cluster to create an AI-generated feel. Individually tolerable, but multiple occurrences signal low editorial effort.
+
+| Pattern ID | Pattern Name | Rationale |
+|-----------|-------------|-----------|
+| PQ-1.1 | Inflated significance | Grandiose framing makes mundane topics sound absurd |
+| PQ-1.3 | Superficial -ing analyses | Participial phrases that restate the obvious in fancier terms |
+| PQ-1.4 | Promotional language | Loss of neutral, technical tone |
+| PQ-2.1 | AI vocabulary (3-4 cluster) | Noticeable AI fingerprint but not overwhelming |
+| PQ-2.2 | Copula avoidance | Over-formal "serves as" / "stands as" instead of simple "is" |
+| PQ-2.3 | Negative parallelisms | "Not only...but also" rhetorical formula |
+| PQ-5.3 | Generic positive conclusions | Vague upbeat endings with no substance |
+| PQ-1.5 | Vague attributions | False authority via unnamed experts |
+| PQ-1.6 | Formulaic sections | Template-like section transitions |
+| PQ-2.4 | Rule of three overuse | Forced triadic groupings |
+| PQ-2.6 | False ranges | Artificial ranges with non-comparable endpoints |
+| PQ-1.2 | Notability emphasis | Unsubstantiated notability claims |
+
+---
+
+## LOW Severity
+
+Minor style issues. Worth fixing in a polish pass but not urgent.
+
+| Pattern ID | Pattern Name | Rationale |
+|-----------|-------------|-----------|
+| PQ-3.1 | Em dash overuse | Style preference; only a problem at high density |
+| PQ-3.5 | Emojis in prose | May be intentional per project conventions |
+| PQ-5.1 | Filler phrases (isolated) | Single occurrences of wordy phrases are minor |
+| PQ-5.2 | Excessive hedging (isolated) | Some hedging is appropriate for uncertainty |
+| PQ-3.2 | Boldface overuse | Visual noise but does not affect meaning |
+| PQ-3.3 | Inline-header vertical lists | Format preference; appropriate in some contexts |
+| PQ-3.4 | Title case headings | Style guide dependent |
+| PQ-3.6 | Curly quotation marks | Typographic preference |
+| PQ-2.5 | Elegant variation | Confusing synonym cycling |
+
+---
+
+## Frequency-Based Escalation Rules
+
+Base severity can be escalated based on pattern density:
+
+### AI Vocabulary (PQ-2.1)
+- **1 occurrence in paragraph:** Ignore (no finding)
+- **3-4 occurrences in paragraph:** MEDIUM
+- **5+ occurrences in paragraph:** HIGH
+- **3+ occurrences across file (non-clustered):** MEDIUM
+
+### Structural Tells (PQ-3.x)
+- **1-2 occurrences in file:** LOW
+- **3+ occurrences in file:** MEDIUM
+
+### Filler Phrases (PQ-5.1)
+- **1 occurrence in paragraph:** Ignore
+- **3+ in paragraph:** LOW
+- **5+ in paragraph:** MEDIUM
+- **3+ across file:** LOW
+
+### Communication Patterns (PQ-4.x)
+- **Any occurrence:** HIGH (no escalation needed; always critical)
+
+### Content Patterns (PQ-1.x)
+- **Isolated occurrence:** Base severity
+- **3+ in same section:** Escalate one level (LOW -> MEDIUM, MEDIUM -> HIGH)
+
+---
+
+## Context Modifiers
+
+Severity may be adjusted based on where the pattern appears:
+
+| Context | Modifier |
+|---------|----------|
+| User-facing documentation (README, guides) | No change (base severity) |
+| Internal comments and docstrings | Reduce one level |
+| Marketing copy or landing pages | Promotional language (PQ-1.4) acceptable; reduce to LOW |
+| Changelogs and release notes | Formulaic sections (PQ-1.6) acceptable; reduce to LOW |
+| Chat interface copy | Collaborative artifacts (PQ-4.1) acceptable; reduce to LOW |