@damiangilgonzalez/harness 1.3.7

package/skills/marketing/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: marketing
+description: "Use when the words span a marketing surface — value proposition, section copy, microcopy, launch and email sequences, channel adaptation, SEO-aware structure — grounded in the brand study, which it stops and builds if missing. NOT one conversion page (that is `landing-copy`), NOT tone rules (that is `brand-voice`), NOT pixels (that is `design`)."
+tags: [marketing, copywriting, landing, content]
+recommends: [presentations, design]
+origin: risco
+---
+
+# Marketing — Conversion Copy for Landings & Web Pages
+
+*The words, not the pixels. Ground in the brand study first, then write copy that is specific, benefit-led, and unmistakably this brand.*
+
+This skill owns **conversion copywriting**: value proposition, headlines, section-by-section landing copy, microcopy, CTAs, email/launch sequences, channel adaptation, and SEO-aware copy structure. The sibling `design` skill owns the visual/UX (type, color, layout, motion); `nextjs` owns the build — including rendering in React the Metadata and JSON-LD this skill specifies. Long-form articles, blog posts, or social content systems with no landing/web surface are a content job, not landing copy. When asked for "a landing page", you write the copy.
+
+## Brand grounding (read this first)
+
+**Hard rule: never produce landing, web-page, or marketing copy without a complete brand study.** Generic copy is the failure mode this skill exists to prevent, and the cure is grounding every word in a real, persisted brand profile. An incomplete brand study is a hard STOP, not a warning.
+
+Run this gate before writing a single line of copy:
+
+1. **Locate the brand study.** Read the project's root `CLAUDE.md` and look for a `## Brand & voice` section linking into `docs/wiki/brand/` (the `harness` Karpathy-wiki convention: compiled brand articles live under `docs/wiki/brand/`, raw inputs the user pastes live under `docs/raw/brand/`). If `CLAUDE.md` is absent, the link is missing, or it points nowhere, treat the study as ABSENT.
+
+2. **Check completeness** against the checklist in `references/brand-grounding.md`. The study is complete only when every dimension is filled: brand name & one-line positioning; ICP / audience & their pains & desires; value proposition & differentiation; tone & voice WITH do/don't word lists and 3–5 voice samples pasted from the user's real writing; proof/credibility; offers & primary CTA; channels; SEO keywords. **Any empty dimension = INCOMPLETE.**
+
+3. **If ABSENT or INCOMPLETE, STOP and interview the user.** Ask the targeted questions from `references/brand-grounding.md`, **one focused batch at a time** (do not dump all questions at once; ask, wait, then continue). Voice samples are mandatory — request 3–5 pieces of the user's real writing; never fabricate a voice. Then:
+   - **a.** Write/update the brand study into `docs/wiki/brand/` as wiki articles (one article per dimension or a single `index.md` plus per-dimension articles), following the wiki article format in `references/brand-grounding.md`, and index it in `docs/wiki/index.md` (the Knowledge map). Save any raw text the user pastes verbatim into `docs/raw/brand/` and link to it from the article's `> Raw:` line. Create the directories if they do not exist.
+   - **b.** Add or update a `## Brand & voice` section in the root `CLAUDE.md` linking to the brand study — a short pointer only. Create `CLAUDE.md` if absent (additive only — never delete existing sections). The exact snippet to insert is in `references/brand-grounding.md`.
+
+4. **Only once the study exists and is complete, proceed.** Cite which brand articles you used (e.g. "grounded in `docs/wiki/brand/value-proposition.md` and `voice.md`") so the user can trace every claim back to the study. Every line you then write must plausibly come from the brand's own writing; if it reads like a different author, rewrite.
+
+If the user explicitly says "skip the brand study, just draft something rough", you may produce a clearly-labelled `DRAFT (ungrounded — not brand-checked)` and still recommend running the gate before anything ships. That is the only exception, and it must be labelled.
+
+Full completeness checklist, the exact question script (batched), and the persistence format → `references/brand-grounding.md`.
+
+## Copy workflow (the one pass)
+
+Run in order. Each step feeds the next; skipping one shows up as vague copy downstream.
+
+1. **Ground.** Pass the brand-grounding gate. Load value prop, ICP, voice, proof, offer, channels, keywords from `docs/wiki/brand/`.
+2. **Lock the value proposition.** Fill the value-proposition canvas (jobs / pains / gains → pain-relievers / gain-creators → headline). → `references/copy-frameworks.md`.
+3. **Pick the framework** by traffic temperature and funnel position: PAS for pain-aware cold traffic; AIDA for broad top-of-funnel; FAB/JTBD for feature → benefit; BAB for transformation/case-study. → `references/copy-frameworks.md`.
+4. **Write section by section.** Each landing section has one job and one framework. Map your copy to the design skill's section anatomy. → `references/landing-copy.md`.
+5. **Write the microcopy and CTAs.** One primary CTA per viewport — choice kills conversion — with a value verb on the button ("Start free", not "Submit"), reassurance under it ("No credit card required"), and human empty/loading/error states. → `references/copy-frameworks.md`.
+6. **Adapt for channels** if the task spans more than the page (email sequence, launch, X/LinkedIn/newsletter). → `references/campaigns-and-channels.md`.
+7. **Run the QA gate** (below) and `scripts/verify.sh`. Fix every flag or justify it.
+
+## Headlines & value proposition in 60 seconds
+
+The headline is the highest-leverage copy on the page. Build it from the canvas, not from a thesaurus. It has one test: a stranger reads the hero and can say *what it is, who it's for, why it's better* — within 5 seconds. If it fails, rewrite it before anything else on the page.
+
+```text
+VALUE-PROP CANVAS (fill before writing the headline)
+Customer job ....... the outcome they're hired to achieve
+Top pain ........... the friction that blocks the job today
+Top gain ........... what "great" looks like to them
+Pain reliever ...... how the product removes that friction
+Gain creator ....... the upside the product unlocks
+Headline ........... compress the strongest reliever+gain into one line
+Subhead ............ who it's for + how it works in one clause + proof if you have it
+```
+
+Headline formula slots (pick one, fill with brand specifics):
+
+- **Outcome + timeframe** — "Preview every branch in 30 seconds".
+- **X without Y** — "Live previews without a staging queue".
+- **JTBD** — "When you open a PR, get a live URL automatically".
+- **Specificity** — replace an adjective with a number. "Fast" is a claim; "30 seconds" is evidence: "Cut review setup from 20 min to 30 sec".
+
+```text
+Bad  — "Revolutionize your workflow with our seamless, cutting-edge platform"
+Good — "Ship a fix in 4 minutes — no YAML, no on-call page"
+```
+
+Full canvas walk-through, PAS/AIDA/FAB/BAB/JTBD with Bad→Good rewrites, headline formulas, microcopy & CTA tables → `references/copy-frameworks.md`.
+
+## Landing copy by section
+
+Each section earns its place by doing one job. Cut any section with no job. This maps 1:1 to the `design` skill's section anatomy — `design` owns the visual treatment, this skill owns the words inside it. Within every section, climb feature → benefit → proof, stop at the rung the reader cares about (the benefit), and back it with proof.
+
+| Section | Copy job | Framework |
+| --- | --- | --- |
+| Hero | State the value prop; pass the 5s test | Outcome + timeframe headline |
+| Social-proof strip | Borrow credibility instantly | Quantified, attributed |
+| Problem / agitation | Name the pain in the reader's words | PAS |
+| Solution | Show the product doing the job | FAB |
+| Features → benefits | Translate each capability into an outcome | FAB / JTBD per item |
+| Objection handling | Preempt the top reason not to buy | "X without Y" |
+| Pricing | Make the choice easy; frame value | Value framing, anchored |
+| FAQ | Answer the real blockers | Question → direct answer |
+| Final CTA | One action, value on the button | CTA verb + reassurance |
+
+```text
+Bad  (features list) — "Includes automated teardown, RBAC, and audit logs."
+Good (benefit-led)   — "Environments tear down on merge, so you never pay for idle infra
+                        or clean up by hand."
+```
+
+Full per-section copy patterns, hero variants, social-proof formats, pricing copy, FAQ writing → `references/landing-copy.md`.
+
+## Campaigns & channels
+
+When the task is bigger than the page — a launch, an email sequence, cross-channel messaging. One claim per asset: a post, an email, a section each carry one real claim, not five hedged ones.
+
+- **Email sequences:** welcome email inside 5 minutes of opt-in (highest open rate of the whole flow); 4-touch starter cadence Day 1 welcome → Day 4 educational → Day 8 case study → Day 12 soft pitch; nurture runs 7–10 emails every 1–2 weeks. One purpose per email. Hold promo language ("free", "limited time") out of early emails to protect deliverability and trust.
+- **Launch:** sequence the beats (tease → reveal → proof → urgency → recap), one claim per beat, every claim traceable to the brand study's proof.
+- **Channel adaptation:** adapt the *format* to the platform, never resize the same copy. X opens with the sharpest claim; LinkedIn expands just enough for outsiders; newsletter does real work in the first screen.
+
+Full email templates, subject-line patterns, launch arc, X/LinkedIn/newsletter adaptation, SEO-aware structure → `references/campaigns-and-channels.md`.
+
+## SEO & GEO
+
+Keep copy *SEO-aware* by default: one `<h1>`, scannable subheads that answer queries, benefit in the
+first 160 chars. Keyword stuffing *lowers* AI citation. When the task is the visibility layer itself
+— ranking on Google/Bing **and getting cited by AI engines** — go to `references/seo-geo.md`. It owns
+technical + on-page SEO, JSON-LD schema, per-engine GEO, and keyword/SERP research.
+
+- **SEO** = rank in traditional results (**Google, Bing**). **GEO** (Generative Engine
+  Optimization) = get *cited* inside an AI answer (**ChatGPT, Perplexity, Gemini/AI Overviews,
+  Claude, Copilot**). GEO sits on top of SEO; do both.
+- **The insight that reframes it:** AI engines don't rank pages, they **cite sources**. Being one of
+  the few sources an answer is built from is the new "ranking #1" — you optimize to be *quoted and
+  attributed*, not clicked.
+- **GEO and this skill agree.** The top GEO moves (Princeton, KDD 2024) are *cite sources, add
+  statistics, add quotations, authoritative tone* — the same "specificity beats adjectives, no
+  invented proof, one claim per asset" discipline this skill enforces everywhere else. Keyword
+  stuffing lowers AI citation (~−10%). The proof rule is absolute: **never fabricate the stat or
+  quote that earns the lift** — mark `[[NEEDS PROOF]]` and source it.
+- **Audit first, free, no API:** `python3 scripts/seo_audit.py "https://yoursite.com"` reports
+  title/description lengths, single-`<h1>`, JSON-LD count, load time, robots/AI-bot access, sitemap.
+- **Crawler reality (2026):** `OAI-SearchBot`/`Claude-SearchBot`/`PerplexityBot` (+ the `*-User`
+  fetchers) earn citations; `GPTBot`/`ClaudeBot` are *training* crawlers — independently
+  controllable. **INP replaced FID** in Core Web Vitals (Mar 2024; ≤ 200 ms good).
+
+Full GEO method table, robots.txt template, schema library, per-engine factors, keyword workflow,
+and SEO/GEO QA gate → `references/seo-geo.md`. Implementing schema/Metadata in code → `nextjs`.
+
+## The ban-list
+
+State once, enforce everywhere. These are defects, not style: they signal AI-template copy and erode trust. `scripts/verify.sh` greps for them.
+
+`revolutionary` · `game-changer` · `cutting-edge` · `world-class` · `unlock` · `seamless` · `elevate` · `supercharge` · `next-level` · "In today's landscape" · "In today's fast-paced world" · bait questions ("Tired of slow deploys?") · "not X, just Y" / "not just X" · forced lowercase as a style · "Excited to share" · hollow proof ("thousands trust us") · generic CTAs ("Learn more", "Click here", "Submit") · fake urgency with no real deadline.
+
+```text
+Bad  — "Excited to share our game-changing, world-class platform!"
+Good — "We rebuilt deploys around one CLI step. Here's what changed: 22 min → 90 sec."
+```
+
+The brand study's do/don't word lists EXTEND this list per project — always apply both.
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails / the fix |
+| --- | --- |
+| Skipping the brand study because "I know the brand" | Your default voice is AI-median. Run the gate; cite the articles. |
+| Leaning on the image and letting the copy stay vague | Copy carries the value prop. Pass the 5s test in words. |
+| Reaching for adjectives to sound premium | They make it sound generic. Replace with a number or mechanism. |
+| Listing every feature "so they see the value" | Feature dumps bury the benefit. Climb to benefit, back with proof. |
+| Dropping in any testimonial to fill the proof slot | A vague rave < one hard number. Quantify and attribute. |
+| Five CTAs "to give them options" | Choice kills conversion. One primary action per viewport. |
+| Hype words because "they test well" | They erode trust and trip the ban-list. Specificity converts. |
+| Inventing a plausible metric to fill a gap | Never. Mark `[[NEEDS PROOF]]` and ask the user. |
+| Reusing the same copy on X and LinkedIn | Resize ≠ adapt. Different format per platform, same claim. |
+
+## Copy QA gate
+
+Run before claiming done. `scripts/verify.sh` automates the greppable subset.
+
+- [ ] Brand study located, complete, and cited (which articles grounded this copy).
+- [ ] Hero passes the 5-second test (what / who / why-better legible fast).
+- [ ] Exactly one `<h1>`; subheads scannable and query-answering.
+- [ ] Every claim is specific (number / mechanism / receipt), not an adjective.
+- [ ] Copy climbs feature → benefit → proof; lands on the benefit.
+- [ ] One primary CTA per viewport; value on the button; reassurance microcopy present.
+- [ ] One claim per asset — no post, email, or section carrying five hedged ones.
+- [ ] No invented proof; every gap marked `[[NEEDS PROOF]]`.
+- [ ] Voice matches the brand study's samples and do/don't lists.
+- [ ] Ban-list words absent (global list + brand don't-words).
+- [ ] No passive-voice hedging or weasel words where a direct claim belongs.
+- [ ] Email subjects match the body (no bait-and-switch); promo language held out of early emails.
+- [ ] Channel copy adapted per platform, not resized.
+- [ ] Title 50–60 chars, meta description 120–160, benefit in the first 160 chars.
+
+Automate → `scripts/verify.sh` (read-only grep gate; warns by default, `--strict` to gate CI).

package/skills/marketing/evals/README.md

@@ -0,0 +1,61 @@
+# Eval harness — `marketing` skill
+
+These evals check two things: that the skill **triggers** on the right prompts
+(and stays quiet on near-misses), and that it **measurably improves** copy/SEO
+output. Cases live in `cases.yaml`. There is no pure shell runner — grading is
+done by an **agent harness** (a Claude Code agent with skills loaded) plus a
+human spot-check, because triggering and copy quality are judgment calls.
+
+## What's in `cases.yaml`
+
+- `should_trigger` — prompts that MUST load `marketing`.
+- `should_not_trigger` — near-misses that must route elsewhere (`route_to`).
+- `capability` — scenarios with a `must_include` rubric to grade with vs without.
+
+## Triggering eval
+
+Goal: the skill fires when it should and never on a near-miss.
+
+1. Configure an agent with the **full catalog of skill descriptions** available
+   for routing (marketing + design, nextjs, postgresdb, secure-coding, go,
+   flutter, presentations, course-storytelling, building-agents, deployment,
+   harness, init) so routing competes realistically.
+2. For each `should_trigger` prompt: feed it cold, record whether `marketing`
+   is the skill the agent loads. Run **3-5 trials** per prompt (fresh context).
+3. For each `should_not_trigger` prompt: confirm `marketing` does NOT load, and
+   that the chosen skill matches `route_to` (or that it correctly declines when
+   `route_to: none`). Same 3-5 trials.
+4. Score: `triggered_correctly / total_trials` across both lists.
+
+**Pass bar: >= 90% trigger accuracy** over all prompts and trials, with **zero
+systematic false-positives** on the `design`/`nextjs` near-misses (those are the
+known traps — a landing-page prompt about pixels or the build must not pull in
+marketing).
+
+## Capability eval
+
+Goal: prove the skill changes the answer, not just the routing.
+
+1. For each `capability` scenario, run it **twice**:
+   - **WITHOUT** the skill (base agent, no `marketing` loaded).
+   - **WITH** the `marketing` skill loaded.
+2. Grade each output against that scenario's `must_include` checklist — one
+   point per checkable item covered. A human or a grading agent marks each
+   item present / absent.
+3. Compute coverage = `items_covered / total_items` for each run.
+
+**Pass bar: WITH the skill covers >= 80% of `must_include`; WITHOUT clearly
+lower** (target a >= 30-point gap). The skill must demonstrably add the
+brand-grounding STOP, specificity-over-adjectives, single-CTA discipline, the
+ban-list, `[[NEEDS PROOF]]`, and the SEO/GEO + JSON-LD spec. If the base answer
+already scores ~80%, the case isn't discriminating — tighten the rubric.
+
+## Notes on honesty
+
+- Trials are stochastic; report the raw fraction, not a rounded "pass".
+- Brand-gate behavior is the highest-signal capability check: a correct answer
+  refuses to write grounded copy with no brand study and interviews instead.
+  Treat a confident, ungrounded full-page draft as a **capability failure** even
+  if the prose reads well.
+- Re-run after any edit to `SKILL.md` or its `references/` — wording changes
+  shift both triggering and rubric coverage.

package/skills/marketing/evals/cases.yaml

@@ -0,0 +1,84 @@
+skill: marketing
+
+# Prompts that MUST load the `marketing` skill. The skill owns the WORDS of a
+# landing/web/launch surface: value prop, hero, section copy, microcopy, CTAs,
+# email/launch sequences, channel adaptation, and SEO/GEO (technical SEO,
+# JSON-LD spec, AI-engine citation). It does NOT own pixels (design) or the
+# build (nextjs).
+should_trigger:
+  - prompt: "Write the hero and section copy for our new pricing page."
+    why: "Section-by-section landing copy and hero headline are the skill's core conversion-copywriting job."
+
+  - prompt: "Our homepage above-the-fold reads generic and sounds like every other AI startup — can you fix it?"
+    why: "Rescuing copy that 'sounds like AI' / reads generic is an explicit trigger; the ban-list and brand-grounding exist for exactly this."
+
+  - prompt: "Turn this feature list into something a customer would actually care about: SSO, audit logs, 99.9% uptime."
+    why: "Translating features into benefits (FAB/JTBD, climbing feature -> benefit -> proof) is a named use, even though the user never says 'marketing' or 'copy'."
+
+  - prompt: "We launch Tuesday — I need a 4-email sequence and a post for X and LinkedIn announcing it."
+    why: "Launch email sequences plus per-channel adaptation are owned by the campaigns-and-channels part of the skill; user names channels, not the skill."
+
+  - prompt: "How do I get our docs page cited by ChatGPT and Perplexity, and what JSON-LD schema should it have?"
+    why: "GEO (getting cited by AI engines) and specifying JSON-LD schema are explicit SEO/GEO triggers owned by references/seo-geo.md (spec, not the React render)."
+
+  - prompt: "What should the button say and what's the reassurance line under it on our signup CTA?"
+    why: "Microcopy and CTAs (value on the button, friction-reducing reassurance) are an explicit copy job, phrased without naming the skill."
+
+  - prompt: "Give me a one-line value proposition and subhead for a tool that previews every PR branch automatically."
+    why: "Locking the value proposition via the canvas and producing the headline/subhead is the highest-leverage copy task the skill defines."
+
+  - prompt: "Our meta titles and descriptions are a mess and the benefit is buried — can you sort out the on-page copy structure so we rank better?"
+    why: "SEO-aware copy structure (one h1, query-answering subheads, title 50-60 / meta 120-160, benefit in first 160 chars) is owned here, not in design or nextjs."
+
+# NEAR-MISS prompts that must NOT load `marketing`. Each routes to the genuinely
+# correct sibling. The recurring trap: anything touching a "landing page" that
+# is actually about pixels (design) or the build (nextjs), and anything that is
+# article/blog content rather than a landing/launch surface.
+should_not_trigger:
+  - prompt: "Pick the type scale, color palette, and spacing for our landing page hero section."
+    route_to: "design"
+    why: "Type/color/spacing/layout is the pixels, explicitly delegated to design; marketing only owns the words inside the section."
+
+  - prompt: "Implement the landing page hero in Next.js with the Metadata API and render the JSON-LD in the page."
+    route_to: "nextjs"
+    why: "Building the page in React/Next and rendering schema/Metadata in code is the build; marketing specifies the title/description/JSON-LD, nextjs renders it."
+
+  - prompt: "Write a 2000-word blog post explaining how our deployment pipeline works."
+    route_to: "none"
+    why: "Long-form article with no landing/web/launch surface is a content job the skill explicitly stays out of; no sibling owns generic blogging, so it declines."
+
+  - prompt: "Write a CHECK constraint and a partial index to enforce one primary CTA row per campaign in Postgres."
+    route_to: "postgresdb"
+    why: "Despite the word 'CTA', this is pure SQL schema/constraint work owned by postgresdb, not conversion copy."
+
+  - prompt: "Add a honeypot field and rate-limit the newsletter signup endpoint to stop spam submissions."
+    route_to: "secure-coding"
+    why: "Abuse prevention / input hardening on a form endpoint is a security concern, not the words on the page."
+
+  - prompt: "Design the motion and scroll-reveal animations for the features section of our marketing site."
+    route_to: "design"
+    why: "Motion and section visual anatomy are design's domain; marketing owns the copy, not the animation."
+
+# Concrete tasks the skill should guide, with a rubric to grade WITH vs WITHOUT
+# the skill loaded. A correct skill-guided answer should hit most must_include
+# points; an ungrounded answer typically misses the brand gate, specificity,
+# and the QA discipline.
+capability:
+  - scenario: "Write the hero (headline + subhead + primary CTA) for a tool that spins up a live preview URL on every pull request. No brand study exists in the repo yet."
+    must_include:
+      - "STOPS on the brand-grounding gate first: notes there is no complete brand study under docs/wiki/brand/ and interviews the user (ICP, positioning, voice samples) before writing — or, only if the user explicitly says draft rough, labels output 'DRAFT (ungrounded — not brand-checked)'."
+      - "Headline built from the value-prop canvas using a concrete formula (outcome+timeframe, 'X without Y', or JTBD), e.g. specificity like '30 seconds' rather than adjectives."
+      - "Passes the 5-second test: a stranger can tell what it is, who it's for, and why it's better."
+      - "Specificity over adjectives — no 'fast/powerful/seamless'; uses a number or mechanism, and marks any unverifiable metric as [[NEEDS PROOF]] rather than inventing it."
+      - "Exactly one primary CTA with value on the button ('Start free', not 'Submit'/'Learn more') plus friction-reducing reassurance microcopy ('No credit card required')."
+      - "Avoids every ban-list word (revolutionary, game-changer, seamless, supercharge, unlock, etc.) and matches the brand's voice samples."
+      - "Subhead names who it's for + how it works in one clause, keeping it SEO-aware (benefit in the first 160 chars)."
+
+  - scenario: "Make our product page get cited by AI engines (ChatGPT, Perplexity, Gemini/AI Overviews) and rank better on Google. Tell us exactly what to change."
+    must_include:
+      - "Distinguishes SEO (rank in Google/Bing results) from GEO (get cited inside an AI answer) and states GEO sits on top of SEO — do both."
+      - "Recommends the proven GEO moves: cite sources, add statistics, add quotations, authoritative tone — and warns keyword stuffing LOWERS AI citation."
+      - "Specifies JSON-LD / schema and on-page structure (one <h1>, query-answering subheads, title 50-60 chars, meta description 120-160, benefit in first 160 chars) — as a spec, deferring the React/Metadata render to nextjs."
+      - "Never fabricates the stat/quote that earns the lift; marks gaps [[NEEDS PROOF]] and asks the user to source them."
+      - "Mentions crawler reality: search/citation bots (OAI-SearchBot, Claude-SearchBot, PerplexityBot) vs training crawlers (GPTBot, ClaudeBot) are controlled independently in robots.txt."
+      - "Suggests an audit-first step (e.g. scripts/seo_audit.py on the URL) before prescribing changes."

package/skills/marketing/references/brand-grounding.md

@@ -0,0 +1,217 @@
+# Brand Grounding — Checklist, Question Script & Persistence
+
+The brand study is the source of truth every piece of marketing copy is grounded in. This file holds the **completeness checklist** (what "complete" means), the **question script** (how to interview the user, batched), and the **persistence format** (how to write it into `docs` and link it from `CLAUDE.md`). The runtime mechanism that invokes this — the hard STOP on an incomplete study — lives in `SKILL.md` under "Brand grounding (read this first)".
+
+## Where the brand study lives
+
+Following the `harness` Karpathy-wiki convention:
+
+```text
+docs/
+├── raw/brand/         ← immutable: voice samples + raw inputs pasted verbatim by the user
+│   ├── voice-sample-1.md
+│   ├── voice-sample-2.md
+│   └── …
+└── wiki/brand/        ← compiled brand study, one article per dimension
+    ├── index.md            ← positioning one-liner + links to every dimension article
+    ├── audience.md         ← ICP, pains, desires
+    ├── value-proposition.md← value prop, differentiation
+    ├── voice.md            ← tone, do/don't word lists, links to raw voice samples
+    ├── proof.md            ← credibility, metrics, customers, guarantees
+    ├── offers.md           ← offers + primary/secondary CTA
+    ├── channels.md         ← active channels + per-channel notes
+    └── seo.md              ← target keywords + intent
+```
+
+Small projects may collapse this into a single `index.md` with all eight sections as `##` headings — but every dimension must still be present and filled.
+
+## Completeness checklist
+
+The study is **COMPLETE** only when every dimension below is filled with real, specific content. Any empty, placeholder, or "TBD" dimension = **INCOMPLETE** = hard STOP, interview the user.
+
+- [ ] **1. Brand name & one-line positioning** — the name, and one sentence: "[Brand] helps [audience] [achieve outcome] by [mechanism]." No jargon, no feature list.
+- [ ] **2. ICP / audience, pains & desires** — who exactly (role, context, sophistication); the top 2–3 pains in their own words; the top 2–3 desires/gains; the alternatives they use today.
+- [ ] **3. Value proposition & differentiation** — the core benefit in one sentence; what makes it different from the named alternatives; the one thing only this brand can credibly say.
+- [ ] **4. Tone & voice** — tone descriptors (3–5 adjectives); a **do-words** list; a **don't-words** list; and **3–5 voice samples pasted from the user's real writing** (posts, emails, docs, prior copy). Samples are mandatory; a voice cannot be inferred without them.
+- [ ] **5. Proof & credibility** — real metrics, named customers/logos, quantified testimonials, certifications, guarantees, or traction the brand can stand behind. Mark anything aspirational as `[[NEEDS PROOF]]`, never present it as fact.
+- [ ] **6. Offers & primary CTA** — what the visitor is being asked to do (sign up, book a demo, buy, join waitlist); the primary CTA verb; any secondary CTA; pricing model if relevant.
+- [ ] **7. Channels** — where this brand actually publishes (landing page, X, LinkedIn, newsletter, email, ads); the priority order; any per-channel constraints.
+- [ ] **8. SEO keywords** — the primary keyword/theme and 3–5 secondary keywords or query phrases the audience actually searches. (This captures intent only; the keyword/SERP workflow and technical SEO/GEO live in `seo-geo.md`.)
+
+## Question script (ask in batches, never all at once)
+
+Ask **one batch at a time**. Send the batch, wait for the answer, persist what you learned, then send the next batch. Skip questions a located-but-incomplete study already answers — only fill the gaps. Stop interviewing the moment all eight dimensions are complete.
+
+### Batch 1 — identity & audience
+
+```text
+1. What's the brand/product name, and in one sentence: who is it for and what outcome does it deliver?
+2. Describe your ideal customer precisely — their role, context, and how sophisticated they are about this problem.
+3. In THEIR words, what are the top 2–3 pains that make them look for something like you?
+4. What does "great" look like to them — the top 2–3 things they actually want?
+5. What do they use today instead of you (tools, workarounds, "doing nothing")?
+```
+
+### Batch 2 — value & proof
+
+```text
+6. In one sentence, what's the core benefit — no feature list, no jargon?
+7. What makes you genuinely different from the alternatives you just named?
+8. What's the one thing only YOU can credibly claim?
+9. What proof can you stand behind right now? (metrics, named customers, testimonials with
+   numbers, certifications, guarantees). If something is aspirational, say so — I'll mark it
+   as needing proof rather than state it as fact.
+```
+
+### Batch 3 — voice (samples are mandatory)
+
+```text
+10. Pick 3–5 adjectives for how the brand should sound (e.g. direct, dry, warm, technical).
+11. Give me a DO list and a DON'T list of words/phrases — things you always say, and things
+    you never want to see.
+12. Paste 3–5 samples of your REAL writing — posts, emails, docs, prior copy. This is how I
+    match your voice instead of inventing a generic one. (I'll save these verbatim under
+    docs/raw/brand/.)
+```
+
+### Batch 4 — offer, channels, SEO
+
+```text
+13. What's the single action you want visitors to take? (sign up, book a demo, buy, join a
+    waitlist…) And is there a secondary action?
+14. What's your pricing model, if any?
+15. Which channels do you actually publish on, and in what priority? (landing page, X,
+    LinkedIn, newsletter, email, ads)
+16. What 1 primary + 3–5 secondary keywords or phrases does your audience actually search?
+```
+
+If the user can't answer a question, that dimension stays incomplete — note the gap, keep the STOP in place for that dimension, and offer to draft a hypothesis they can confirm rather than fabricating an answer.
+
+## Persistence format
+
+### Brand wiki article template
+
+Each `docs/wiki/brand/*.md` article follows the harness wiki format. It is an OKF v0.1 article: open it with YAML frontmatter carrying a non-empty `type:` (`brand-study`), then the H1 and body:
+
+```markdown
+---
+type: brand-study
+title: Brand — Value Proposition
+description: The core benefit and what makes this brand different from the named alternatives.
+tags: [brand, value-proposition]
+timestamp: YYYY-MM-DDTHH:MM:SSZ
+topic: brand
+status: stable
+---
+
+# Brand — Value Proposition
+
+> Sources: {user interview, YYYY-MM-DD}
+> Raw: [voice-sample-1](../../raw/brand/voice-sample-1.md)
+
+## Overview
+
+One paragraph: the core benefit and what makes it different.
+
+## Core benefit
+
+[Brand] helps [audience] [achieve outcome] by [mechanism].
+
+## Differentiation
+
+- vs [alternative A]: …
+- vs [alternative B]: …
+
+## The one credible claim
+
+…
+
+## See Also
+
+- [Audience](audience.md)
+- [Proof](proof.md)
+```
+
+### Voice article specifics
+
+`voice.md` must contain the do/don't word lists and link to every raw sample (same OKF frontmatter; `type: brand-study`):
+
+```markdown
+---
+type: brand-study
+title: Brand — Tone & Voice
+description: Tone descriptors, do/don't word lists, and the voice fingerprint extracted from real samples.
+tags: [brand, voice, tone]
+timestamp: YYYY-MM-DDTHH:MM:SSZ
+topic: brand
+status: stable
+---
+
+# Brand — Tone & Voice
+
+> Sources: {user interview, YYYY-MM-DD}
+> Raw: [sample-1](../../raw/brand/voice-sample-1.md); [sample-2](../../raw/brand/voice-sample-2.md)
+
+## Tone
+
+direct · dry · technical · respects the reader's time
+
+## Do-words
+
+ship, concrete, mechanism, receipt, in <time>
+
+## Don't-words
+
+revolutionary, seamless, unlock, leverage, synergy, "excited to share"
+
+## Voice fingerprint (extracted from samples)
+
+- Sentence rhythm: short, declarative; one idea per sentence.
+- Specifics over adjectives; numbers and mechanisms appear often.
+- Parentheticals used for qualification, not for jokes.
+- Never opens with a bait question.
+
+## Voice samples
+
+Stored verbatim under `docs/raw/brand/` — see Raw links above.
+```
+
+### Raw samples
+
+Paste each user-provided writing sample verbatim into its own `docs/raw/brand/voice-sample-N.md` with a one-line provenance header:
+
+```markdown
+> Source: user-pasted, YYYY-MM-DD, origin: "LinkedIn post about the v2 launch"
+
+<the sample text, unedited>
+```
+
+### CLAUDE.md link
+
+Add (or update) this section in the root `CLAUDE.md`. Additive only — never delete existing sections. Create `CLAUDE.md` if absent.
+
+```markdown
+## Brand & voice
+
+Marketing and landing copy is grounded in the brand study under
+`docs/wiki/brand/`. Read it before writing any user-facing copy:
+
+- [Positioning](docs/wiki/brand/index.md)
+- [Audience](docs/wiki/brand/audience.md)
+- [Value proposition](docs/wiki/brand/value-proposition.md)
+- [Voice & tone](docs/wiki/brand/voice.md)
+- [Proof](docs/wiki/brand/proof.md)
+- [Offers & CTA](docs/wiki/brand/offers.md)
+- [Channels](docs/wiki/brand/channels.md)
+- [SEO keywords](docs/wiki/brand/seo.md)
+
+Raw voice samples and inputs: `docs/raw/brand/`.
+The `marketing` skill maintains this study and stops to interview the user
+if any dimension is missing.
+```
+
+## See Also
+
+- `../SKILL.md` — the runtime grounding mechanism (hard STOP) that uses this checklist.
+- `copy-frameworks.md` — turns the value proposition and voice into headlines and copy.
+- `harness` — the canonical `docs` wiki protocol and article templates.