# Extraction Validation -- Triple-Validation Gate

Detailed reference for Step 3 (PATTERN) and Step 4 (RULE) of the create-voice
pipeline. This rubric decides which extracted patterns are kept in the voice
profile and which are discarded.

The principle: a voice profile is only as strong as the patterns it captures.
Patterns that survive all three checks below carry real signal about how the
person thinks and writes. Patterns that pass on intuition alone tend to be
generic observations dressed up as voice traits.

---

## The Triple-Validation Rubric

A voice trait, mental model, phrase fingerprint, or thinking pattern is kept
in the profile only when **all three** of the following hold:

1. **Cross-domain recurrence**: the pattern appears in at least two distinct
   sources or domains (e.g. blog posts AND chat replies; technical writing
   AND casual writing; long-form essays AND short-form replies).
2. **Generative power**: the pattern lets you predict, with reasonable
   confidence, how the person would respond to a NEW situation they haven't
   written about. The pattern produces new output, not just descriptions of
   old output.
3. **Distinguishing exclusivity**: the pattern is specific enough to
   distinguish this person from their peers in the same field. It would feel
   wrong attributed to a similar writer in the same genre.

Patterns that satisfy all three checks earn a place in the voice profile.
Patterns that satisfy two earn a footnote ("observed in domain X, weak in
domain Y") so the voice-writer knows to use them with care. Patterns that
satisfy only one are discarded; they're either noise from the corpus or
generic-writer features the model already produces by default.

---

## Apply the Rubric to Each Extracted Pattern

Document each candidate with this template:

```
### Pattern: <short name>
- Recurrence: <list 2+ sources/domains where it appears, with quotes>
- Generative test: <a NEW situation + the predicted response shape>
- Exclusivity: <name 1-2 peers in the same genre + what they do differently>
- Verdict: KEEP / FOOTNOTE / DROP
- If KEEP, where it lives in the profile: <SKILL.md section, profile.json field>
```

The verdict is positive: KEEP a pattern when all three checks pass. FOOTNOTE
a pattern that passes two of three. DROP a pattern that passes one or none --
those slots are better spent on patterns with stronger signal.

---

## Worked Examples

### Example 1: KEEP -- Writer A's Calibration Questions

- **Recurrence**: Appears in their blog posts ("So is the answer to just keep
  context windows shorter?"), in their HN comments ("am I missing something
  obvious here?"), and in their chat replies ("does that match your
  experience?"). Three distinct domains, same move.
- **Generative test**: Prompted with "what do you think about the new Claude
  release?", we'd predict an opener like "what's the actual workflow change
  here, am I missing it?" rather than a flat assessment. The pattern
  generates new text that matches voice.
- **Exclusivity**: Other AI-tooling writers state confident takes; Writer A
  reliably opens with calibration. Distinguishes them from peers in the same
  genre.
- **Verdict**: KEEP. Lives in `SKILL.md` thinking-patterns and
  fingerprints sections.

### Example 2: KEEP -- Writer B's Mechanism-First Framing

- **Recurrence**: Their lectures, their memos, and their investigative appendix
  all open by laying out a physical mechanism before assigning blame or
  importance. Cross-domain across teaching, technical writing, and
  investigative work.
- **Generative test**: Asked about a new technology, Writer B would describe what is
  physically happening before judging it. The pattern predicts new output.
- **Exclusivity**: Other writers of their generation default to formalism or
  authority-citing. Writer B's mechanism-first move is recognisably their own.
- **Verdict**: KEEP. Documented as a thinking pattern with quotes from each
  domain.

### Example 3: FOOTNOTE -- Writer C's Household Analogies

- **Recurrence**: Strong in long-form blog posts ("the toolbox", "the filing
  cabinet"), nearly absent in chat replies. One domain, partially.
- **Generative test**: Prompted with a tooling question, the analogy tendency
  predicts new output -- but only in long-form mode.
- **Exclusivity**: Distinguishing within tech-writing peers, who mostly use
  industrial or game analogies.
- **Verdict**: FOOTNOTE -- "applies to long-form mode; do not force in
  short-form chat replies".

### Example 4: DROP -- "Uses contractions"

- **Recurrence**: Yes, contractions appear everywhere in the corpus.
- **Generative test**: Predicts no new output -- every casual writer uses
  contractions.
- **Exclusivity**: Fails. This pattern fits any informal writer in English.
- **Verdict**: DROP from the qualitative pattern list. The contraction RATE
  still belongs in `profile.json` (it's a quantitative metric), but it's not
  a distinctive pattern worth a SKILL.md callout.

### Example 5: DROP -- "Sometimes uses em-dashes"

- **Recurrence**: Sporadic, no clear domain pattern.
- **Generative test**: Doesn't predict new output -- the use is too
  inconsistent to anchor on.
- **Exclusivity**: Em-dashes are common in casual writing and notorious in
  AI-generated text. The pattern would push the voice toward a known AI tell.
- **Verdict**: DROP. Em-dashes belong in the banned-pattern list, not the
  positive pattern list.

---

## How This Wires Into the Pipeline

- **Step 3 (PATTERN)**: every extracted pattern is run through the rubric
  before it's documented. Show the verdict inline with the pattern. The Step 3
  gate requires that documented patterns each carry an explicit KEEP or
  FOOTNOTE verdict with evidence for all three checks.
- **Step 4 (RULE)**: rules are derived only from KEEP and FOOTNOTE patterns.
  Dropped patterns never reach the rules document.
- **Step 5 (GENERATE)**: the generated SKILL.md cites the verdict per
  pattern so future maintainers know what survived the gate and why.

A pattern that can't pass triple-validation is a pattern that will degrade
the voice when the model leans on it. Spending the gate's effort upfront
saves correction work in Step 6 (VALIDATE) and Step 7 (ITERATE).

# Create Voice — Iteration Guide (Step 6 + 7 details)

## Step 6 Details: Validation Procedure

### Generate Test Content

Using the new voice skill, generate 3 test pieces:
1. A short response (2-3 sentences) to a casual prompt
2. A medium response (paragraph) to a technical question
3. A long response (multi-paragraph) to an opinion question

Save each to a temp file.

### Run Validation

For each test piece:

```bash
python3 ~/.claude/scripts/voice-validator.py validate \
  --content /tmp/voice-sample-{name}-{N}.md \
  --profile skills/voice-{name}/profile.json \
  --voice {name} \
  --format text \
  --verbose
```

### Run Banned Pattern Check

```bash
python3 ~/.claude/scripts/voice-validator.py check-banned \
  --content /tmp/voice-sample-{name}-{N}.md \
  --voice {name}
```

### Interpret Results

| Score | Status | Action |
|-------|--------|--------|
| 60+ with 0 errors | PASS | Proceed to Step 7. The script's pass threshold is 60 (calibrated against real human writing which scored ~66). 70+ is ideal but not required. |
| 50-59 with warnings only | MARGINAL | Review warnings, fix if simple, or proceed |
| < 50 or errors present | FAIL | Identify top 3 violations, fix in SKILL.md, regenerate, revalidate |

**Wabi-sabi check**: If validation flags natural imperfections as errors (run-on sentences, fragments, loose punctuation that match the samples), adjust the validator threshold in config.json, NOT the content, because the authentic writing scored what it scored and synthetic content should match it, not exceed it. If the original writing "fails" validation, the validator is wrong, not the writing.

### If Validation Fails

1. Read the violation report carefully
2. Identify the top 3 violations by severity
3. For each violation, determine if it's:
   - A **real problem** (AI phrase, wrong structure) -- fix in SKILL.md rules or add more samples
   - A **false positive** (natural imperfection flagged as error) -- adjust config.json thresholds
4. Make targeted fixes (one at a time, not wholesale rewrites)
5. Regenerate test content and revalidate
6. Maximum 3 validation/refinement iterations before escalating to user

---

## Step 7 Details: Authorship Matching

### The Authorship Matching Test

1. Select 3-5 original writing samples that were NOT included in the SKILL.md (hold-out samples)
2. Generate 3-5 new pieces using the voice skill on similar topics
3. Present both sets (mixed, unlabeled) to 5 "roasters" (people familiar with the original voice)
4. Ask each roaster: "Were these written by the same person?"
5. Target: 4/5 roasters say "SAME AUTHOR"

### If Authorship Matching Fails

The answer is almost always MORE SAMPLES, not more rules, because adding "just one more rule" was tried through V7-V9 and produced zero improvement -- what worked was adding 100+ categorized samples in V10.

| Failure Pattern | Diagnosis | Fix |
|----------------|-----------|-----|
| "Ideas match but style doesn't" | Insufficient samples in SKILL.md | Add 20-50 more samples, especially short responses |
| "Too polished, too perfect" | Wabi-sabi not applied strongly enough | Increase fragment rate target, add more typos, loosen punctuation rules |
| "Phrases feel generic" | Phrase fingerprints not prominent enough | Bold the fingerprints, add more examples of each |
| "Wrong rhythm" | Sentence length distribution off | Check profile.json targets against generated metrics |
| "Right voice, wrong length" | Response length distribution wrong | Adjust default mode or add stronger length constraints |

### The V10 Lesson

One voice went through 10 versions during development:
- V1-V6: Incremental rule improvement. Modest gains.
- V7-V9: Rules were correct but authorship matching failed 0/5. The voice had the right CONSTRAINTS but not enough EXAMPLES.
- V10: Added 100+ samples organized by pattern. Passed 5/5.

**The breakthrough was not better rules. It was more samples.**

If you find yourself tweaking rules and not improving, step back and ask: "Do I need more samples in the SKILL.md?" The answer is almost certainly yes.

### Wabi-Sabi Final Check

Before declaring the voice complete, verify:

- [ ] Generated content contains natural imperfections from the samples (not manufactured imperfections)
- [ ] Run-on sentences appear at approximately the same rate as in the original samples
- [ ] Fragments appear for emphasis, matching sample patterns
- [ ] Typos from the natural typos list appear occasionally (not forced)
- [ ] Content reads with the same level of polish as the original samples (unless the original voice IS polished)
- [ ] If content is too perfect, the skill needs MORE samples and LOOSER constraints, not fewer
- [ ] If generated content "feels too rough," compare against original samples before adjusting -- if it matches the samples' roughness, it's correct

# Pattern Identification Guide

Detailed reference for Step 3: PATTERN of the create-voice pipeline.

---

## Phrase Fingerprints (CRITICAL)

Read through ALL samples and identify 10+ distinctive phrases that recur. These are what authorship-matching roasters use to confirm identity.

Look for:
- **Signature openers**: How do they start responses? ("I think the issue is...", "So basically...", "Here's what I've found...")
- **Signature closers**: How do they end? ("but we'll see", "does that help?", "anyway, that's my take")
- **Filler phrases**: Verbal tics that appear across contexts ("For what it's worth", "to be fair", "honestly")
- **Hedging patterns**: How they express uncertainty ("probably", "I suspect", "my guess is")
- **Emphasis patterns**: How they stress a point ("the key thing is", "the part people miss")

Document each fingerprint with 2-3 exact quotes from the samples showing it in context.

---

## Thinking Patterns

How does this person reason? This is deeper than style; it's cognitive architecture.

Common patterns to check for:
- **Concede-then-assert**: "That's fair, but..." (acknowledges opposing view, then states own position)
- **Hypothesis-experiment**: "My theory is... I tried... and found..."
- **Systems framing**: "The way this works is..." (explains mechanisms, not just opinions)
- **Experience-based**: "In my experience..." (grounds claims in personal observation)
- **Question-led**: "The question is..." (frames issues as questions to investigate)
- **Analogy-driven**: Uses metaphors and comparisons from specific domains

---

## Response Length Distribution

From the samples, estimate what percentage of responses fall into each bucket:
- Very short (1 sentence): ____%
- Short (2-3 sentences): ____%
- Medium (4-6 sentences): ____%
- Long (paragraph+): ____%

This distribution is critical because most people write short responses most of the time, and AI tends to generate medium-to-long responses by default.

---

## Natural Typos (Authenticity Markers)

Scan samples for 5+ real typos. Document them with the correct spelling. These become wabi-sabi markers that signal authenticity. Keep those spellings as voice markers when they are part of the sample, because the goal is to preserve the author's natural texture rather than smooth it away.

Examples of what to look for:
- Missing apostrophes ("dont" instead of "don't")
- Common word swaps ("there" for "their")
- Dropped letters ("probabl" for "probably")
- Double-typed characters ("tthe")
- Missing spaces after punctuation ("works.But")

---

## Wabi-Sabi Markers

Identify which "imperfections" ARE the voice. These are not bugs to fix; they are features to preserve.

- Run-on sentences: Does this person chain clauses with commas?
- Fragments: Do they use sentence fragments for emphasis?
- Loose punctuation: Is comma usage inconsistent? Is that part of the texture?
- Self-corrections: Do they change direction mid-sentence? ("Well, actually..." or "I mean,")
- Tangential asides: Do they go on tangents? (Parenthetical digressions?)

---

## Linguistic Architectures

Beyond sentence-level patterns, identify the **structural moves** that operate across sentences and paragraphs. These are what AI erases most aggressively -- the model defaults to claim -> evidence -> hedged conclusion regardless of the writer's actual architecture.

Analyze ALL samples (not just a few) for each dimension:

### Argument Architecture

How does the writer build a case?
- **Direction**: Inductive (examples -> conclusion) vs deductive (claim -> evidence) vs mixed? Where does the main claim appear relative to supporting evidence?
- **Escalation**: Do stakes increase through the piece? Narrow -> broad? Low -> high severity?
- **Ending reframe**: Does the ending restate the opening, or transform it into something new?

Document with exact quotes: "In {N} of {M} samples, the writer builds inductively -- evidence first, conclusion last. Example from sample X: [quote showing the build]"

### Concession Architecture

How does the writer handle "yes, but"?
- **Structure**: Short admission -> pivot? Long qualification -> reversal? Never concedes?
- **Pivot markers**: Which words signal the turn? ("but", "though", "the thing is", "and yet", "that said")
- **Position**: Where do concessions appear? Opening? Mid-argument? Never at the end?

Document with exact quotes: "Concessions follow a [short admission -> blunt pivot] pattern. Example: [quote showing concession shape]"

### Analogy Architecture

Where do metaphors and references come from?
- **Source domains**: Which fields? (cooking, construction, sports, warfare, nature, machinery, music, software, etc.)
- **Deployment**: Are analogies used to open? To explain mid-section? To close with a memorable image?
- **Density**: Every post? Rarely? Only for technical concepts?

Document with exact quotes: "Analogies cluster around {domains}. Example: [quote showing analogy from that domain]"

### Bookend Architecture

How do pieces open and close?
- **Opening moves**: Question? Declarative claim? Anecdote? Provocation? Scene-setting?
- **Closing moves**: Reframe? Fragment punch? Circle back to opening? Call to action? Open question?
- **Symmetry**: Does the closing echo or answer the opening?

Document with exact quotes: "Opens with [pattern] in {N}/{M} samples. Closes with [pattern]. Opening and closing are [symmetric/independent]."

---

## Architecture Coverage Note

Not all writers exhibit all 4 architectures. Tweet-only writers may not have argument or bookend architecture. The gate requires 2 of 4, not 4 of 4.

# Create Voice — Phase Status Banners

Report progress at each phase gate using these banner templates. Be direct about what passed or failed, not congratulatory.

## Phase 1/7: COLLECT

```
Phase 1/7: COLLECT
  Samples: {count} across {file_count} files
  Sources: {list of source types}
  GATE: {PASS if >= 50 / FAIL if < 50}
```

## Phase 2/7: EXTRACT

```
Phase 2/7: EXTRACT
  Profile: skills/voice-{name}/profile.json
  Samples analyzed: {N}
  Total words: {N}
  Total sentences: {N}
  Average sentence length: {X} words
  GATE: {PASS/FAIL}
```

## Phase 3/7: PATTERN

```
Phase 3/7: PATTERN
  Phrase fingerprints: {count}
  Thinking patterns: {count}
  Linguistic architectures: {count}/4 documented
  Length distribution: {very short}% / {short}% / {medium}% / {long}%
  Natural typos: {count}
  Wabi-sabi markers: {list}
  GATE: {PASS/FAIL}
```

## Phase 4/7: RULE

```
Phase 4/7: RULE
  Positive traits: {count} (with dampening)
  Contrastive aspects: {count}
  Hard prohibitions: {count}
  Wabi-sabi rules: {count}
  Anti-essay patterns: {list}
  Architectural patterns: {count}
  GATE: {PASS/FAIL}
```

## Phase 5/7: GENERATE

```
Phase 5/7: GENERATE
  SKILL.md: {line_count} lines
  Samples section: {line_count} lines
  config.json: created
  Template sections: {present_count}/{required_count}
  GATE: {PASS/FAIL}
```

## Phase 6/7: VALIDATE

```
Phase 6/7: VALIDATE
  Test 1 (short): {score}/100 - {PASS/FAIL}
  Test 2 (medium): {score}/100 - {PASS/FAIL}
  Test 3 (long): {score}/100 - {PASS/FAIL}
  Banned patterns: {CLEAN/violations found}
  Iterations: {N}/3
  GATE: {PASS/FAIL}
```

## Phase 7/7: ITERATE

```
Phase 7/7: ITERATE
  Authorship match: {X}/5 roasters
  Iterations completed: {N}
  Final validation score: {X}/100
  GATE: {PASS/FAIL}
```

## Final Output

After all phases complete:

```
===============================================================
 VOICE CREATION COMPLETE: {name}
===============================================================
 Files created:
   skills/voice-{name}/SKILL.md              (voice skill)
   skills/voice-{name}/profile.json          (metrics)
   skills/voice-{name}/config.json           (validation config)
   skills/voice-{name}/references/samples/   (organized samples)

 Validation: {PASSED/FAILED} (score: {X}/100)
 Authorship Match: {X}/5 roasters
===============================================================
```

# Skill Generation Guide

Detailed reference for Step 5: GENERATE of the create-voice pipeline.

---

## Files to Create

1. **`skills/voice-{name}/SKILL.md`** -- The voice skill itself (2000+ lines)
2. **`skills/voice-{name}/config.json`** -- Validation configuration
3. **`skills/voice-{name}/profile.json`** -- Already created in Step 2

---

## SKILL.md Structure

The sections, in order of importance by line count. Target 400+ lines of samples and ~200 lines of rules, because V7-V9 had 500+ lines of rules with 100 lines of samples and failed authorship matching -- V10 inverted that ratio and passed 5/5:

| Section | Target Lines | Why This Size |
|---------|-------------|---------------|
| Extensive Authentic Samples | 400+ | THIS IS WHAT MAKES AUTHORSHIP MATCHING WORK. V7-V9 failed with rules-only. V10 passed with 100+ samples. |
| Voice Metrics (from profile.json) | ~100 | Quantitative targets give the model measurable goals, not vague aspirations |
| Rules and Prohibitions | ~200 | Hard constraints prevent the worst AI tells |
| Phrase Fingerprints | ~50 | Exact phrases that roasters use to confirm identity |
| Generation Protocol | ~100 | Pre/During/Post checklists keep output consistent |
| Natural Typos | ~20 | Authenticity markers that signal human-ness |
| Contrastive Examples | ~50 | Shows the model what NOT to do with concrete alternatives |
| Thinking Patterns | ~80 | Cognitive architecture, not just surface style |

**Total: 2000+ lines minimum. Most should be SAMPLES, not rules.** Keep the line count focused on useful samples rather than verbose padding; the goal is 2000+ lines of USEFUL content, primarily samples.

---

## SKILL.md Frontmatter

```yaml
---
name: voice-{name}
user-invocable: false
allowed-tools:
  - Read
  - Write
  - Bash
  - Grep
  - Glob
  - Edit
  - Task
  - Skill
description: |
  Apply {Name}'s voice profile for content generation: [2-3 key traits],
  and modal writing. Use when generating content that must match {Name}'s
  distinctive voice. Use a different pipeline for voice analysis, voice
  profile creation, and generating content in other voices.
command: /voice-{name}
---
```

---

## Sample Organization (THE MOST IMPORTANT SECTION)

Organize samples from Step 1 into the SKILL.md following this structure:

**By Response Length:**
- Very short (1 sentence, ~{X}% of responses): Include 10+ samples
- Short (2-3 sentences, ~{X}% of responses): Include 15+ samples
- Medium (4-6 sentences, ~{X}% of responses): Include 10+ samples
- Long (paragraph+, ~{X}% of responses): Include 5+ samples

**By Pattern Type:**
- Admitting Mistakes: 5+ samples
- Acknowledging Limits: 5+ samples
- Respectful Disagreement: 5+ samples
- Technical Expertise (delivered casually): 5+ samples
- Strong Opinions (unhedged): 5+ samples
- Casual Closers: 5+ samples
- Sarcasm/Wit (if applicable): examples

---

## Voice Metrics Section

Transfer the profile.json data into human-readable tables with targets and tolerances:

```markdown
| Metric | Target | Tolerance | Notes |
|--------|--------|-----------|-------|
| Average sentence length | {X} words | +/- 2 words | Primary rhythm indicator |
| Short sentences (3-10 words) | {X}% | +/- 5% | For emphasis and pacing |
```

---

## Two-Layer Architecture

Design the skill with two layers:

- **Layer A (Always-On Base Voice)**: Core traits, sentence rhythm, punctuation signature, contraction rate, function word signature. These apply to ALL content regardless of mode.
- **Layer B (Mode-Specific Overlays)**: Different modes (e.g., technical, casual, opinion, review) that adjust tone, formality, and structure while keeping Layer A constant.

---

## Prompt Engineering Techniques (Apply Throughout)

These techniques were validated over 10 iterations of a reference voice:

1. **Probability Dampening**: Use "**subtly**", "**slightly**", "**generally**" before traits. Without dampening, the model cranks traits to 100%
2. **Attention Anchoring**: **Bold** all negative constraints. The model pays more attention to formatted text
3. **XML Context Tags**: Use `<context type="static-instructions">` for directives and `<context type="safety-guardrails">` for prohibitions. Structured tags signal instruction priority to the model
4. **Few-Shot Examples**: Include 3+ examples for every prohibition (especially "It's not X. It's Y"). Rules without examples are abstract; examples are concrete
5. **Contrastive Pairs**: For every "DO" include a "DON'T" with concrete text. The model needs to see both sides of the boundary

---

## config.json Template

Create the validation configuration:

```json
{
  "name": "{Name}",
  "version": "1.0.0",
  "description": "{Brief voice description}",
  "modes": ["technical", "casual", "opinion"],
  "validation": {
    "strict_banned_patterns": true,
    "em_dash_forbidden": true,
    "metric_tolerance": 0.20,
    "required_checks": ["banned_phrases", "punctuation", "rhythm"],
    "optional_checks": ["metrics", "sentence_starters", "opening_pattern"]
  },
  "thresholds": {
    "pass_score": 70,
    "error_max": 0,
    "warning_max": 3
  },
  "voice_specific_patterns": []
}
```

Adjust `em_dash_forbidden`, `modes`, and `pass_score` based on the specific voice's characteristics.

# Voice Rules Template

Detailed reference for Step 4: RULE of the create-voice pipeline.

---

## What This Voice IS (Positive Identity)

Write 4-6 core traits with examples from the samples. Use probability dampening to avoid caricature:

- **"subtly" skeptical** not "skeptical" -- dampens the trait so it appears naturally, not performatively
- **"generally" conversational** not "conversational" -- allows for variation
- **"slightly" self-deprecating** not "self-deprecating" -- prevents over-application

For each trait, include 2-3 exact quotes from samples that demonstrate it.

Use dampening adverbs because without them the model cranks traits to 100%. "Skeptical" becomes every-sentence-is-a-challenge. "Conversational" becomes aggressively casual.

---

## What This Voice IS NOT (Contrastive Identity)

Build a contrastive table showing THIS voice vs Generic AI for at least 6 aspects:

| Aspect | This Voice | Generic AI |
|--------|-----------|------------|
| Opening | [Example from samples] | "In today's rapidly evolving landscape..." |
| Uncertainty | [How they express doubt] | "It's worth noting that perspectives may vary" |
| Agreement | [How they agree] | "I absolutely agree with your insightful point" |
| Disagreement | [How they disagree] | "While there are valid concerns, I would respectfully suggest..." |
| Conclusion | [How they end] | "In conclusion, we have explored..." |
| Technical | [Technical style] | "This represents a robust paradigm for..." |

---

## Voice Boundaries

Identify patterns this voice NEVER uses. Apply attention anchoring (**bold**) to all negative constraints because the model pays more attention to bolded text:

Common boundaries to verify:
- **Em-dashes**: Check whether the samples use them; if not, keep them out of the generated voice.
- **Formal transitions**: "However", "Furthermore", "Moreover", "Additionally", "Consequently"
- **AI-typical phrases**: "Let's dive in", "Here's the thing", "delve", "robust", "leverage", "ecosystem"
- **The "It's not X. It's Y" pattern**: Signature AI structure. Almost always prohibited
- **Excessive hedging**: "It's worth noting", "One might argue", "At the end of the day"

For each prohibition, explain WHY it's prohibited for this specific voice (not just "because it's AI-sounding").

### Universal Tic Categories (check all five for every voice)

These five patterns must be explicitly addressed for every voice profile. They are common AI tells that vary by writer — some use them authentically, others never would.

- **Tricolon / Rule of Three**: Does this writer naturally use groups of three, or is it an AI rhythm? If not observed in samples, ban it. If observed, note the frequency and context (argument-building vs. pure rhythm).
- **Rhetorical questions as transitions**: Does this writer use them authentically (premise-setting, calibration, frustration), or are they a crutch? Flag if they appear only to create pacing rather than to steer the reader.
- **Meta-announcements**: Does this writer announce conclusions before stating them ("Here's where I landed:", "What I discovered is:")? If not in samples, ban all pre-announcement structures.
- **Performed self-awareness**: Does this writer label their own cognitive moments ("I find myself thinking...", "As I reflect on...", "What strikes me is...")? If not observed, prohibit. If observed, note whether it's structural or decorative.
- **Section-boundary patterns**: How does this writer open and close sections? Check for: aphoristic button lines (quotable one-liner at section end), verdict headers (headers that state the conclusion), and cold-open vs. signposted section starts. Match the samples exactly; do not default to essay conventions.

---

## Wabi-Sabi Rules

Which "errors" MUST be preserved? This is the inversion of typical quality rules. Only include imperfections actually observed in the samples, because manufactured imperfections feel forced and are as detectable as forced perfection:

- If they write run-on sentences: "Allow comma-chain sentences up to {N} words when expressing enthusiasm or building arguments"
- If they use fragments: "Target {X}% fragment rate for emphasis and pacing"
- If punctuation is loose: "Do not standardize comma usage; match the inconsistent pattern from samples"
- If they self-correct: "Include at least one visible direction change per long-form response"

---

## Anti-Essay Patterns

Most voices are NOT essay-writers. Identify the structural anti-patterns:

- Staccato rhythm? (Short sentences dominating)
- No signposting? (No "First... Second... Third...")
- Single-sentence paragraphs? (Common in chat/forum)
- No introduction/conclusion structure? (Just starts talking)
- Abrupt endings? (No wrap-up, just stops)

---

## Architectural Patterns Template

Translate the linguistic architectures discovered in Step 3 into actionable rules for the voice skill. These go in a dedicated `## Architectural Patterns` section in the generated SKILL.md, between the identity rules and banned patterns.

For each documented architecture, write a rule:

```markdown
## Architectural Patterns

### Argument Flow
[Inductive/Deductive/Mixed] — [one-sentence description]
Build arguments by [specific instruction]. The main claim should appear [position].
Example from samples: "[exact quote showing the pattern]"

### Concessions
Structure: [short admission → pivot / long qualification → reversal / never concedes]
Pivot markers: [list of words this voice uses]
Example: "[exact quote]"

### Analogy Domains
Primary: [domain1, domain2]
Deployment: [where analogies appear — openers? mid-section? closers?]
Density: [frequency]
**NEVER draw analogies from**: [domains this voice avoids]
Example: "[exact quote]"

### Bookends
Opening move: [pattern]
Closing move: [pattern]
Symmetry: [yes/no/sometimes]
Example opening: "[quote]"
Example closing: "[quote]"
```

Omit any architecture that wasn't documented in Step 3. A missing section is better than a fabricated one.

# Narrative Structure Patterns

The 13-check Narrative rubric. Source: Russell et al. (2026), "StoryScope: Towards Comprehensive Narratological Evaluation of LLM-Generated Stories," arXiv:2604.03136v4, University of Maryland. 61,608 stories, 10,272 prompts, 304 narrative features, 5 AI models. The checks below adapt StoryScope's fiction features to nonfiction: arguments instead of plots, named actors and sources instead of characters, endings instead of resolutions.

**Applicability**: content over 500 words. Skip this checklist for captions, tweets, and short social posts. `voice-validator` runs this rubric as its Narrative category; the private de-AI editor skill runs the same checks as its Narrative Structure category (its own `references/narrative-patterns.md`).

**Why narrative checks matter**: surface tells (word choice, cliches, sentence rhythm) get edited away; narrative structure survives stylistic editing. StoryScope reports 93.9% macro-F1 for human-vs-AI detection after LAMP rewriting stripped every stylistic cue. The structural fingerprint persists when every surface tell is patched.

**Known limit**: StoryScope measured fiction. The nonfiction rephrasing here is an adaptation. Transfer to argumentative prose is assumed, not yet measured. StoryScope's Dream/Vision Avoidance feature (SHAP 0.116) is dropped deliberately: dream and vision sequences are fiction devices with no nonfiction counterpart.

**How to run it**: these are LLM-judgment checks, not regex patterns. Read the whole piece, score each check pass or fail against its test, count the fails, apply the scoring table at the end. Every fail must cite a specific quote or location.

---

## Universal Patterns (Checks 1-8)

Present across all five models StoryScope tested, each with a measured human-vs-AI gap.

### 1. Theme Over-Explanation

**Signal**: The narrator states the takeaway in abstract terms: "the lesson here is", "what this means is", a moral paragraph after the evidence. StoryScope: 77% of AI stories explain their theme vs 52% human (25-point gap).

**Human contrast**: Evidence carries the meaning. Facts, quotes, and moments make the point; the reader is trusted to land on it.

**Pass/fail test**: Find every sentence that restates the piece's point in abstract terms. Pass if the point is stated at most once and the evidence still carries it with that sentence deleted. Fail if the takeaway is spelled out more than once, or if deleting the explanation leaves evidence that no longer makes the point. Fix the evidence, then cut the explanation.

### 2. Single-Track Argument

**Signal**: The piece runs straight from thesis to conclusion. No tangents, counter-examples, or asides. StoryScope: 79% of AI stories have no subplot vs 57% human (22-point gap).

**Human contrast**: Secondary threads. A tangent, a counter-example, an aside that returns to enrich the main argument. Real writers wander productively.

**Pass/fail test**: Count the threads that depart from the main argument and return to feed it. Pass: one or more. Fail: zero.

### 3. Strict-Linear Time

**Signal**: Every section moves forward in strict chronological or logical order. No callbacks, no jumps. StoryScope non-linearity scale: 2.12 AI vs 2.40 human.

**Human contrast**: A callback to an earlier point, a flash-forward, an opening that starts at the outcome and explains how it happened, a "remember when" return.

**Pass/fail test**: Count the moves that break strict order (callback, flash-forward, non-linear opening). Pass: one or more. Fail: zero.

### 4. Tidy-Realization or Epilogue Ending

**Signal**: The piece ends on an internal realization ("and then I understood...") or a future-gesturing wrap-up paragraph that adds no information. Realization endings: 47% AI vs 27% human (20-point gap). The epilogue preference is also a Claude fingerprint (SHAP 0.096).

**Human contrast**: Endings with forward motion: a concrete action, an open question, a dated plan, tension left standing.

**Pass/fail test**: Read the final two paragraphs. Pass if the ending carries new information or forward motion (specific next step, open question, standing tension). Fail if it restates the piece, gestures at "what comes next" in general terms, or settles into a neat realization.

### 5. Resolved Ambiguity

**Signal**: The subject has the answer to every question the piece raises; every judgment is settled by the end. StoryScope: the protagonist's choices drive all resolution in 69% of AI stories vs 46% human (23-point gap).

**Human contrast**: Luck, timing, other people's decisions, loose ends. The piece says "I don't know" somewhere it matters, and a moral or open question is left standing.

**Pass/fail test**: List the questions the piece raises. Pass if at least one stays open, or is resolved by something outside the subject's control. Fail if every question closes and the subject's own choices close them all.

### 6. Single Emotional Register

**Signal**: Emotion arrives through one channel only, usually bodily sensation (tight chest, cold sweat, breath catching). StoryScope: 81% AI vs 38% human (42-point gap, the largest in the set).

**Human contrast**: Mixed registers. Named feelings ("I was afraid"), behavioral cues ("I closed the laptop"), sensation, plain statement.

**Pass/fail test**: Mark each emotional beat by register. Pass: two or more registers across the piece. Fail: one register throughout.

### 7. Vague References

**Signal**: "Experts say", "as many have noted", "studies show", with no names attached. StoryScope: implicit, unnamed references in 72% of AI stories vs 50% human (22-point gap).

**Human contrast**: Named people, named works, dates, publications. "Russell et al. (2026) measured" carries authority that "researchers found" lacks.

**Pass/fail test**: List every external claim. Pass if each load-bearing claim names its source. Fail if any load-bearing claim rests on an unnamed authority.

### 8. Reader Never Addressed

**Signal**: The piece is written as if no one is reading: purely declarative from first line to last. StoryScope: 93% of AI stories ignore the reader vs 72% human (21-point gap).

**Human contrast**: "You have probably seen this", "if you have tried X, you know". The prose admits a reader exists.

**Pass/fail test**: Search for direct address or an appeal to the reader's likely experience. Pass: present at least once where the target voice allows it. Fail: absent in a piece whose voice profile is conversational. Formal voices that exclude direct address pass on an implied reader (anticipating an objection counts).

---

## Model Fingerprints and Adapted Checks (Checks 9-13)

Checks 9, 10, and 13 are Claude-specific fingerprints (we generate with Claude; these are self-awareness checks). Checks 11 and 12 adapt StoryScope's discourse-structure and character-agency features to nonfiction; they carry no measured percentage gap yet.

### 9. Flat Escalation

**Signal**: Stakes and intensity hold level from start to finish, or climb in one even ramp. Every section sits at the same emotional temperature. The single strongest Claude discriminator (SHAP 0.402).

**Human contrast**: Escalation in bursts. Stakes ratchet at a specific moment, then release. Peaks and valleys.

**Pass/fail test**: Sketch the intensity curve section by section. Pass: at least one identifiable peak and one valley. Fail: a flat line, or a strictly linear ramp with no release.

### 10. Uniform Event Types

**Signal**: Every paragraph makes the same move: explain, evidence, explain, evidence. Narrow range of what happens in the piece (SHAP 0.491, Claude fingerprint).

**Human contrast**: At least one move the reader would not predict from the opening: a surprising data point, an unexpected reaction, a reversal.

**Pass/fail test**: Label each paragraph's move type. Pass: three or more distinct move types and at least one unpredicted turn. Fail: two move types alternating throughout.

### 11. Front-Loaded Conclusion

**Signal**: The full conclusion arrives in the opening and every later section justifies it backward. No claim is ever at risk. Adapted from StoryScope's discourse-structure features.

**Human contrast**: An inductive build. Evidence accumulates, the conclusion forms in front of the reader, and early sections leave the outcome genuinely uncertain. A front-loaded thesis can also pass when later sections test it for real.

**Pass/fail test**: Locate where the piece's main conclusion first appears in full. Pass if it forms after the evidence, or if it is front-loaded and at least one later section runs a test that could have broken it. Fail if the opening states the conclusion and nothing afterward puts it at risk.

### 12. Agentless Action

**Signal**: Things happen with no named actor ("the system was improved", "mistakes were made"), or one actor does everything and is never stuck. Adapted from StoryScope's character-agency features: AI protagonists act decisively; human subjects get stuck, decide partially, and react to forces outside their control.

**Human contrast**: Visible actors with mixed agency. Specific people do specific things, and at least one of them stalls, reverses, or responds to something they did not choose.

**Pass/fail test**: For each major action in the piece, name who did it. Pass: actions have named actors, and at least one moment shows an actor stuck or reacting rather than driving. Fail: actions float without actors, or a single subject acts decisively at every turn.

### 13. Reverent Structure

**Signal**: The piece honors every convention of its genre. Nothing is subverted; everything feels proper. StoryScope: 62% of Claude stories take the reverent/continuist approach.

**Human contrast**: One subverted expectation per piece: a counter-intuitive lead, a challenged convention, a position the reader might push back on.

**Pass/fail test**: Name the expectation the piece subverts. Pass: you can point to one. Fail: you cannot.

---

## Scoring

Count fails across all 13 checks.

| Fails | Assessment | Action |
|-------|-----------|--------|
| 0-2 | Natural narrative structure | No narrative revision needed |
| 3-5 | Narrative revision warranted | Address the flagged checks |
| 6+ | Structural rewrite needed | Rebuild the piece's architecture, not just surface edits |

The percentages above ground the judgment: most measured checks carry a >=20-point gap (or a top SHAP value) between human and AI writing. Checks 11 and 12 are adapted features awaiting their own measurement; weight them as judgment calls, not measured gaps.

---

## Evidence Summary

| Metric | Value |
|--------|-------|
| Narrative features alone (macro-F1) | 93.2% |
| After LAMP stylistic editing (macro-F1) | 93.9% |
| Human structural rarity (mean percentile) | 0.71 |
| AI structural rarity (mean percentile) | 0.49 |
| Rarity effect size (Cohen's d) | 0.83 |
| Core 30 features retain | 84.8% of full model performance |
| Claude 6-way attribution without style features (F1) | 77.1% |

# Professional Communication Transformation Examples

**Note**: Examples use SaaS/infrastructure context for illustration. The transformation patterns apply to any technical domain.

## Example 1: Multi-Propositional Sentence Processing

### Input (Dense Technical Update)
```
The rate limiter is still broken because it counts preflight OPTIONS requests against the quota, so if you have a frontend making CORS requests the API sees double the traffic and throttles legitimate calls even though the OPTIONS don't hit the backend, but I patched this in our custom middleware along with tons of other rate limiting edge cases to keep things more stable.
```

### Proposition Extraction
1. **Current Status**: Rate limiter broken
2. **Root Cause**: Counts preflight OPTIONS requests against quota
3. **Specific Bug**: CORS preflight requests inflate traffic count
4. **Behavioral Impact**: Legitimate API calls throttled prematurely
5. **Solution Implemented**: Fixed in custom middleware
6. **Scope of Fix**: Includes multiple other rate limiting edge cases
7. **Quality Goal**: Maintain system stability

### Structured Output
```markdown
**STATUS**: YELLOW
**KEY POINT**: Rate limiter bug causes premature throttling of legitimate requests, resolved in middleware patch

**Summary**:
- Core issue: Rate limiter counts preflight OPTIONS requests against client quotas
- Impact: Frontend applications with CORS see double-counted traffic, triggering false throttling
- Resolution: Custom middleware patch implemented alongside other rate limiting stability improvements

**Technical Details**:
Rate limiter incorrectly includes preflight OPTIONS requests in quota calculations, causing CORS-enabled frontends to consume quota at 2x the actual request rate. Middleware patch filters OPTIONS from quota counting and includes additional edge case handling.

**Next Steps**:
1. Document specific rate limiter fixes for upstream contribution to the cloud provider
2. Monitor throttling metrics for additional edge cases
3. Coordinate with the provider on quota calculation logic improvements
```

## Example 2: Stream-of-Consciousness Debugging Translation

### Input (Non-Linear Update)
```
Yeah the v2.1 migration script was an improvement but v2.2 rollback is massive, there were tons of foreign key constraint issues and orphaned records before but v2.2 rollback is cleaner than any point with our custom migration tooling, that's how much they improved it, though I'm sure I'll find more to fix since it's rare you just delete code because the platform handles it better now.
```

### Proposition Extraction
1. **Historical Context**: v2.1 migration showed incremental improvement
2. **Current Release**: v2.2 rollback represents major update
3. **Historical Problems**: Foreign key constraints and orphaned record issues existed
4. **Comparative Performance**: v2.2 exceeds custom migration tooling
5. **Quality Assessment**: Substantial improvement magnitude
6. **Future Expectation**: Additional improvements likely still possible
7. **Code Impact**: Platform improvements may allow custom tooling removal

### Structured Output
```markdown
**STATUS**: GREEN
**KEY POINT**: v2.2 rollback resolves critical foreign key constraint issues, exceeds custom tooling

**Summary**:
- v2.2 rollback released: Major improvements to database migration rollback systems
- Performance milestone: Platform tooling now exceeds custom migration implementation quality
- Historical issues: Foreign key constraints and orphaned record problems resolved

**Technical Details**:
Platform improvements in v2.2 have eliminated the need for custom rollback tooling that was previously required. Rollback performance now superior to any previous state including custom implementations.

**Next Steps**:
1. Evaluate remaining custom migration components for potential removal
2. Identify new improvement opportunities in updated platform tooling
3. Refactor migration scripts to leverage new platform capabilities where appropriate
```

## Example 3: Dependency Blocker Extraction

### Input (Defensive Constraint Explanation)
```
I can't implement certain features unless the vendor fixes their SDK, I don't say they have to do their job first but they do have to fix things I don't control, that's just accurate not demanding, the breaking changes in their latest release that have issues I cannot patch around, only the vendor can fix.
```

### Proposition Extraction
1. **Capability Limitation**: Multiple features blocked
2. **External Dependency**: Vendor controls required SDK
3. **Clarification Intent**: Not demanding priority, acknowledging constraints
4. **Technical Boundary**: No access to modify third-party SDK internals
5. **Scope Delineation**: Clear controllable vs. uncontrollable elements
6. **Tone Defense**: Defensive about being perceived as demanding

### Structured Output
```markdown
**STATUS**: YELLOW
**KEY POINT**: Multiple features blocked by third-party SDK breaking changes

**Summary**:
- Current blockers: Several planned features depend on SDK functionality broken in latest release
- Vendor dependency: Third-party vendor controls the SDK with breaking changes
- Workaround status: No alternative implementation paths available within current API surface

**Technical Details**:
SDK breaking changes are outside development team's control and require a vendor patch. Blocked features cannot proceed until the vendor releases a fixed SDK version.

**Next Steps**:
1. Document specific SDK limitations requiring vendor resolution
2. Continue development on features not dependent on broken SDK paths
3. Coordinate with vendor on SDK fix timeline and priority
4. Identify any possible workarounds for high-priority blocked features
```

## Example 4: Microservice Communication Failure

### Input (Multi-Hypothesis Technical Analysis)
```
I haven't addressed the issues you bring up with the order service timeouts, haven't touched that yet at all, it's on the things to do, it's driven by the async messaging layer, they could have been dropping messages during peak load, they could be misconfigured to not retry.
```

### Proposition Extraction
1. **Current Status**: Order service timeout issues not addressed
2. **Acknowledgment**: Issue recognition confirmed
3. **Backlog Status**: Added to development task list
4. **System Identification**: Async messaging layer involvement
5. **Hypothesis 1**: Messages dropped during peak load
6. **Hypothesis 2**: Retry configuration bug preventing delivery

### Structured Output
```markdown
**STATUS**: YELLOW
**KEY POINT**: Order service timeout issues identified but not yet addressed

**Summary**:
- Issue status: Confirmed timeout problems in async messaging layer
- Current focus: Issue added to development backlog for investigation
- Root cause: Two potential causes identified (message dropping or retry misconfiguration)

**Technical Details**:
Async messaging layer may be dropping messages during peak load or experiencing retry configuration issues that prevent reliable delivery to the order service. Investigation required to determine root cause.

**Next Steps**:
1. Investigate message throughput patterns in async messaging layer during peak load
2. Test retry configuration for potential misconfigurations affecting delivery
3. Implement fixes for confirmed root causes
4. Validate normal message delivery behavior post-fix
```

## Example 5: Crisis Communication Processing

### Input (Urgent Technical Issue)
```
The latest deploy broke CDN cache invalidation completely, stale assets are being served to all regions now and won't update, this affects every customer-facing page and it's breaking the checkout flow, I can work around it by busting caches manually but this needs an immediate rollback or hotfix.
```

### Proposition Extraction
1. **Severity**: Complete system failure
2. **System Affected**: CDN cache invalidation
3. **Behavioral Symptom**: Stale assets served, cache not clearing
4. **Scope**: All regions affected
5. **Impact**: Customer-facing pages and checkout flow disrupted
6. **Workaround Availability**: Manual cache busting possible
7. **Required Action**: Immediate rollback or hotfix urgency

### Structured Output
```markdown
**STATUS**: RED
**KEY POINT**: Critical CDN cache invalidation failure after deploy requires immediate action

**Summary**:
- Critical issue: CDN cache invalidation completely non-functional after latest deploy
- Impact scope: All regions affected, checkout flow broken for customers
- Workaround: Manual cache busting available but rollback or hotfix required

**Technical Details**:
Latest deploy introduced regression causing CDN cache invalidation to fail across all regions. Stale assets being served to all customer-facing pages, creating broken checkout experience.

**Next Steps**:
1. IMMEDIATE: Begin manual cache invalidation to mitigate customer impact
2. URGENT: Initiate deploy rollback or coordinate emergency hotfix
3. Document exact regression point and provide reproduction steps to CDN team
4. Test fix thoroughly before redeployment to prevent additional regressions
```

## Transformation Pattern Summary

### Multi-Propositional Sentences
- Extract 4-6 embedded facts per sentence
- Categorize by status/action/impact/blocker
- Apply priority ordering (business impact first)
- Preserve all technical accuracy

### Stream-of-Consciousness
- Parse chronologically to extract temporal flow
- Group related propositions together
- Linearize into sequential structure
- Maintain causal relationships

### Dependency Blockers
- Strip defensive or emotional language
- Extract specific constraints and dependencies
- Frame as neutral project status
- Provide clear next steps with ownership

### Crisis Communication
- Elevate severity appropriately (RED status)
- Front-load business impact
- Separate immediate vs. follow-up actions
- Maintain technical precision for resolution teams

# Communication Template Library

## Standard Business Communication Template

```markdown
**STATUS**: [GREEN|YELLOW|RED]
**KEY POINT**: [Single most important business takeaway]

**Summary**:
- [Primary accomplishment/issue]: [Business impact]
- [Current focus/blocker]: [Expected outcome/resolution need]
- [Secondary consideration]: [Implications]

**Technical Details**:
[2-3 sentences maximum preserving technical accuracy]

**Next Steps**:
1. [Specific action with timeline if available]
2. [Secondary action with ownership implications]
3. [Follow-up considerations]
```

## Status Indicator Guidelines

### GREEN Status Template
Use when: Successful completion, positive progress, resolved issues

```markdown
**STATUS**: GREEN
**KEY POINT**: [Positive achievement or resolution]

**Summary**:
- Success: [What was accomplished]
- Impact: [Positive business or technical outcome]
- Quality: [Performance or reliability improvement]

**Technical Details**:
[Brief technical implementation or resolution details]

**Next Steps**:
1. [Monitoring or validation actions]
2. [Documentation or knowledge sharing]
3. [Potential follow-up enhancements]
```

### YELLOW Status Template
Use when: In progress with blockers, partial completion, external dependencies

```markdown
**STATUS**: YELLOW
**KEY POINT**: [Current state and primary blocker]

**Summary**:
- Progress: [What has been completed]
- Blocker: [Specific constraint or dependency]
- Workaround: [Temporary solution if available, or "None available"]

**Technical Details**:
[Technical explanation of constraint or dependency]

**Next Steps**:
1. [Action to address blocker or coordinate with stakeholders]
2. [Continue work on unblocked components]
3. [Document or escalate if appropriate]
```

### RED Status Template
Use when: Critical issues, project-affecting problems, urgent intervention needed

```markdown
**STATUS**: RED
**KEY POINT**: [Critical issue and business impact]

**Summary**:
- Critical issue: [Specific problem and severity]
- Impact scope: [Who/what is affected]
- Workaround: [Emergency mitigation if available]

**Technical Details**:
[Root cause and technical explanation for resolution teams]

**Next Steps**:
1. IMMEDIATE: [Emergency action to mitigate impact]
2. URGENT: [Coordination or escalation action]
3. [Root cause resolution and prevention]
```

## Section Templates

### Summary Section Structure

```markdown
**Summary**:
- [Most critical item]: [Business or technical impact]
- [Second priority item]: [Expected outcome or resolution timeline]
- [Supporting information]: [Implications for stakeholders]
```

**Rules**:
- Maximum 3 bullet points for executive summary
- Each bullet: [Subject]: [Impact or outcome]
- Order by business impact priority
- Keep each bullet to one line if possible

### Technical Details Section

```markdown
**Technical Details**:
[System or component name] [specific behavior or issue description]. [Root cause or implementation approach]. [Performance or reliability implications if relevant].
```

**Rules**:
- 2-3 sentences maximum for business stakeholders
- Can expand to 1 paragraph for technical audiences
- Preserve exact technical terminology
- Maintain cause-effect relationships
- Include metrics or measurements if relevant

### Next Steps Section

```markdown
**Next Steps**:
1. [Action verb] [specific task] [with timeline marker if available]
2. [Action verb] [specific task] [with ownership implication if present]
3. [Action verb] [follow-up consideration]
```

**Action Verb Examples**:
- Investigate, analyze, determine (for discovery)
- Implement, deploy, configure (for execution)
- Coordinate, escalate, communicate (for stakeholder actions)
- Document, validate, test (for quality assurance)
- Monitor, track, measure (for ongoing activities)

**Timeline Markers**:
- IMMEDIATE (within hours)
- URGENT (within 1-2 days)
- This week, Next sprint, This month
- After [dependency], When [condition met]

## Proposition Extraction Templates

### Fact Extraction Pattern
```
ORIGINAL: [Dense sentence]

FACTS:
- [Fact 1]: [What is stated]
- [Fact 2]: [What is stated]
- [Fact 3]: [What is stated]

IMPLICATIONS:
- [Fact 1] → [Consequence]
- [Fact 2] → [Consequence]
```

### Temporal Extraction Pattern
```
PAST ACTIONS:
- [What was done]

CURRENT STATE:
- [What is happening now]

FUTURE INTENTIONS:
- [What will be done]
```

### System Reference Pattern
```
SYSTEMS/COMPONENTS:
- [Component 1]: [Current state or behavior]
- [Component 2]: [Relationship to Component 1]
- [Component 3]: [External dependency or constraint]
```

## Multi-Stakeholder Templates

### Executive Summary (C-Level)
```markdown
**STATUS**: [COLOR]
**BUSINESS IMPACT**: [Revenue/customer/strategic implication]

**Summary**:
[1-2 sentences maximum covering what happened and what it means for business]

**Required Action**:
[What executive needs to know or approve]
```

### Technical Manager Summary
```markdown
**STATUS**: [COLOR]
**KEY POINT**: [Technical achievement or issue]

**Summary**:
- Technical: [What was implemented or discovered]
- Team impact: [Resource or timeline implications]
- Dependencies: [What's needed from other teams]

**Technical Details**:
[1 paragraph with sufficient detail for technical understanding]

**Next Steps**:
[3-5 specific actions with ownership]
```

### External Partner Communication
```markdown
**STATUS**: [COLOR]
**KEY POINT**: [Partnership or integration impact]

**Summary**:
- Integration status: [Current state of joint work]
- Dependencies: [What's needed from partner]
- Timeline: [Expected milestones or delivery dates]

**Technical Details**:
[API, integration, or interface specifics]

**Next Steps**:
[Coordinated actions with clear ownership split]
```

## Specialized Patterns

### Bug Report Translation
```markdown
**STATUS**: [YELLOW or RED based on severity]
**KEY POINT**: [Bug impact on functionality or users]

**Summary**:
- Bug: [Specific behavior that's broken]
- Impact: [Who/what is affected]
- Root cause: [Technical explanation if known, or "Under investigation"]

**Technical Details**:
[Reproduction steps, error messages, system state]

**Next Steps**:
1. [Immediate mitigation or workaround]
2. [Investigation or fix implementation]
3. [Testing and validation]
```

### Feature Request Translation
```markdown
**STATUS**: YELLOW
**KEY POINT**: [Feature request and business justification]

**Summary**:
- Request: [What functionality is needed]
- Business value: [Why it's important]
- Technical feasibility: [High/Medium/Low with brief explanation]

**Technical Details**:
[Implementation approach or architectural considerations]

**Next Steps**:
1. [Prioritization or stakeholder decision]
2. [Design or planning phase]
3. [Implementation timeline if approved]
```

### Performance Analysis Translation
```markdown
**STATUS**: [GREEN if acceptable, YELLOW if degraded, RED if critical]
**KEY POINT**: [Performance metric and business impact]

**Summary**:
- Current performance: [Metric with comparison to baseline or target]
- Impact: [User experience or system reliability effect]
- Root cause: [What's causing the performance characteristic]

**Technical Details**:
[Profiling data, bottlenecks, resource utilization]

**Next Steps**:
1. [Optimization approach or investigation]
2. [Performance testing validation]
3. [Monitoring and ongoing measurement]
```

## Quality Checklist Template

```markdown
TRANSFORMATION QUALITY CHECKLIST:
✓ Single, clear key point identified
✓ No information loss from original communication
✓ Technical accuracy maintained throughout
✓ Business impact clearly highlighted
✓ Action items specific and appropriately assigned
✓ Professional formatting and tone consistency
✓ Appropriate detail level for target audience
✓ Status indicator matches severity
✓ Next steps are actionable and owned
```

## Common Phrase Transformations

### Defensive → Neutral
- "I can't do X unless Y" → "X is blocked by dependency on Y"
- "That's not my fault" → "Root cause is in [system/team] scope"
- "I told you this would happen" → "As previously documented, [issue] occurred"

### Technical → Business
- "The algorithm is broken" → "System producing incorrect results"
- "Performance is terrible" → "Response time exceeds acceptable thresholds"
- "It won't work" → "Implementation not feasible with current constraints"

### Casual → Professional
- "This is awesome" → "Substantial improvement achieved"
- "Totally broken" → "Complete system failure"
- "Pretty good" → "Acceptable performance within parameters"
- "Kinda works" → "Partial functionality with known limitations"

# Translate Skill: Glossary Reference

> **Load when**: Request contains "technical", "specialized", "glossary", "terms", or domain vocabulary.
> **Scope**: Glossary format, build procedure, chunk injection, term-preservation rules, example.

---

## Glossary Format

Use a markdown table with three columns:

```markdown
| Source Term | Target Term | Notes |
|---|---|---|
| machine learning | 機械学習 | Use consistently; annotate on first occurrence |
| API | API | Preserve as-is; internationally recognized |
| Docker | Docker | Brand name; preserve unchanged |
| microservice | マイクロサービス | Transliteration preferred over translation |
```

**Column definitions**:

| Column | Content |
|---|---|
| Source Term | Term exactly as it appears in the source document |
| Target Term | Agreed translation or "preserve" if keeping source-language form |
| Notes | Usage rule: annotate on first use, preserve unchanged, transliterate, etc. |

---

## Building a Glossary from the Source Document

**Step 1: Scan for specialized vocabulary**

Read the source document and list every term that falls into one of these categories:

- Technical identifiers: function names, library names, protocol names, data formats
- Domain vocabulary: field-specific terms that have a standard translation in the target language
- Brand and product names: trademarks, software product names, company names
- Proper nouns: person names, place names, organization names
- Abbreviations and acronyms: expand on first use in the target language if the expansion differs

**Step 2: Decide on treatment per term**

| Term type | Default treatment |
|---|---|
| Internationally recognized technical term (API, JSON, HTTP) | Preserve source-language form |
| Brand name or registered trademark | Preserve source-language form |
| Person name, place name | Preserve source-language form unless a standard transliteration exists |
| Domain vocabulary with a standard target-language equivalent | Translate; annotate on first use |
| Abbreviation whose expansion differs in target language | Translate expansion; keep source abbreviation in parentheses on first use |
| Culturally specific term with no equivalent | Preserve source-language form; add bracketed explanation on first use |

**Step 3: Populate the glossary table**

For each term identified in Step 1, add a row with the treatment decided in Step 2.

**Step 4: Review for consistency**

Check that no term appears in both "preserve" and "translate" rows. If the same concept appears in multiple surface forms in the source (e.g., "ML", "machine learning", "ML model"), unify them under one glossary entry.

---

## Injecting the Glossary into Chunk Translation Prompts

Prepend the glossary to each chunk prompt in this format:

```
Session glossary — apply these translations consistently throughout this chunk:

| Source Term | Target Term | Notes |
|---|---|---|
{glossary rows}

On first occurrence of a translated term, annotate it: "target-term (source-term)".
Preserve source-language form for all terms marked "preserve" in the Notes column.
```

Place the glossary block immediately after the context line and before the chunk text. Keep the glossary under 30 rows in a single prompt; if your glossary exceeds 30 rows, include only the rows relevant to the current chunk's content.

---

## Term Preservation Rules

Apply these in order when deciding whether to translate a term:

1. **Proper noun with no standard transliteration**: preserve unchanged.
2. **Internationally recognized technical identifier** (API, HTTP, JSON, SQL, HTML): preserve unchanged.
3. **Brand name or software product name**: preserve unchanged.
4. **Domain term with a widely used target-language equivalent**: translate and annotate on first use.
5. **Culturally specific concept with no equivalent**: preserve source term; add bracketed gloss explaining the concept on first use.

When in doubt, preserve the source-language term and annotate. A reader who encounters a preserved term can look it up. A reader who encounters a wrong translation has no signal that anything is wrong.

---

## Example Glossary: Technical Document (English to Japanese)

Source document: software architecture article discussing microservices, containers, and CI/CD pipelines.

| Source Term | Target Term | Notes |
|---|---|---|
| microservice | マイクロサービス | Transliterate; annotate on first use |
| container | コンテナ | Transliterate; annotate on first use |
| Docker | Docker | Brand name; preserve unchanged |
| Kubernetes | Kubernetes | Brand name; preserve unchanged |
| CI/CD | CI/CD | Abbreviation; preserve unchanged; expand on first use: 継続的インテグレーション/継続的デリバリー (CI/CD) |
| API gateway | APIゲートウェイ | Mixed: preserve API, transliterate gateway |
| service mesh | サービスメッシュ | Transliterate; annotate on first use |
| load balancer | ロードバランサー | Transliterate; annotate on first use |
| deployment | デプロイメント | Transliterate preferred over 展開 in technical contexts |
| pod | Pod | Kubernetes term; preserve source form; capitalize |
| namespace | 名前空間 | Standard Japanese translation; use consistently |
| YAML | YAML | Abbreviation; preserve unchanged |

**First-use annotation example**:
- Source: "A microservice handles one business capability."
- Target: "マイクロサービス（microservice）は1つのビジネス機能を担当します。"

---

## See Also

- `modes.md` — Chunking algorithm, parallel dispatch, per-mode workflow

# Translate Skill: Mode Reference

> **Load when**: Phase 1 of every translation task.
> **Scope**: Mode detection, per-mode workflow, chunk detection, chunking algorithm, parallel dispatch.

---

## Mode Detection Table

| Request contains | Mode | Notes |
|---|---|---|
| "quick", "fast", "draft", "rough" | quick | Single-pass, no analysis phase |
| "professional", "publication-quality", "polished", "refined" | refined | Full 4-step pipeline |
| "slow", "careful", "accurate" | normal | Emphasizes analysis depth |
| (no qualifier) | normal | Default |

When multiple signals conflict ("quick professional translation"), prefer the higher-effort mode.

---

## Quick Mode

**Use for**: Short text under 500 words, informal content, draft output where speed matters more than polish.

**Workflow**:
1. Detect source and target language.
2. Translate in a single pass using translation principles from SKILL.md Phase 3.
3. Deliver immediately. Skip Phase 2 (ANALYZE) and Phase 4 (POLISH).

**Chunking in quick mode**: For documents over 2000 words that explicitly request quick mode, apply the chunking algorithm below but skip the analysis pass per chunk. Build only a minimal glossary (proper nouns and brand names only).

---

## Normal Mode

**Use for**: Standard documents where accuracy and register matter but publication polish is not required.

**Workflow**:
1. Phase 2: ANALYZE — full analysis pass (language/dialect, register, document type, terminology list).
2. Phase 3: TRANSLATE — single-pass translation using analysis output.
3. Phase 5: DELIVER — report summary.

**Offer refined pass**: After delivering, offer the user an optional refined pass if the output would benefit from idiom review.

---

## Refined Mode

**Use for**: Publication-quality translation, formal documents, content that will be read by native speakers.

**Workflow**:
1. Phase 2: ANALYZE — full analysis pass.
2. Phase 3: TRANSLATE — initial translation draft.
3. Phase 4: POLISH — register scan, idiom review, term audit.
4. Phase 5: DELIVER — report summary including what was changed in the polish pass.

**Register note**: In refined mode, flag every passage where the initial translation sounds like a translation. A skilled native writer would rephrase these; the polish pass rewrites them.

---

## Chunk Detection

Apply chunking when the document exceeds approximately 2000 words. Use this threshold because a single context window produces less consistent term handling and register over long documents than parallel bounded passes do.

**Boundary detection order** (prefer the highest-structure boundary available):

1. Level-2 headings (`## Heading`) — split after the heading, keep heading with its following content.
2. Level-3 headings (`### Heading`) — use when no level-2 headings exist.
3. Blank-line paragraph boundaries — for prose without headings.
4. Sentence boundary — only as a last resort for very long paragraphs with no blank lines.

**Minimum chunk size**: 200 words. Merge chunks below minimum with the preceding chunk.

**Maximum chunk size**: 600 words. Split at next available boundary if a chunk exceeds this.

---

## Chunking Algorithm

```
1. Scan document and identify all split boundaries (in order of preference above).
2. Assign each paragraph/section to a chunk, respecting min/max sizes.
3. Build a session glossary:
   a. In normal/refined mode: extract specialized terms from Phase 2 ANALYZE.
   b. In quick mode: extract proper nouns and brand names only.
   c. Format: markdown table with columns Source Term | Target Term | Notes.
4. For each chunk (dispatch in parallel):
   a. Inject session glossary as a prefix instruction.
   b. Inject document context: "This is chunk N of M from a {document-type} in {register} register."
   c. Translate the chunk using the translation principles from SKILL.md Phase 3.
   d. Capture the translated chunk.
5. Reassemble: concatenate translated chunks in original order, preserving headings and blank lines.
6. Consistency check: scan reassembled output for term variations. If a glossary term appears in multiple forms, normalize to the session glossary form.
```

---

## Parallel Subagent Dispatch Pattern

When dispatching chunks as parallel subagents, structure each subagent call with:

```
System: You are a professional translator. Translate from {source-language} to {target-language}.
Context: This is chunk {N} of {M} from a {document-type}. Register: {register}. 

Session glossary (use these translations consistently):
{glossary-table}

Translate the following text. Preserve all markdown formatting, code blocks, and headings.
Return only the translated text, no commentary.

---
{chunk-text}
```

After all subagents return, proceed to step 5 (reassemble) in the chunking algorithm above.

---

## See Also

- `glossary-template.md` — Glossary format, build procedure, term-preservation rules, example