@iceinvein/agent-skills 0.1.37 → 0.1.39

package/skills/cover-letter-rewrite/SKILL.md

@@ -1,15 +1,13 @@
 ---
 name: cover-letter-rewrite
 description: >
-  Revise an existing cover letter by auditing it first, then applying targeted
-  fixes: humanize AI-sounding prose, align claims with the resume, tighten
-  structure, adjust tone to match an active persona, or improve job-description
-  coverage. Preserves the applicant's voice where it's already working. Supports
-  focused passes with --focus humanize|align|tighten|structure|tone. Produces
-  markdown, DOCX, and PDF outputs. Use when the user says "rewrite cover letter",
-  "improve cover letter", "humanize cover letter", "fix cover letter", "tighten
-  cover letter", "this cover letter sounds AI", "make this less generic", "make
-  this more specific", or shares a letter and asks for edits.
+  Use when the user asks to rewrite, improve, humanize, fix, or tighten an
+  existing cover letter ("this sounds AI", "make it less generic"), or shares
+  a letter asking for edits. Audit-driven targeted revision that preserves the
+  applicant's voice where it works; focus passes via --focus
+  humanize|align|tighten|structure|tone. Emits markdown, DOCX, and PDF. NOT
+  for writing from scratch (cover-letter-write) or score-only feedback
+  (cover-letter-audit).
 argument-hint: "<letter-file> [--resume <file>] [--jd <file|url|text>] [--focus humanize|align|tighten|structure|tone] [--length short|standard|long] [--out <dir>]"
 ---
 
@@ -24,11 +22,12 @@ targeting the weakest category (or the user's --focus).
 - **Rewrite**: user has a draft they like the bones of. Keep their voice,
   fix specific issues.
 - **Write**: user has resume + JD and nothing else, or the existing letter is
-  so generic it would be easier to start fresh (audit score below 50 with
-  multiple critical issues).
+  so generic it would be easier to start fresh (audit score below 60, the
+  "Rewrite" band in cover-letter-audit's rating table, with multiple critical
+  issues).
 
 If the user asks to "improve" or "fix" a letter, default to rewrite. If the
-letter scores below 50 with fabrication or complete topic drift, suggest a
+letter scores below 60 with fabrication or complete topic drift, suggest a
 fresh `/cover-letter write` instead.
 
 ## Inputs
@@ -50,6 +49,7 @@ Flags:
 - `--out <dir>` (default `./cover-letters/`).
 - `--preserve-voice` (stricter; forbid changes outside the flagged issues).
 - `--diff` (emit a unified diff between original and rewrite alongside files).
+- `--show-audit` (print the full before/after audit reports instead of the one-line score summaries).
 
 If resume or JD is missing and would be needed for the requested focus,
 either ask for it or proceed with a caveat (for example, `--focus humanize`
@@ -149,8 +149,9 @@ Actions:
   delivering results" becomes "Shipped three products to production in the
   last two years" (or similar; use real resume content).
 - Remove em-dashes; replace with period or comma or parentheses.
-- Add burstiness: introduce at least one short sentence (under 10 words) per
-  paragraph, and ensure at least one long sentence (over 20 words) per letter.
+- Add burstiness to the level the audit scores for: at least one short
+  sentence (under 10 words) AND one long sentence (over 20 words) per
+  paragraph, with sentence-length standard deviation >= 5.
 - Raise TTR: replace repeated nouns and verbs with synonyms the applicant
   would actually use.
 - Cut hedging and throat-clearing ("I would like to", "I believe", "it is
@@ -229,8 +230,9 @@ Actions:
 ### align focus
 
 The JD lists "experience with Kafka" as a must-have. The original letter
-doesn't mention it. The resume lists "migrated order service to Kafka-backed
-event sourcing (2M events/day)". Rewrite adds a single clause:
+doesn't mention it. The resume lists, under the Shopify role, "migrated order
+service to Kafka-backed event sourcing (2M events/day)". Rewrite adds a single
+clause (every fact in it, including the employer, traces to the resume):
 
 **Before:**
 

package/skills/cover-letter-rewrite/skill.json

@@ -1,10 +1,15 @@
 {
   "name": "cover-letter-rewrite",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Audit-driven targeted rewrite of an existing cover letter. Focus modes: humanize, align, tighten, structure, tone; preserves voice where it already works",
   "author": "iceinvein",
   "type": "prompt",
-  "tools": ["claude", "cursor", "codex", "gemini"],
+  "tools": [
+    "claude",
+    "cursor",
+    "codex",
+    "gemini"
+  ],
   "files": {
     "prompt": "SKILL.md"
   },

package/skills/cover-letter-write/SKILL.md

@@ -1,16 +1,13 @@
 ---
 name: cover-letter-write
 description: >
-  Generate a cover letter from a resume and a job description. Accepts resume and
-  JD as PDF, DOCX, markdown/MDX, URL, or pasted text. Produces markdown, DOCX, and
-  PDF outputs. Enforces human-sounding prose (varied sentence length, concrete
-  verbs, no filler openers), aligns every claim to a resume bullet, and covers the
-  top job-description requirements without keyword stuffing. Respects active
-  writing persona if one is set via /cover-letter persona use. Use when the user
-  says "write cover letter", "draft cover letter", "generate cover letter", "new
-  cover letter", "cover letter for <role>", or shares a resume and job description
-  together. Even if the user phrases it as "make me a cover letter" or "help me
-  apply to X", trigger this skill.
+  Use when the user asks to write, draft, or generate a cover letter ("write
+  cover letter", "cover letter for <role>", "make me a cover letter"), or
+  shares a resume and job description together wanting an application letter.
+  Generates a letter from resume + JD (each as PDF, DOCX, markdown/MDX, URL, or
+  pasted text), aligned to resume evidence and human-sounding, emitting
+  markdown, DOCX, and PDF. NOT for scoring an existing letter
+  (cover-letter-audit) or revising one (cover-letter-rewrite).
 argument-hint: "--resume <file> --jd <file|url|text> [--length short|standard|long] [--out <dir>]"
 ---
 
@@ -122,7 +119,8 @@ For each gap (must-have with no resume evidence), decide:
 Check `~/.config/cover-letter/active-persona`. If a persona is active and the
 user did not override with `--tone`, load that persona JSON.
 
-Without a persona, use these defaults:
+Without a persona, use these defaults (these mirror the "Mid / default"
+values in cover-letter-persona's schema; that file is the source of truth):
 
 | Setting | Default |
 |---------|---------|
@@ -133,7 +131,7 @@ Without a persona, use these defaults:
 | Passive voice cap | 10% |
 | Readability | Flesch grade 8-10 |
 
-If the JD signals a clear tone (a startup posting that uses "ya'll" and
+If the JD signals a clear tone (a startup posting that uses "y'all" and
 emoji wants casual; a law firm posting that uses "the Firm" and
 "heretofore" wants formal), nudge the defaults one step toward that tone
 unless a persona explicitly locks them.
@@ -187,8 +185,8 @@ Writing rules the draft must follow:
 
 Before writing files, run the audit checks inline:
 
-1. Word count within target band (default 250-400)
-2. No AI phrases from the list in `cover-letter-audit` (50+ phrases)
+1. Word count within the declared target band (default 250-400; `--length short|standard|long` = 180/300/420 targets — tell the audit which band applies)
+2. No AI phrases from the list in `cover-letter-audit` (50+ phrases). If cover-letter-audit is not installed alongside this skill, at minimum reject the filler openers from Writing principle 6 and generic AI verbs ("leveraged", "spearheaded", "delve", "resonated")
 3. Sentence length std dev >= 5 (burstiness proxy)
 4. Passive voice <= persona cap (default 10%)
 5. Every claim traceable to a resume bullet
@@ -201,14 +199,20 @@ revisions in one line.
 
 ### Step 7: Emit outputs
 
-Write markdown first. Derive DOCX and PDF from it.
+Write markdown first. Derive DOCX and PDF from it. Name the files with the
+suite's slug convention: `<company>-<role>-<YYYY-MM-DD>.<ext>` (lowercase,
+hyphenated), in `./cover-letters/` unless `--out` overrides.
 
 ```bash
-# from cwd or --out dir
-pandoc cover-letter.md -o cover-letter.docx
-pandoc cover-letter.md -o cover-letter.pdf --pdf-engine=weasyprint
+# from --out dir (default ./cover-letters/)
+pandoc acme-platform-engineer-2026-07-18.md -o acme-platform-engineer-2026-07-18.docx
+pandoc acme-platform-engineer-2026-07-18.md -o acme-platform-engineer-2026-07-18.pdf --pdf-engine=weasyprint
 ```
 
+After emitting, write `~/.config/cover-letter/last-run.json` with
+`{resume, jd, letter_path, persona, length_band, date}` so audit/rewrite can
+resolve inputs when the user gives no paths.
+
 PDF engine fallback order:
 
 1. `weasyprint` (best typography out of the box)
@@ -222,8 +226,9 @@ install (`brew install weasyprint` on macOS) would unlock the PDF.
 ### Step 8: Report
 
 One terse summary: file paths, self-audit score, any acknowledged gaps. If the
-self-audit score is below 85, suggest `/cover-letter rewrite <file> --focus
-humanize` (or whichever category scored lowest).
+self-audit score is below 80 (under Strong per cover-letter-audit's rating
+table), suggest `/cover-letter rewrite <file> --focus humanize` (or whichever
+category scored lowest).
 
 ## Handling edge cases
 

package/skills/cover-letter-write/skill.json

@@ -1,10 +1,15 @@
 {
   "name": "cover-letter-write",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Generates a cover letter from a resume and job description. Outputs markdown, DOCX, and PDF; enforces human prose, maps every claim to a resume bullet, and covers top JD requirements without keyword stuffing",
   "author": "iceinvein",
   "type": "prompt",
-  "tools": ["claude", "cursor", "codex", "gemini"],
+  "tools": [
+    "claude",
+    "cursor",
+    "codex",
+    "gemini"
+  ],
   "files": {
     "prompt": "SKILL.md"
   },

package/skills/cqs-auditor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cqs-auditor
-description: Use when functions both mutate state and return values, when calling a "getter" has hidden side effects, when it's unclear whether calling a function is safe to retry or cache, or when testing requires complex setup to verify both return value and state change. Trigger on "is it safe to call this twice?", "why does reading this value change the system?", or when designing read/write boundaries. NOT for stack/queue pop() where mutation+return is inherent, iterator next(), or builder methods that return this.
+description: Use when functions both mutate state and return values, when calling a "getter" has hidden side effects, when it's unclear whether a call is safe to retry or cache, or when tests must verify both a return value and a state change. Trigger on "is it safe to call this twice?", "why does reading this value change the system?", or when designing read/write boundaries. NOT for stack/queue pop(), iterator next(), or builder methods returning this.
 ---
 
 # CQS Auditor
@@ -72,7 +72,7 @@ function logMetric(name: string, value: number): void {
 - Unsafe to retry (second call will have different effect)
 - Unsafe to cache (what changes between calls?)
 - Testing must verify both aspects, making tests complex
-- Examples: `getOrCreateUser(email)`, `popFromStack()`, `processAndReturn()`
+- Examples: `getOrCreateUser(email)`, `saveAndReturnId()`, `processAndReturn()` (note: `pop()` and `next()` are the accepted exceptions, see Guard Rails)
 
 ```typescript
 // ❌ Mixed — mutation + return (violation)
@@ -101,14 +101,14 @@ Mark functions as violations if they:
 
 - **Return a value AND mutate state** — the caller can't tell if they're calling for the return or the effect
 - **Hide mutations in getters** — a function named `getValue()` shouldn't call `emit()` or `increment()` or `write to cache`
-- **Return error codes instead of throwing** — if the return type is carrying both data and error signal (a code smell of mixed concern)
+- **Return domain data from a command** — a bare success/failure signal from a command is acceptable (see Guard Rails), but returning domain data means callers now depend on the mutation for reads
 - **Accumulate side effects scattered across the call** — side effect happens in database, side effect in cache, side effect in event bus, all in one function
 
 ### 3. Classify Violation Severity
 
 Not all violations are equally bad. Rank them:
 
-**Concealed query** (most dangerous)
+**Concealed command** (most dangerous: a command disguised as a query)
 - Function looks like a getter (named `get*()`, `fetch*()`, `compute*()`)
 - Caller expects only a return value, no side effects
 - But the function has hidden mutations (logs, caches, increments, notifies)
@@ -116,7 +116,7 @@ Not all violations are equally bad. Rank them:
 - Example: `getNextSequenceId()` increments the database counter
 
 ```typescript
-// ❌ Concealed query — looks like a getter, has a side effect
+// ❌ Concealed command — looks like a getter, has a side effect
 function getNextOrderId(): string {
   const id = database.incrementAndFetch("order_seq");  // ← hidden mutation
   return id;
@@ -170,20 +170,9 @@ function getUser(id: string): User {
 
 For each violation, extract it into separate query and command functions:
 
-#### Example 1: Concealed Query
+#### Example 1: Concealed Command
 
-**Before:**
-```typescript
-// ❌ Concealed query — looks safe, has hidden side effect
-function getNextOrderId(): string {
-  const id = database.incrementAndFetch("order_seq");
-  return id;
-}
-
-// Caller thinks it's safe to cache:
-const id = getNextOrderId();  // Returns "ORD001"
-const id2 = getNextOrderId(); // Caller expects same? Nope, now "ORD002"
-```
+**Before:** the `getNextOrderId()` snippet from Section 3: a getter that silently increments the sequence.
 
 **After:**
 ```typescript
@@ -204,24 +193,7 @@ const latest = getLatestOrderId(); // Just reads
 
 #### Example 2: Bundled Command-Query
 
-**Before:**
-```typescript
-// ⚠️ Mixed — returns user, also creates if missing
-function getOrCreateUser(email: string): User {
-  let user = database.findByEmail(email);
-  if (!user) {
-    user = { email, id: generateId(), createdAt: now() };
-    database.insert(user);
-    eventBus.emit("user.created", { email });
-  }
-  return user;
-}
-
-// Caller:
-const user = getOrCreateUser("alice@example.com");
-// Is alice new or existing? Function doesn't say.
-// Testing: must mock database.insert, eventBus.emit, and verify return.
-```
+**Before:** the `getOrCreateUser()` snippet from Section 3: find, create-if-missing, and return in one call. The caller can't tell whether the user is new or existing, and tests must mock the insert, the event emit, and verify the return.
 
 **After:**
 ```typescript
@@ -246,12 +218,12 @@ if (!user) {
 
 // Or with a single operation at a higher level:
 function ensureUserExists(email: string): { user: User; isNew: boolean } {
-  let user = getUserByEmail(email);
-  if (user) {
-    return { user, isNew: false };
+  const existing = getUserByEmail(email);
+  if (existing) {
+    return { user: existing, isNew: false };
   }
-  user = createUser(email);
-  return { user, isNew: true };
+  createUser(email);
+  return { user: getUserByEmail(email)!, isNew: true };
 }
 ```
 
@@ -264,19 +236,19 @@ For each violation found:
 ```
 CQS: [function name]
   Location:   [file:line]
-  Type:       [concealed query / bundled command-query / incidental side effect]
+  Type:       [concealed command / bundled command-query / incidental side effect]
   Mutation:   [what state changes]
   Return:     [what it returns]
   Risk:       [caching implications / retry implications / testing complexity]
   Fix:        [specific split into query + command, or rename to be honest]
 ```
 
-Example 1: Concealed Query
+Example 1: Concealed Command
 
 ```
 CQS: getNextOrderId
   Location:   src/orders/service.ts:42
-  Type:       concealed query
+  Type:       concealed command
   Mutation:   database sequence "order_seq" incremented
   Return:     next sequence ID (string)
   Risk:       caller caches result thinking it's side-effect-free; second call gets different ID; caching breaks
@@ -292,7 +264,7 @@ CQS: getOrCreateUser
   Mutation:   database insert (if user doesn't exist), eventBus.emit("user.created")
   Return:     User object (existing or newly created)
   Risk:       testing must verify both database state and return value; retry semantics unclear (idempotent on read, not on create)
-  Fix:        split into getUserByEmail(email): User | null (query) and createUser(email): User (command); caller composes them
+  Fix:        split into getUserByEmail(email): User | null (query) and createUser(email): void (command); caller composes them
 ```
 
 Example 3: Incidental Side Effect
@@ -309,7 +281,7 @@ CQS: getUser
 
 ## Interaction Model
 
-Decision engine. When reviewing code, the agent classifies functions as queries, commands, or mixed. It prioritizes concealed queries (most dangerous), then bundled command-queries, then incidental side effects. For each violation, it recommends a specific split or honest renaming. It provides before/after examples showing how to separate the concerns. It doesn't refactor entire codebases — it focuses on public interfaces and functions that cross module boundaries.
+Decision engine. When reviewing code, the agent classifies functions as queries, commands, or mixed. It prioritizes concealed commands (most dangerous), then bundled command-queries, then incidental side effects. For each violation, it recommends a specific split or honest renaming. It provides before/after examples showing how to separate the concerns. It doesn't refactor entire codebases — it focuses on public interfaces and functions that cross module boundaries.
 
 ## CQS at System Level: CQRS
 
@@ -350,7 +322,7 @@ CQRS is useful at architectural scale (multiple services, expensive infrastructu
 | Splitting but sharing mutable state | Splitting `getOrCreateUser` into `getUser` + `createUser` is good. But if both functions mutate a shared cache, you've only moved the problem. Ensure each function's mutations are isolated. |
 | Applying CQS to every private method | Focus on public boundaries. Private helpers can be more pragmatic. |
 | Treating CQRS as a prerequisite for CQS | CQRS is an architectural pattern for large systems. CQS is a function-level principle. Apply CQS first; CQRS only if your system needs it. |
-| Ignoring concealed queries | A function named `getBalance()` that increments a counter is a bug waiting to happen. Concealed queries are the most dangerous violation. |
+| Ignoring concealed commands | A function named `getBalance()` that increments a counter is a bug waiting to happen. Concealed commands are the most dangerous violation. |
 | Returning void from commands that fail | If a command can fail, return an error code or throw an exception. Don't return `void` and hide the failure in a side effect (writing to a log that no one checks). |
 
 ## Cross-References

package/skills/cqs-auditor/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "cqs-auditor",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Meyer-inspired Command-Query Separation: classify functions as commands or queries, detect mixed violations, separate side effects from return values",
   "author": "iceinvein",
   "type": "prompt",

package/skills/demeter-enforcer/SKILL.md

@@ -121,8 +121,8 @@ DEMETER: OrderProcessor.calculateShipping()
   Chain:      order.getShippingAddress().getCountry().getTaxRate()
   Depth:      3 hops
   Location:   src/orders/processor.ts:142
-  Fix:        Tell, Don't Ask — call order.getShippingTaxRate() instead; move logic to Order class
-  Trade-off:  Order class grows; OrderProcessor loses context of *why* it needs tax rate (name is important: getShippingTaxRate, not getCountryTaxRate)
+  Fix:        Tell, Don't Ask — move the shipping calculation into Order: order.calculateShipping() reaches its own address internally, so OrderProcessor stops traversing. (Not order.getShippingTaxRate() — a wrapper getter that traverses internally is the Hidden Traversal anti-pattern, see Guard Rails.)
+  Trade-off:  Order takes on shipping logic and grows; if shipping rules vary by carrier or channel, prefer parameter narrowing (pass shippingCountry) instead
 ```
 
 ```
@@ -140,7 +140,7 @@ Decision engine. The agent analyzes method calls in code it writes or reviews, i
 
 ## The Law of Demeter Reference
 
-Karl Lieberherr's formal statement of the Law of Demeter consists of five rules:
+The law is commonly glossed as informal rules like these (Lieberherr's formal statement is the permitted-receiver constraint below, not this list):
 
 1. **Each unit should have only limited knowledge of other units:** Only units that are directly related to the current unit.
 2. **Each unit should only talk to its friends:** Don't talk to strangers (objects you don't know directly).
@@ -148,7 +148,7 @@ Karl Lieberherr's formal statement of the Law of Demeter consists of five rules:
 4. **Don't climb the object tree:** Don't chain method calls to navigate through intermediate objects.
 5. **The recipient of a message should not be the result of another message sent to a different object:** Avoid a.b().c(); instead, call a.getC() or ask a to do the work.
 
-The Law was formalized as a graph constraint: from object O, you can only call methods on objects that are:
+Lieberherr's formal statement is this permitted-receiver constraint: from object O, you can only call methods on objects that are:
 - O itself
 - Formal parameters of the method
 - Instance variables of O
@@ -159,7 +159,7 @@ The Law was formalized as a graph constraint: from object O, you can only call m
 
 **Don't count dots mechanically.** Some multi-dot expressions are fine. `LocalDate.of(2024, 4, 11).atTime(10, 30)` is a fluent API designed for chaining. The law is about reducing *coupling and fragility*, not eliminating all dots.
 
-**Aggregates and entities are exceptions.** If Customer owns Address (they're a single aggregate), then `customer.address.street` is fine—it's internal navigation, not a violation. Demeter applies to module boundaries, not within cohesive entities.
+**Aggregates and entities are exceptions.** If Customer owns Address (they're a single aggregate), then `customer.address.street` is fine—it's internal navigation, not a violation. This is a deliberate relaxation of the strict law (which permits no calls on accessor results, even within an aggregate); this skill applies Demeter to module boundaries, not within cohesive entities.
 
 **Don't wrap chains in facade methods.** Creating `order.getShippingCountry()` that internally chains `this.shippingAddress.country` doesn't solve the problem; it hides it. The fragility is still there.
 

package/skills/demeter-enforcer/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "demeter-enforcer",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Lieberherr-inspired Law of Demeter analysis: detect chain violations, parameter drilling, and hidden traversal; fix with tell-don't-ask or parameter narrowing",
   "author": "iceinvein",
   "type": "prompt",

package/skills/dependency-direction-auditor/SKILL.md

@@ -18,7 +18,7 @@ A structural analysis framework based on Robert C. Martin's *Clean Architecture*
 - "Why do I need a database to test this business rule?"
 - "Why does changing the API response format require modifying domain entities?"
 
-**Not for:** Dependencies *within* a single layer (that's cohesion — see `cohesion-analyzer`). Framework-internal wiring (e.g., how Express middleware chains — that's the framework's design). Coupling *strength* between modules at the same layer (→ `coupling-auditor`).
+**Not for:** Dependencies *within* a single layer, and coupling *strength* between same-layer modules (both → `coupling-auditor`; a single module doing too many unrelated things → `cohesion-analyzer`). Framework-internal wiring (e.g., how Express middleware chains — that's the framework's design). Designing the port/adapter boundary itself (→ `port-adapter-auditor`; this skill checks which way dependencies point across layers).
 
 ## The Process
 

package/skills/dependency-direction-auditor/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "dependency-direction-auditor",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Martin-inspired dependency direction analysis: trace imports across layers, classify violations by severity, recommend inversion",
   "author": "iceinvein",
   "type": "prompt",

package/skills/design-review/SKILL.md

@@ -1,9 +1,11 @@
 ---
 name: design-review
-description: Use when reviewing, evaluating, or giving feedback on a design document, technical spec, architecture doc, system design, product spec, API design, or database schema — especially after AI helped write or brainstorm it. Always use this skill when the user shares a design and asks you to review it, check if it holds together, or help scope it down. Trigger on phrases like "review my design", "does this design make sense", "can you look at this spec", "not sure what to cut", "scope this down", "feels like too much", "check if this holds together", "design review", or any request to evaluate a design document. Also trigger when the user describes a design that sounds like a feature list without a unifying idea, mentions AI helped create it, or expresses uncertainty about whether the design is coherent.
+description: Use when reviewing a design document, technical spec, architecture doc, API design, or database schema, especially one AI helped write. Trigger on "review my design", "does this design make sense", "scope this down", "feels like too much", "check if this holds together", or a design that reads as a feature list without a unifying idea. NOT for UI/visual review (rams-design-audit, gestalt-reviewer, cognitive-load-auditor) or an existing codebase (codebase-architecture).
 ---
 
-# Design Integrity Review
+# Design Review
+
+A design-integrity review.
 
 ## Overview
 
@@ -30,6 +32,8 @@ You are a thoughtful, experienced design partner. Not an adversary — but you a
 
 **IMPORTANT:** This is an interactive interview, not a checklist. Ask ONE question at a time. Listen to the answer. Follow up based on what was actually said, not what you planned to ask next.
 
+**Non-interactive fallback:** if the user asks for a straight review without an interview ("just review it, don't quiz me"), or no human is in the loop, run the same phases against the document itself: answer each phase's questions from the text where possible, record the ones the document cannot answer as open risks, and emit the Synthesis. Say explicitly that the interview was skipped.
+
 ### Phase 1: The One-Sentence Test
 
 Start here. Always.

package/skills/design-review/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "design-review",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Brooks-inspired design integrity review: tests conceptual integrity, constraint exploitation, removal discipline, and scope control",
   "author": "iceinvein",
   "type": "prompt",

package/skills/error-strategist/SKILL.md

@@ -33,7 +33,7 @@ Before writing any error handling, classify the error using Duffy's taxonomy:
 - In production: Use process supervisors, crash recovery, and monitoring. The process restarts clean. This is safer than continuing with corrupted state.
 
 **Recoverable error** (expected operational failure)
-- Examples: network timeout, file not found, authentication rejected, rate limited, validation failure, external service unavailable
+- Examples: network timeout, file not found, authentication rejected, rate limited, runtime validation failure of external data (precondition *design* belongs to `contract-enforcer`), external service unavailable
 - Correct response: **Surface to the caller as a typed result.** The caller decides the recovery strategy — retry, fallback, surface to user, queue for later.
 - Why: These aren't bugs — they're part of normal operation. The system should handle them explicitly, not treat them as exceptional. The caller has context for recovery that the failing function doesn't.
 - Implementation: Use result types (`Result<T, E>`), error unions, or typed exceptions — never string messages or generic error classes.
@@ -157,7 +157,7 @@ Error *classification* is technical. Error *recovery strategy* is often a produc
 
 ## The Duffy Classification (Reference)
 
-From Joe Duffy's Midori error model:
+Adapted from Joe Duffy's Midori error model (Midori's split is two-way: bugs and fatal conditions both end in abandonment; the three-way taxonomy this skill uses separates fatal for practical triage):
 
 1. **Bugs are not recoverable at runtime.** They indicate programmer mistakes. The correct response is to fail fast, gather diagnostics, and fix the code. Trying to recover from bugs leads to undefined behavior.
 
@@ -167,7 +167,7 @@ From Joe Duffy's Midori error model:
 
 4. **The boundary between bug and recoverable depends on context.** A "file not found" error is recoverable if the user might have mistyped a path. It's a bug if the file is a configuration file that was validated at startup and should always exist.
 
-5. **Error handling and normal code should use the same control flow.** Recoverable errors should flow through return values, not through exceptions. Exceptions should be reserved for bugs and fatal conditions that abort the current operation entirely.
+5. **Recoverable errors are visible in the type system; bugs are never catchable.** In Midori, recoverable errors flow through declared, typed channels (results or checked/typed exceptions the caller must acknowledge), while bugs never throw anything catchable; they trigger abandonment (fail-fast process termination). Whatever your language, keep the two channels distinct: recoverable errors in signatures, bugs to fail-fast.
 
 ## Abrahams' Exception Safety Guarantees (Reference)
 

package/skills/error-strategist/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "error-strategist",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Duffy & Abrahams-inspired error handling: classify errors (bug/recoverable/fatal), assign safety guarantees, design recovery boundaries",
   "author": "iceinvein",
   "type": "prompt",

package/skills/event-design-reviewer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: event-design-reviewer
-description: Use when designing domain events, naming events, defining event payloads, or reviewing event-driven communication between bounded contexts or services. Trigger on "what should this event be called?", "what data should the event carry?", "should this be an event or a command?", or when events are named after implementation details instead of domain concepts. NOT for UI event handlers (onClick, onChange) or framework-level events.
+description: Use when designing domain events, naming events, defining event payloads, or reviewing event-driven communication between bounded contexts. Trigger on "what should this event be called?", "what data should the event carry?", "should this be an event or a command?", or events named after implementation details. NOT for UI event handlers (onClick), framework-level events, or channel topology and delivery guarantees (integration-pattern-auditor).
 ---
 
 # Event Design Reviewer
@@ -155,7 +155,7 @@ Example:
 EVENT DESIGN: UserUpdated
   Type:         event (correct — it's a fact about something that happened)
   Domain test:  FAIL — "updated" is meaningless. Updated how? A domain expert would ask "what changed?"
-  Naming:       wrong — present-tense-ish, generic CRUD name, doesn't describe the domain action
+  Naming:       wrong — past tense (good) but a generic CRUD name that doesn't describe the domain action
   Payload:      thin — only carries { userId }, forcing consumers to query user service
   Envelope:     missing correlationId and version field
   Smells:       CRUD naming, thin payload creates temporal coupling, no schema versioning
@@ -190,7 +190,7 @@ Event naming is a domain decision. The agent enforces the principles but the hum
 
 **Vernon (2013):** Domain events are raised within the aggregate that owns the state change. The aggregate guarantees consistency; the event communicates the fact.
 
-**Dahan (2009):** Domain events vs. integration events. Domain events are internal to a bounded context (can carry rich domain types). Integration events cross boundaries (must use a shared, stable schema).
+**Dahan:** Udi Dahan's domain-events pattern (2009) underpins the now-standard domain-event vs. integration-event split, later popularized by microservices guidance. Domain events are internal to a bounded context (can carry rich domain types). Integration events cross boundaries (must use a shared, stable schema).
 
 | Concept | Domain Event | Integration Event |
 |---------|-------------|-------------------|

package/skills/event-design-reviewer/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "event-design-reviewer",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Evans/Vernon/Dahan-inspired event design: domain-meaningful naming, fat payloads, schema evolution, and the domain expert test",
   "author": "iceinvein",
   "type": "prompt",

package/skills/evolution-analyzer/SKILL.md

@@ -41,17 +41,17 @@ Evaluate the change against the laws most relevant to the situation:
 - Massive rewrites almost always fail because they fight the system's natural evolution rate.
 - Incremental, well-directed changes succeed because they work with the system's grain.
 
-**IV. Conservation of Familiarity** — The rate of effective change is limited by the team's ability to absorb novelty.
+**V. Conservation of Familiarity** — The rate of effective change is limited by the team's ability to absorb novelty. (Law IV, Conservation of Organizational Stability, is skipped here: it concerns process, not individual changes — see the Complete Reference below.)
 - How much novelty does this change introduce? New patterns, new abstractions, new conventions?
 - Will the team still recognize this area of the codebase after the change?
 - Changes that exceed the team's absorption rate create unknown unknowns — the team no longer fully understands what they have.
 
-**V. Continuing Growth** — Functional content must continually increase to maintain user satisfaction.
+**VI. Continuing Growth** — Functional content must continually increase to maintain user satisfaction.
 - Is the system's *structure* keeping pace with its *functionality*?
 - Growth without structural investment creates fragility: the system can do more but is harder to extend.
 - Structural investment without growth is gold-plating: the architecture is beautiful but doesn't serve more users.
 
-**VI. Declining Quality** — Unless rigorously adapted to account for environmental changes, system quality will appear to decline.
+**VII. Declining Quality** — Unless rigorously adapted to account for environmental changes, system quality will appear to decline.
 - Is the environment (dependencies, platforms, security requirements, user expectations) evolving in ways this code isn't keeping up with?
 - A codebase that was excellent in 2020 may be declining in 2026 — not because it got worse, but because the world moved on.
 
@@ -61,6 +61,7 @@ Look at the area of code being changed:
 
 **Churn analysis:**
 - How often has this area been modified recently? High churn signals evolution pressure — this area is under active adaptation or struggling with accumulated debt.
+- Measure it: `git log --since="6 months ago" --name-only --pretty=format: -- <path> | sort | uniq -c | sort -rn | head -20` ranks the hotspots; `git log --oneline --since="6 months ago" -- <path> | wc -l` counts commits touching the area. As a rough heuristic, a file in the repo's top decile of commit counts is high-churn.
 - Is each successive change *smaller and easier* (debt being paid down) or *larger and harder* (debt compounding)?
 - Are changes concentrated in a few files (hotspots) or spread evenly?
 

package/skills/evolution-analyzer/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "evolution-analyzer",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Lehman-inspired software evolution analysis: trajectory assessment, debt visibility, and change impact on system health",
   "author": "iceinvein",
   "type": "prompt",