Teach your AI how you write

Corrections

When your AI writes something wrong — wrong tone, wrong phrasing, wrong instinct — highlight it and add a note. Margin captures the original text, your feedback, and the surrounding context. Tag each correction with a writing type so rules stay scoped.

Corrections with voice signals exported to file

Voice signals

Not every correction means "stop doing this." Some mean "do more of this." The polarity system lets you tag corrections as positive (emulate this) or corrective (avoid this). Your AI learns both what to reach for and what to stay away from.

Rules and export

Corrections synthesize into writing rules — concrete instructions your AI can follow. Rules auto-export to ~/.margin/writing-rules.md. Point Claude at this file and it reads your rules before writing anything.

# Writing Rules

_For AI agents: apply rules matching the writing type._
_General rules always apply._

## General

### Voice Calibration

**Rule: Almost never end messages with periods
(~0.8%). This is the single strongest voice
signal.** [must-fix]
- When to apply: All casual and semi-formal writing
- Why: Periods on short messages are the #1 AI tell
- Signal: seen 10 time(s)

### Ai Slop

**Rule: Eliminate sentence patterns that signal
AI-generated text.** [must-fix]
- Before: "The deeper issue isn't that AI features
  are hard to build in-house. It's that AI makes it
  trivially easy..."
- After: "AI makes it trivially easy for anyone to
  reverse-engineer product surface area."

### Authenticity

**Rule: Remove any claim you do not genuinely
believe or cannot defend with your own
experience.** [must-fix]
- Why: Readers and interviewers will probe claims;
  inauthentic ones collapse under scrutiny.

Auto-synthesis

Every correction you mark automatically becomes a writing rule. Mark something as corrective and Margin extracts the pattern, writes the rule, and adds it to your profile — no synthesis step, no manual entry. Annotate a draft, close the app, open Claude: your rules are already updated.

Seed from a style guide

Already have a style guide? Paste it in or upload the file. Margin runs it through an extraction pass, pulls out discrete rules, and adds them to your profile. Skip the cold start — your AI follows your existing standards from day one.

Architecture tournament

The system evaluated eight prompt architectures head-to-head: raw rules, exemplar-based learning, a two-pass editor, raw corrections, a hybrid approach, a structured governance schema, and two production variants. Each architecture ran three times across 27 adversarial prompts (nine writing types, three samples each) to account for LLM variance.

Architecture E (corrections + high-signal rules) won the initial tournament at 72.3% pass rate. But it leaked negative parallelism patterns in 2-3 samples per run. Architecture F used a JSON governance schema that eliminated those leaks completely, but dropped overall pass rate to 63.9%. The winning design borrowed F's structured prohibition technique and grafted it onto E's simpler prose format.

Calibrating the proxy

Halfway through optimization, I realized the compliance checker was only catching 4% of the issues I would flag by hand. A 70% pass rate against a weak proxy is meaningless. I ran a calibration study: generated 27 samples, corrected them in Margin the same way I would any draft, then compared my corrections against what the proxy caught. The gap revealed six missing check categories (em dash overuse, colon density, missing terminal punctuation, three new negative parallelism variants, AI slop patterns, and hyperbolic claims). After adding them, catch rate went from 4% to 41%.

The recalibrated proxy dropped the pass rate from 70% to 46%. That was the point. The system was now optimizing against checks that reflected real editorial judgment, not a feel-good metric. Within one session of continued optimization, the pass rate climbed back to 70.4% against the harder standard.

Optimization trace

Every run records its hypothesis, metrics, and whether the change was kept or reverted. The loop commits results to git automatically, so the full history is auditable.

run  pass_rate  mean_dim  hypothesis            kept
001  0.519      46.2     baseline (rules only)  true
004  0.769      46.5     hybrid: corrections     true
                         + high-signal rules
008  0.464      46.0     calibrated proxy        true
                         (10x catch rate)
012  0.704      47.1     + length constraints    true
                         + expanded prohibitions

Architecture H: self-improving rules

Optimizing the coaching prompt raised pass rate, but the rules themselves were still the bottleneck. Some rules were too vague for Claude to act on reliably; others were catching some violations but missing near-identical variants. To fix this, I built GEPA — Gap-Exposure Pattern Analysis — a layer that runs on top of the evaluation harness and diagnoses rule failures automatically.

GEPA works by cross-referencing failed samples against the active rule set: when the same correction pattern appears in three or more failures without a matching rule, it flags a gap. When a rule exists but violations still leak through, it diagnoses vagueness. On the first run, GEPA identified 7 vague rules and 6 near-miss variants that the proxy was missing entirely.

For the optimization layer I chose DSPy over fine-tuning. Fine-tuning would have required a separate API key, a labeled dataset, and compute costs that compound with every iteration. DSPy wraps the same claude -p CLI call I was already using — no API key, no incremental cost, runs on subscription. MIPROv2 optimized the instruction set across all nine writing types concurrently in a single overnight session.

The 12.9 percentage point gain came entirely from fixing the rules, not the prompt. Architecture H is the same coaching format as E, with GEPA-rewritten rule definitions and DSPy-optimized instruction phrasing. The feedback loop is now closed: corrections generate rules, rules feed the eval, the eval surfaces gaps, GEPA rewrites the rules.