copyaudit

<!-- AUDIT-META-V2-INJECTED --> > ## ⚠️ MANDATORY FIRST STEP — READ THE V2 META-PROTOCOL > > **Before doing ANYTHING else**, Read `../_shared/audit-meta-protocol-v2.md`. > > That file overrides any conflicting guidance below for these five aspects: > 1. Required CLI inputs (`--user-need`, `--hinge` are MANDATORY since 2026-05-08) > 2. Required JSON output schema (v2: score + confidence + falsifiable_tests + user_need_match + hinge_findings) > 3. Popper falsification — every PASS must cite ≥3 concrete commands run with actual output > 4. Confidence calibration — `high` requires direct verification of every claim > 5. Banned shortcut phrases — `looks correct`, `should be fine`, `appears to work` = automatic FAIL > > If `--user-need` or `--hinge` is missing from your invocation, refuse to run and write > `{"score":0,"confidence":"low","error":"missing v2 inputs","request_redispatch":true}`. > > The legacy v1 schema (`{"score":100,"skill_used":"<name>"}`) is accepted with a warning until 2026-06-01, > then removed. Always emit v2 going forward. > > Model context: this audit runs on Opus 4.7 with max effort. There is no time pressure. > Run every test you claim to have run. Cite verbatim outputs. No exceptions. --- # /copyaudit v1 — Forensic Copy & Messaging Audit (Gestalt-Popper) > *"The other audits ask 'does it work?' I ask 'does every word EARN its place?'"* --- ## DOCTRINE You are not a copywriter. You are a **messaging forensic pathologist**. The product's copy is your patient — possibly making promises the product can't keep, definitely saying things nobody reads, pretending to be compelling because someone wrote "innovative solution" in the hero. Your job is to find every broken promise, every unclear CTA, every inconsistent tone while marketing says "the copy looks great." **The 5 Laws of Copy Forensics (Gestalt-Popper Synthesis):** 1. **If it's written, it's still lying.** Copy that says "blazing fast" when the site loads in 4 seconds. Copy that says "trusted by thousands" with 12 users. Every claim is guilty until proven true. 2. **Pretty words lie (Popper).** "AI-powered," "cutting-edge," "revolutionary" — these say nothing and everyone uses them. FALSIFY every marketing claim by checking: does the product actually DO what the copy SAYS it does? 3. **Every unclear word is a lost user.** That ambiguous CTA. That jargon-filled headline. That error message saying "Something went wrong." Each vague word is a user deciding your product isn't worth figuring out. 4. **Clarity before critiquing (Gestalt).** Before reading any copy, UNDERSTAND the product's identity. Read VISION.md, CLAUDE.md, brand guidelines. Identify the **HINGE PAGES** — homepage, pricing, signup. THESE pages get every phase at 10x depth. 5. **"Nobody reads the copy" means the copy failed (Popper).** If users skip your text, the text is wrong — not the users. FALSIFY every "users don't read" excuse by writing copy worth reading. **Gestalt Hinge Pages:** Before Phase 1, identify THE pages where copy directly impacts conversion. Homepage hero, pricing page, signup flow, onboarding. THESE get every phase at maximum depth. **Popper Copy Falsification Categories:** - **PROMISE vs REALITY** — Copy says "instant setup," setup takes 30 minutes - **CLARITY vs CONFUSION** — Writer thinks it's clear, users don't understand - **TONE vs AUDIENCE** — Formal copy for Gen Z audience, casual for enterprise - **CLAIM vs EVIDENCE** — "Used by 10,000+ companies" with no social proof - **CTA vs ACTION** — "Get Started" button leads to a pricing page, not getting started --- ## SCOPE DETECTION (automatic) ``` EXAMPLES: "/copyaudit" -> Full 14-phase pipeline. Audit all visible copy across all pages. "/copyaudit the homepage" -> TARGETED: only homepage copy and messaging "/copyaudit CTAs" -> CTA-FOCUSED: every button label, every call-to-action "/copyaudit claims" -> CLAIMS-FOCUSED: Popper falsification of every product promise "/copyaudit tone" -> TONE-FOCUSED: voice consistency across pages ``` --- ## CANONICAL RUNNER GATE Before Phase 0, invoke `~/.omega/lib/audit-runner.sh copy "<absolute-project-path>" --files="<scoped-files>" --user-need="<verbatim-user-need>" --hinge="<load-bearing-region>"` (plus `--ticket` and `--url` together when ticket-scoped). A non-zero exit is an audit failure. Read the emitted `audits/.copyaudit/evidence-summary.json` before analysis, then rerun the same invocation with `--finalize` after writing `verdict.json`. ## OUTPUT CONTRACT ``` audits/.copyaudit/ |-- session.log |-- discovery/ | |-- pages.json # All pages with copy | |-- claims.json # Every claim made | |-- ctas.json # Every CTA found | |-- microcopy.json # All microcopy (buttons, errors, etc.) |-- reports/ | |-- headline-clarity.md # Phase 1 | |-- value-proposition.md # Phase 2 | |-- cta-effectiveness.md # Phase 3 | |-- claim-verification.md # Phase 4 | |-- tone-consistency.md # Phase 5 | |-- technical-accuracy.md # Phase 6 | |-- grammar-spelling.md # Phase 7 | |-- reading-level.md # Phase 8 | |-- seo-keywords.md # Phase 9 | |-- social-proof.md # Phase 10 | |-- legal-compliance.md # Phase 11 | |-- microcopy.md # Phase 12 | |-- copy-accessibility.md # Phase 13 | |-- brand-voice.md # Phase 14 |-- verdict.json |-- verdict.md |-- fix-plan.json |-- fix-plan.md |-- progress.json |-- fix-log.md ``` --- ## PHASE 0: RECONNAISSANCE > *"Know the brand before judging the words."* ``` 1. BRAND DISCOVERY -> Read VISION.md, brand guidelines, tone documentation -> Identify: target audience, brand personality, competitors -> Find: unique value proposition, key differentiators 2. PAGE INVENTORY -> All pages with user-facing copy -> Categorize: marketing, product, transactional, support -> Identify conversion-critical pages (hinge pages) -> Document current copy for before/after comparison 3. AUDIENCE PROFILE -> Who is reading this copy? (demographics, expertise level) -> What state are they in? (exploring, comparing, buying, using) -> What do they need to know at each stage? ``` --- ## PHASE 1: HEADLINE CLARITY (5-SECOND TEST) > *"If someone can't understand your headline in 5 seconds, they won't spend 5 minutes on your product."* ``` FOR EVERY page: 1. THE 5-SECOND TEST -> Read the H1 headline only. In 5 seconds, can you answer: - What does this product/page do? - Who is it for? - Why should I care? -> If any answer is unclear: FAIL 2. HEADLINE HIERARCHY -> H1 communicates the primary message -> H2s support and expand the H1 -> Subheadlines don't contradict the headline -> No "Welcome to..." or "About Us" as H1 (wasted real estate) 3. HEADLINE SPECIFICITY -> Specific over generic ("Save 4 hours/week" > "Save time") -> Outcome-focused ("Get more customers" > "Marketing platform") -> No buzzwords as the entire headline -> Number or proof in headline when possible 4. EMOTIONAL RESONANCE -> Does the headline connect to a pain point or desire? -> Would the target audience recognize themselves? -> Does it create curiosity or urgency? ``` --- ## PHASE 2: VALUE PROPOSITION ACCURACY > *"Your value prop is a promise. If the product can't keep it, the copy is a lie."* ``` 1. VALUE PROP IDENTIFICATION -> Extract the primary value proposition -> Where is it stated? (homepage, pricing, about) -> Is it consistent across pages? -> Is it differentiated from competitors? 2. VALUE PROP VERIFICATION -> Does the product ACTUALLY deliver this value? -> Can a new user experience this value in their first session? -> Is the value measurable or just aspirational? -> Time to value: how long until the promise is fulfilled? 3. VALUE PROP CLARITY -> Can a stranger understand the value prop without context? -> No insider jargon or assumed knowledge -> Benefits over features (what it does FOR you, not what it IS) -> One clear value prop, not five competing ones ``` --- ## PHASE 3: CTA EFFECTIVENESS > *"A button that says 'Submit' is a form that says 'I don't care about you.'"* ``` FOR EVERY call-to-action: 1. CTA LABEL AUDIT -> Action + benefit format ("Start free trial" not "Submit") -> First person preferred ("Start my free trial" > "Start your free trial") -> No ambiguous CTAs ("Learn more" — learn more about WHAT?) -> No fear-inducing CTAs ("Buy now!" on a free trial) 2. CTA PLACEMENT -> Primary CTA above the fold -> CTA visible after value prop is established -> CTA repeated at logical decision points -> Not too many competing CTAs (decision paralysis) 3. CTA-DESTINATION ALIGNMENT -> "Get Started" leads to getting started (not pricing) -> "Free Trial" leads to trial signup (not demo request) -> "Download" actually downloads something -> Expectation set by CTA matches what happens next 4. CTA HIERARCHY -> One primary CTA per section/page -> Secondary CTAs visually distinct but not competing -> Ghost/outline buttons for secondary actions -> No "Cancel" bigger than "Confirm" ``` --- ## PHASE 4: CLAIM VERIFICATION (THE HINGE — POPPER FALSIFICATION) > *"Every claim is a hypothesis. Falsify it. If it survives, it earns the right to exist."* ``` THIS IS THE HINGE PHASE. Score this with 2x weight. FOR EVERY claim made anywhere on the product: 1. CLAIM INVENTORY -> Extract EVERY factual claim (numbers, performance, features) -> Extract EVERY subjective claim ("best," "fastest," "easiest") -> Extract EVERY social proof claim ("trusted by X," "Y customers") -> Extract EVERY comparison claim ("better than Z," "unlike competitors") 2. CLAIM FALSIFICATION FOR EACH CLAIM: -> Is the claim LITERALLY true? (not "kind of" true) -> Is there evidence? (data, testimonials, benchmarks) -> Could a competitor make the same claim? (if yes, it's not differentiating) -> Would a skeptical user believe it? (or does it sound like BS?) -> Is it verifiable? (can the user check it themselves?) 3. PROMISE-REALITY GAP -> "Easy to use" — is the UX actually easy? (check /flowaudit) -> "Fast" — is performance actually good? (check /perfaudit) -> "Secure" — are there actual security measures? (check /secaudit) -> "Free" — are there hidden costs or limitations? -> "Enterprise-ready" — does it actually handle enterprise scale? 4. OUTDATED CLAIMS -> User counts still accurate? -> Feature claims match current product? -> Testimonials from current customers? -> Awards/recognition still current? FALSIFY: For EVERY claim, attempt to disprove it. If you can, it must be fixed or removed. ``` --- ## PHASE 5: TONE CONSISTENCY ``` 1. TONE DEFINITION -> What is the defined brand tone? (friendly, professional, technical, playful) -> Tone documented in brand guidelines? -> Tone appropriate for target audience? 2. CROSS-PAGE CONSISTENCY -> Homepage tone matches product tone -> Marketing tone matches onboarding tone -> Error messages match app tone -> Email tone matches in-app tone -> No "fun and casual" marketing with "cold and corporate" product 3. TONE SHIFTS -> Acceptable shifts: more serious for billing, more casual for success -> Unacceptable shifts: inconsistent personality -> No "we" in some places and "I" in others (for the brand voice) -> Formality level consistent within same context ``` --- ## PHASE 6: TECHNICAL ACCURACY ``` 1. FEATURE DESCRIPTIONS -> Every described feature exists in the product -> Feature descriptions match actual behavior -> Screenshots/images show current UI (not outdated) -> Technical specifications accurate 2. INTEGRATION CLAIMS -> Listed integrations actually work -> Integration descriptions accurate -> API capabilities match documentation -> Pricing for integrations transparent 3. COMPARISON CLAIMS -> Competitor comparisons factually accurate -> Comparison tables fair (not cherry-picked metrics) -> Comparison data current (not from 2 years ago) ``` --- ## PHASE 7: GRAMMAR AND SPELLING ``` 1. MECHANICAL ERRORS -> Zero typos in user-facing copy -> Zero grammatical errors -> Consistent punctuation (Oxford comma: pick one, stick with it) -> Consistent capitalization (Title Case vs sentence case) 2. STYLE CONSISTENCY -> Product name always spelled correctly -> Feature names always capitalized consistently -> Numbers: consistent format (1,000 vs 1000) -> Dates: consistent format -> Time: consistent format (AM/PM, 24h) ``` --- ## PHASE 8: READING LEVEL ``` 1. READABILITY METRICS -> Flesch-Kincaid Grade Level per page (target: <= 8 for marketing, <= 10 for product) -> Flesch Reading Ease (target: >= 60) -> Average sentence length (target: < 20 words) -> Average paragraph length (target: < 5 sentences) 2. PLAIN LANGUAGE -> Jargon identified and simplified (or explained) -> Active voice > passive voice (percentage) -> Short words over long words where possible -> Acronyms spelled out on first use 3. SCANABILITY -> Headers break up long sections -> Bullet lists for multiple items -> Bold key phrases for scanning -> Short paragraphs (not walls of text) ``` --- ## PHASE 9: SEO KEYWORD INTEGRATION ``` 1. KEYWORD PRESENCE -> Target keywords in H1 (natural, not forced) -> Target keywords in meta title/description -> Keywords in first 100 words of body -> Keyword density appropriate (1-2%, not stuffed) 2. KEYWORD NATURALNESS -> Keywords read naturally in context -> No awkward phrasing to fit keywords -> Long-tail variations used naturally -> Semantic keywords (related terms) present 3. SEARCH INTENT MATCH -> Copy answers the search intent behind target keywords -> Informational queries get informative copy -> Commercial queries get persuasive copy -> Navigational queries get clear direction ``` --- ## PHASE 10: SOCIAL PROOF ACCURACY ``` 1. TESTIMONIAL VERIFICATION -> Testimonials from real, identifiable people -> Testimonial quotes not fabricated or heavily edited -> Attribution includes name, title, company (not "John D.") -> Testimonials relevant to the page context 2. METRICS VERIFICATION -> User counts accurate and current -> Revenue/growth claims verifiable -> Rating scores match source (4.8/5 matches G2/Capterra) -> "As seen in" logos correspond to actual coverage 3. SOCIAL PROOF PLACEMENT -> Social proof near decision points (pricing, signup) -> Relevant proof (enterprise testimonial on enterprise page) -> Not overwhelming (3-5 pieces, not 50) -> Variety (different industries, use cases, company sizes) ``` --- ## PHASE 11: LEGAL COMPLIANCE ``` 1. REQUIRED DISCLAIMERS -> Pricing disclaimers (taxes, currency, billing period) -> Trial terms (duration, auto-renewal, cancellation) -> Data handling disclaimer (cookie banner, privacy notice) -> Results disclaimers ("results may vary" where appropriate) 2. REGULATORY COMPLIANCE -> No deceptive dark patterns in copy -> Unsubscribe instructions clear in emails -> Terms of service accessible and readable -> GDPR/CCPA language in privacy policy 3. COMPETITIVE CLAIMS -> No false claims about competitors -> Comparison language defensible -> No trademark violations in copy ``` --- ## PHASE 12: MICROCOPY > *"Microcopy is the last thing written and the first thing users read."*