@lvlup-sw/axiom 0.2.4 → 0.2.6

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "axiom",
-  "version": "0.2.4",
-  "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.6",
+  "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.4",
+  "version": "0.2.6",
   "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

@@ -108,6 +108,30 @@ Each check has: ID, pattern, what it detects, severity, and false-positive guida
 
 ## DIM-6: Architecture
 
+### T-6.1a: Deep nesting
+- **Pattern:** Count indentation levels per function; flag functions with >3 levels of nesting
+- **Severity:** MEDIUM
+- **Detects:** Functions where business logic is buried under layers of conditional checks
+- **False positives:** Nesting from resource scoping (`try`/`with` blocks) or framework-required patterns
+
+### T-6.1b: Long functions
+- **Pattern:** Functions exceeding 50 lines (measured from signature to closing brace)
+- **Severity:** MEDIUM
+- **Detects:** Functions doing too much — multiple concerns in a single body
+- **False positives:** Functions with long but simple data declarations (mapping tables, configuration objects)
+
+### T-6.1c: Long parameter lists
+- **Pattern:** Functions with more than 4 parameters in the signature
+- **Severity:** MEDIUM
+- **Detects:** Functions with too many inputs, suggesting they handle multiple concerns or need an options object
+- **False positives:** Constructor functions in DI-heavy codebases where parameters are injected dependencies; callback-heavy APIs where signature is dictated by framework
+
+### T-6.1d: Deep inheritance
+- **Pattern:** `class\s+\w+\s+extends\s+` — flag when inheritance chain exceeds 2 levels
+- **Severity:** MEDIUM
+- **Detects:** Class hierarchies that would be simpler as composition
+- **False positives:** Framework-required inheritance (e.g., extending base controller classes); sealed hierarchies with exhaustive matching
+
 ### T-6.1: Circular imports
 - **Pattern:** Build import graph; detect cycles
 - **Severity:** HIGH
@@ -146,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/critique/SKILL.md

@@ -100,7 +100,17 @@ Identify modules with too many responsibilities:
 - Classes or modules that are modified in every feature branch (shotgun surgery indicator)
 - Modules that import from many unrelated domains
 
-#### 3e. Circular Dependency Identification
+#### 3e. Readability Patterns
+
+Evaluate code-level readability and structural clarity:
+
+- **DRY violations:** Duplicated logic across multiple locations that should be extracted
+- **Deep nesting:** Functions with excessive indentation that could use guard clauses / early returns
+- **Composition over inheritance:** Class hierarchies that would be simpler as composed components
+- **Parameter discipline:** Long parameter lists and boolean flags that obscure call-site meaning
+- For definitions, violation signals, and refactoring approaches, see `@skills/critique/references/readability-patterns.md`
+
+#### 3f. Circular Dependency Identification
 
 Detect import cycles between modules:
 
@@ -130,3 +140,4 @@ Format all findings per `@skills/backend-quality/references/findings-format.md`:
 - `@skills/backend-quality/references/findings-format.md` — Standard output format for findings
 - `@skills/critique/references/solid-principles.md` — SOLID principle definitions, violation signals, severity guide, and detection heuristics
 - `@skills/critique/references/dependency-patterns.md` — Dependency pattern catalog, coupling metrics, circular dependency detection, and layered architecture guidance
+- `@skills/critique/references/readability-patterns.md` — DRY, early returns, composition over inheritance, and parameter discipline

package/skills/critique/references/readability-patterns.md

@@ -0,0 +1,277 @@
+# Readability Patterns Reference
+
+Detection heuristics and severity guidance for code readability concerns beyond SOLID. These patterns address structural clarity at the function and expression level.
+
+---
+
+## DRY — Don't Repeat Yourself
+
+### Definition
+
+Every piece of knowledge should have a single, authoritative representation in the system. When the same logic appears in multiple places, a change to that logic requires finding and updating every copy — and missing one creates a bug.
+
+### Violation Signals
+
+1. Two or more functions with near-identical bodies differing only in variable names or literals
+2. Copy-pasted conditional chains (same `if/else` structure with different field names)
+3. Parallel data transformations that follow the same pattern but aren't abstracted
+4. Test setup code duplicated across multiple test files without extraction into a shared fixture
+5. Configuration or mapping objects repeated in multiple modules instead of imported from one source
+
+### When Duplication Is Acceptable
+
+Not all duplication violates DRY. Apply the **three uses rule** (see `@skills/distill/references/simplification-guide.md`):
+
+- **First occurrence:** Write it inline. Do not extract.
+- **Second occurrence:** Note the duplication but tolerate it. The pattern may be coincidental.
+- **Third occurrence:** Extract. You now have enough examples to see the true shape of the abstraction.
+
+**Also acceptable:**
+- Test assertions that happen to look similar but test different behaviors — readability in tests often outweighs DRY
+- Protocol handlers or route definitions that share structure but represent distinct endpoints — premature abstraction here creates "magic" dispatchers that are harder to understand
+- Two-line utility patterns (e.g., null-check-and-return) — the abstraction would be longer than the duplication
+
+### Severity Guide
+
+| Severity | When to assign |
+|----------|---------------|
+| **HIGH** | Duplicated business logic where a bug fix applied to one copy but not the other would cause incorrect behavior. |
+| **MEDIUM** | Duplicated structural patterns (>10 lines) across 3+ locations. The abstraction is clear but hasn't been extracted. |
+| **LOW** | Minor duplication (<10 lines) in 2 locations. Extraction would add more complexity than it removes. |
+
+### Detection Heuristics
+
+- Look for functions with the same control flow structure but different variable names
+- Search for identical error handling blocks across different catch clauses
+- Check for repeated object construction patterns (same keys, different values)
+- Compare test files for duplicated setup/teardown logic
+
+---
+
+## Early Returns and Guard Clauses
+
+### Definition
+
+Guard clauses handle edge cases and preconditions at the top of a function, returning or throwing early. This eliminates nesting and keeps the main logic path at the lowest indentation level.
+
+### The Problem with Deep Nesting
+
+```typescript
+// Deep nesting — hard to follow
+function processOrder(order: Order): Result {
+  if (order) {
+    if (order.items.length > 0) {
+      if (order.customer) {
+        if (order.customer.isActive) {
+          // ... actual business logic buried at 4 levels deep
+          const total = calculateTotal(order.items)
+          return { success: true, total }
+        } else {
+          return { success: false, error: 'Inactive customer' }
+        }
+      } else {
+        return { success: false, error: 'No customer' }
+      }
+    } else {
+      return { success: false, error: 'Empty order' }
+    }
+  } else {
+    return { success: false, error: 'No order' }
+  }
+}
+```
+
+```typescript
+// Guard clauses — preconditions handled upfront, main path is flat
+function processOrder(order: Order): Result {
+  if (!order) return { success: false, error: 'No order' }
+  if (order.items.length === 0) return { success: false, error: 'Empty order' }
+  if (!order.customer) return { success: false, error: 'No customer' }
+  if (!order.customer.isActive) return { success: false, error: 'Inactive customer' }
+
+  const total = calculateTotal(order.items)
+  return { success: true, total }
+}
+```
+
+### Violation Signals
+
+1. Functions with more than 3 levels of nesting
+2. `else` branches that contain only a return or throw (invert the condition and return early)
+3. Long `if` blocks followed by a short `else { return }` — the return should come first
+4. Nested `if` chains where each level checks a single condition (collapse into sequential guards)
+5. Functions where the main logic is indented 3+ levels deep
+
+### When to Keep Nesting
+
+- **Mutually exclusive branches with equal weight:** When both branches contain substantial logic (not just a return), `if/else` is clearer than early return
+- **Loop bodies with `continue`:** Using `continue` as a guard clause inside loops is the same pattern and equally valid, but excessive `continue` statements can fragment loop logic
+- **Transaction scoping:** When nesting represents a resource scope (e.g., `try` blocks wrapping database transactions), the nesting communicates the scope boundary
+
+### Severity Guide
+
+| Severity | When to assign |
+|----------|---------------|
+| **HIGH** | Function with 5+ levels of nesting. Main business logic is buried and hard to trace. |
+| **MEDIUM** | Function with 3-4 levels of nesting that could be flattened with guard clauses. |
+| **LOW** | Occasional unnecessary `else` after a return statement. Cosmetic but worth noting. |
+
+### Detection Heuristics
+
+- Measure maximum indentation depth per function — flag functions exceeding 3 levels
+- Search for `else { return` or `else { throw` patterns — these can almost always be inverted
+- Look for `if (condition) { ... long block ... } else { return }` — invert the condition
+- Count the ratio of guard-eligible checks to actual guards in functions with preconditions
+
+---
+
+## Composition Over Inheritance
+
+### Definition
+
+Favor assembling behavior from small, focused components rather than building deep class hierarchies. Inheritance creates tight coupling between parent and child classes; composition allows flexible recombination.
+
+### Why Inheritance Creates Problems
+
+- **Fragile base class:** Changes to the parent class ripple into all children, even when irrelevant to their specific behavior
+- **Forced inheritance of unwanted behavior:** Subclasses inherit all parent methods, even ones that don't apply (ISP violation in class form)
+- **Diamond problem:** Multiple inheritance paths create ambiguity about which parent's behavior to use
+- **Deep hierarchies obscure behavior:** Understanding what a class does requires reading the entire chain from root to leaf
+
+### Violation Signals
+
+1. Class hierarchies deeper than 2 levels (grandchild classes)
+2. Subclasses that override >50% of parent methods (the "is-a" relationship is wrong)
+3. Abstract base classes with only one concrete implementation (premature abstraction)
+4. Classes that extend a base class only to access a utility method (use composition or a standalone function)
+5. `super` calls that require understanding the parent's implementation details (leaky inheritance)
+6. "Template method" patterns where the base class controls flow and subclasses fill in hooks — often better expressed as a function accepting strategy callbacks
+
+### Composition Alternatives
+
+**Instead of inheritance for shared behavior:**
+```typescript
+// Inheritance approach — tight coupling
+class BaseRepository {
+  async findById(id: string) { /* shared query logic */ }
+  async save(entity: unknown) { /* shared persistence logic */ }
+}
+class UserRepository extends BaseRepository {
+  async findByEmail(email: string) { /* user-specific */ }
+}
+```
+
+```typescript
+// Composition approach — flexible, testable
+function createRepository(tableName: string) {
+  return {
+    findById: (id: string) => query(tableName, { id }),
+    save: (entity: unknown) => upsert(tableName, entity),
+  }
+}
+
+function createUserRepository() {
+  const base = createRepository('users')
+  return {
+    ...base,
+    findByEmail: (email: string) => query('users', { email }),
+  }
+}
+```
+
+**Instead of inheritance for variation:**
+```typescript
+// Strategy pattern via composition
+interface PricingStrategy {
+  calculate(items: Item[]): number
+}
+
+const standardPricing: PricingStrategy = {
+  calculate: (items) => items.reduce((sum, i) => sum + i.price, 0)
+}
+
+const discountPricing: PricingStrategy = {
+  calculate: (items) => items.reduce((sum, i) => sum + i.price * 0.9, 0)
+}
+
+// No inheritance needed — strategies are interchangeable values
+function checkout(items: Item[], pricing: PricingStrategy) {
+  return pricing.calculate(items)
+}
+```
+
+### When Inheritance Is Appropriate
+
+- **Framework requirements:** When a framework requires extending a base class (e.g., React class components, some ORM patterns). Use inheritance because the framework demands it, not by choice.
+- **True "is-a" relationships with shared state:** When the parent class manages state that all subclasses genuinely need, and subclasses extend rather than override behavior.
+- **Sealed hierarchies:** When the set of subclasses is closed and known (e.g., AST node types, event types). Inheritance + exhaustive pattern matching is a valid design.
+
+### Severity Guide
+
+| Severity | When to assign |
+|----------|---------------|
+| **HIGH** | Class hierarchy 3+ levels deep where subclasses override most parent behavior. The hierarchy is fighting against itself. |
+| **MEDIUM** | Abstract base class with one implementation, or base class used primarily as a bag of utility methods. Composition would be simpler. |
+| **LOW** | Shallow inheritance (1 level) that works but could be expressed as composition. Not causing active problems. |
+
+### Detection Heuristics
+
+- Count `extends` depth — flag hierarchies deeper than 2 levels
+- Look for abstract classes with exactly one concrete subclass
+- Search for `super.` calls in methods that also override the parent method — sign of fragile coupling
+- Check if subclasses use <50% of inherited methods — the inheritance may be for convenience, not design
+- Look for classes that extend a base class and immediately override the constructor to do something unrelated
+
+---
+
+## Parameter Discipline
+
+### Long Parameter Lists
+
+Functions with many parameters are hard to call correctly. The caller must remember the order, and boolean flags in the middle of a parameter list are especially error-prone.
+
+**Violation signals:**
+- Functions with more than 4 parameters
+- Boolean parameters that aren't self-documenting at the call site
+- Parameters that are always passed together (should be grouped into an object)
+
+**Refactoring approaches:**
+```typescript
+// Before: positional parameters, unclear at call site
+function createUser(name: string, email: string, isAdmin: boolean,
+  sendWelcome: boolean, teamId: string | null) { ... }
+
+createUser('Alice', 'a@b.com', true, false, 'team-1') // What do true, false mean?
+```
+
+```typescript
+// After: options object, self-documenting
+interface CreateUserOptions {
+  name: string
+  email: string
+  isAdmin?: boolean
+  sendWelcome?: boolean
+  teamId?: string
+}
+
+function createUser(options: CreateUserOptions) { ... }
+
+createUser({ name: 'Alice', email: 'a@b.com', isAdmin: true, teamId: 'team-1' })
+```
+
+### Boolean Parameters
+
+Boolean parameters are a special case of poor readability. At the call site, `true` and `false` carry no meaning without reading the function signature.
+
+**Alternatives:**
+- Use an options object (as above)
+- Use separate functions: `enableFeature()` / `disableFeature()` instead of `setFeature(enabled: boolean)`
+- Use string literals or enums: `format('compact')` instead of `format(true)`
+
+### Severity Guide
+
+| Severity | When to assign |
+|----------|---------------|
+| **HIGH** | Function with 6+ parameters, especially if multiple are booleans. Call sites are unreadable. |
+| **MEDIUM** | Function with 4-5 parameters where grouping into an object would improve clarity. |
+| **LOW** | Function with a boolean parameter that could be more expressive but is only called in 1-2 places. |

package/skills/distill/references/simplification-guide.md

@@ -36,10 +36,54 @@ Reference guide for reducing code complexity, identifying vestigial patterns, an
 ### Reducing Conditional Complexity
 
 - **Collapse nested conditionals:** Replace `if (a) { if (b) { ... } }` with `if (a && b) { ... }` when the nesting adds no clarity
-- **Use early returns:** Convert deep nesting into guard clauses that return/throw early
 - **Replace flag variables:** When a boolean flag is set and then checked once, inline the condition
 - **Simplify boolean expressions:** `if (x === true)` becomes `if (x)`; `if (!x === false)` becomes `if (x)`
 
+#### Early Returns and Guard Clauses
+
+Convert deep nesting into guard clauses that return or throw early. This is one of the highest-impact readability improvements available.
+
+**The principle:** Handle preconditions and edge cases at the top of the function, then let the main logic flow at the lowest indentation level.
+
+**Before — nested conditionals:**
+```typescript
+function getDiscount(customer: Customer): number {
+  if (customer) {
+    if (customer.isActive) {
+      if (customer.orders > 10) {
+        return 0.15
+      } else {
+        return 0.05
+      }
+    } else {
+      return 0
+    }
+  } else {
+    throw new Error('Customer required')
+  }
+}
+```
+
+**After — guard clauses:**
+```typescript
+function getDiscount(customer: Customer): number {
+  if (!customer) throw new Error('Customer required')
+  if (!customer.isActive) return 0
+
+  return customer.orders > 10 ? 0.15 : 0.05
+}
+```
+
+**Patterns to look for:**
+- `if (x) { ... long block ... } else { return y }` — invert: `if (!x) return y; ... long block ...`
+- `if (x) { if (y) { if (z) { ... } } }` — flatten: `if (!x) return; if (!y) return; if (!z) return; ...`
+- `else` after a `return` or `throw` — the `else` is unnecessary; remove it and dedent
+
+**When not to flatten:**
+- Both branches have substantial logic (not just returns) — `if/else` is clearer
+- The nesting represents resource scoping (e.g., transaction boundaries)
+- The conditions are not preconditions but genuinely branching logic paths
+
 ## Vestigial Pattern Identification
 
 ### Code Archaeology Approach

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 |