Skill: quochungto/bookforge-curse-of-knowledge-detector (version 1.0.0)

--- name: curse-of-knowledge-detector description: Diagnose a draft for the Curse of Knowledge — the expert blind spot that makes insiders write copy full of unexplained jargon, buried assumptions, strategy-level abstractions, and tacit shared context that lose non-expert audiences. Use this skill whenever reviewing a pitch, announcement, explainer, landing page, onboarding doc, slide, internal memo, or technical write-up for clarity to a non-expert. Activate when the user says things like "why isn't my message landing", "make this clearer", "my audience doesn't get it", "I can't tell if this is too technical", "diagnose this draft", "is this too jargony", "expert blind spot", "tapper listener", "translate for non-experts", "audit this for jargon", "I'm too close to this", or provides a draft plus an audience description and asks for a clarity critique. Also triggers when a user complains that smart readers stare blankly at their copy, when an explainer is full of acronyms, when an announcement leads with context instead of news, or when a strategy deck reads like a mission statement generator. This skill does NOT rewrite the draft end-to-end (that is the message-clinic skill) and does NOT score the full SUCCESs rubric (that is the stickiness-audit skill) — it produces a targeted report of Curse-of-Knowledge violations with locations, reasons, and rewrite guidance. version: 1.0.0 homepage: https://github.com/bookforge-ai/bookforge-skills/tree/main/books/made-to-stick/skills/curse-of-knowledge-detector metadata: {"openclaw":{"emoji":"📚","homepage":"https://github.com/bookforge-ai/bookforge-skills"}} status: draft source-books: - id: made-to-stick title: "Made to Stick: Why Some Ideas Survive and Others Die" authors: ["Chip Heath", "Dan Heath"] chapters: [1, 12, 13] tags: [communication, clarity, diagnostic, expert-blind-spot, jargon-detection, copywriting, messaging, audit, writing, plain-language] depends-on: [] execution: tier: 1 mode: hybrid inputs: - type: document description: "Draft to audit — a message, pitch, announcement, explainer, slide, memo, or product page as markdown or pasted text" - type: document description: "Audience description — who the draft is for, what they know, what they do not know" tools-required: [Read, Write] tools-optional: [Grep] mcps-required: [] environment: "Any agent environment with file read/write. Document-set working environment: the agent operates on short-form prose drafts provided by the user." discovery: goal: "Surface every passage in a draft where expert blind spots lose a non-expert audience, with concrete rewrite guidance." tasks: - "Audit a pitch or announcement for jargon, abstractions, and buried assumptions" - "Diagnose why an expert-written explainer is not landing with non-expert readers" - "Produce a flagged-passage report before running a full rewrite" audience: roles: [marketer, founder, communicator, product-manager, teacher, technical-writer] experience: any when_to_use: triggers: - "User provides a draft and an audience description and asks for a clarity review" - "User complains that smart readers are confused by their copy" - "Draft is authored by a subject-matter expert for a non-expert audience" prerequisites: [] not_for: - "Rewriting the draft end-to-end — use a message-clinic skill instead" - "Scoring the full six-principle stickiness rubric — use a stickiness-audit skill" environment: codebase_required: false codebase_helpful: false works_offline: true --- # Curse of Knowledge Detector ## When to Use You have a draft (a pitch, announcement, explainer, slide, landing page, memo, or product write-up) authored by someone who knows the subject deeply, and you need to find the specific places where that expertise has corrupted clarity for a non-expert audience. Use this skill when the goal is **diagnosis, not rewriting** — you want a ranked list of Curse-of-Knowledge violations the user can act on (or hand to a rewriting skill). **Preconditions to verify before starting:** - The draft exists as text the agent can read (paste, markdown file, or document). - The audience is named and at least roughly profiled — without a target audience, "too expert" is undefined. - The user wants a critique, not a full rewrite. If they want a rewrite, hand off to `message-clinic-runner` after producing the report. **The Curse of Knowledge, restated for the agent:** Once someone knows something, they cannot imagine not knowing it. Experts "tap" a tune they can hear in their own head (Elizabeth Newton's 1990 Stanford study: tappers predicted listeners would guess 50% of tunes; listeners got 2.5% — a 20x gap). The same expertise that produced the Answer backfires during the Telling Others stage. This skill catches the tapping. --- ## Context & Input Gathering ### Required Context (must have — ask if missing) - **The draft:** The actual text to audit — not a summary. -> Check prompt for: pasted text, file path, document attachment. -> Ask if missing: "Paste the draft you want me to audit, or give me the file path." - **The target audience:** Who the draft is for, and — critically — what they do NOT already know. -> Check prompt for: audience description, persona, reader profile. -> Ask if missing: "Who is this draft for? Tell me (a) their role, (b) what they already know about the subject, and (c) what you think they do not know. One sentence each is fine." ### Observable Context (gather from environment) - **Author expertise domain:** Often visible in the prose (heavy acronyms, named frameworks, implied processes). -> Infer from: density of jargon, tone, structural choices. -> If unclear: ask one question — "Is the author a subject-matter expert in [X]?" - **Prior attempts:** A note like "I already tried simplifying it" changes the rewrite guidance — you push for more radical reframing, not another smoothing pass. -> Look for: user comments about previous drafts. ### Default Assumptions - **Assumption: the author is closer to the subject than the reader.** State this in the report. The Curse is a one-way disease — detection assumes the author is the "tapper," not the "listener." - **Assumption: the audience cannot ask follow-up questions.** Drafts are typically read asynchronously. If the audience can ask, note the change in severity (Q&A recovers some clarity; it does not cure the Curse). ### Sufficiency Threshold - **SUFFICIENT:** Draft text + audience description with at least role and "what they do not know." - **PROCEED WITH DEFAULTS:** Draft + role-only audience. Flag the missing "does not know" list in the report so the user can supply it later. - **MUST ASK:** No draft, OR audience is "general public" with no narrowing (too vague — every reader is different and the skill cannot detect insider assumptions without a contrast point). --- ## Process ### Step 0: Initialize task tracking **ACTION:** Create a TodoWrite checklist with the steps below. **WHY:** This is a multi-pass audit. Tracking prevents the agent from fusing passes into a single shallow scan, which is the failure mode that produces "looks fine to me" false negatives. Each pass has a different target and must run independently. ### Step 1: Establish the "listener baseline" **ACTION:** Write a one-paragraph profile of the audience in plain terms. List explicitly: (a) vocabulary they know, (b) vocabulary they do NOT know, (c) processes/workflows they understand, (d) processes they do NOT understand, (e) prior context they have, (f) prior context they lack. Use the audience description supplied by the user and your own reasoning. **WHY:** You cannot detect Curse-of-Knowledge violations without a contrast point. The tapper/listener experiment works because the listener's state of mind is knowable (they literally cannot hear the tune). For a draft, you simulate the listener by writing down, up front, what the listener can and cannot hear. Every subsequent flag is scored against THIS baseline, not a generic "average reader." **Save:** The listener baseline as the first section of the output report. ### Step 2: Pass A — Unexplained jargon, acronyms, and named frameworks **ACTION:** Scan the draft and flag every term that appears in the draft but not in the listener baseline's "vocabulary they know" list. Include: acronyms (including common-in-industry ones the audience may not share), proper nouns referring to internal tools/products/projects, named frameworks (e.g., "SUCCESs framework", "Sinatra Test"), technical verbs used as nouns ("a retro", "a standup"), and metaphors borrowed from a sub-field the audience does not live in. **WHY:** Jargon is the most visible Curse-of-Knowledge symptom. It is also the easiest to miss in self-review because the author reads every term as transparent. A mechanical pass catches what an "impression pass" glosses over. **For each hit record:** location (quote or line reference), the term, why a listener would not parse it, and a rewrite option (define on first use, swap for a common-language equivalent, or remove if not load-bearing). ### Step 3: Pass B — Abstraction ladder (strategy-level talk) **ACTION:** Re-read each paragraph and ask: "Is the sentence operating at the level of STRATEGY (goals, visions, synergies, principles) or the level of ACTION (observable behavior, physical object, named person, concrete step)?" Flag sentences that live at the strategy level without ever dropping to the action level. Apply the Boeing 727 test: "If this were replaced by a concrete constraint ('seat 131 passengers, land on Runway 4-22, one mile long'), would the sentence lose meaning or gain it?" If concrete constraints GAIN meaning, the abstract original is a Curse-of-Knowledge hit. **WHY:** Experts prefer the strategy level because they have internalized the concrete layer and find it tedious. Non-experts can only anchor to concrete objects, people, and behaviors ("bishops moving diagonally," not "chess strategy"). Abstract-only copy is readable but un-actionable — the reader finishes the paragraph and cannot say what anyone would DO differently tomorrow. This is exactly what the JFK "man on the moon" example contrasts with the modern-CEO "maximize shareholder value" failure mode. **For each hit record:** location, the abstract phrase, a specific concrete translation (actor + verb + observable object), and whether the fix is "add a concrete example" or "replace the abstraction entirely." ### Step 4: Pass C — Buried assumptions and tacit shared context **ACTION:** For each claim in the draft, ask: "What does the reader have to ALREADY believe or know for this sentence to land?" Write the implicit premise. Then check it against the listener baseline. If the premise is not on the listener's "known" list, the sentence is a Curse-of-Knowledge hit even if every word is plain English. **WHY:** This is the subtlest axis and the one where "it sounds clear" audits miss the most. A sentence like "we're deprecating the legacy pipeline" has no jargon to the author — but assumes the reader knows (a) there is a pipeline, (b) there is a legacy version and a new version, (c) "deprecate" is a soft word for "turning off," and (d) the reader is a stakeholder in the decision. Each of those assumptions is a tapper tapping a tune. Surfacing the buried premises IS the diagnosis. **For each hit record:** location, the explicit premise the reader must hold, whether the listener baseline shows they hold it, and a rewrite option (state the premise, link to a primer, or restructure). ### Step 5: Pass D — Buried lead and common-sense sedation **ACTION:** Read the first sentence of the draft. Ask: "Is this the single most important thing the reader must walk away with?" If not, flag "buried lead" (the Nora Ephron journalism-teacher test: the lead is `there will be no school Thursday`, not `principal announces faculty retreat`). Then scan the draft for sentences every member of the audience would nod and agree with before reading — "customer service is important," "communication is key." Flag these as "common sense sedation." Both failure modes are Curse-of-Knowledge symptoms: the author is leading with context they already know, or stating positions so internalized they feel like news to the author but are invisible to the reader. **WHY:** The Heaths frame "burying the lead" as the first villain named after the Curse in the Epilogue — "we're tempted to share it all" because we know it all. Common-sense statements are a second-order Curse effect: the author forgot what it was like not to already agree. Both pass the plain-English test but fail the stickiness test. **For each hit record:** location, the failure mode (buried-lead OR common-sense), and one concrete replacement sentence. ### Step 6: Synthesize the report **ACTION:** Combine the four pass outputs into a single prioritized report with this structure: 1. **Listener baseline** (from Step 1). 2. **Tapper/listener gap estimate** — your one-sentence summary of the delta between what the draft assumes and what the listener baseline actually holds. Be specific. ("Author assumes reader knows what a feature flag is, what rollout means, and why staged rollouts reduce risk. Listener baseline shows none of these are held.") 3. **Top 3 rewrite targets** — the three highest-impact hits across all four passes, ranked by (severity × how much of the draft they poison). Each gets: quote, pass it came from, why it hurts, specific rewrite. 4. **Full flagged-passage table** — every hit from Passes A–D with columns: location, passage, pass (A/B/C/D), why, rewrite guidance. 5. **Listener simulation test** — three to five questions the listener baseline-reader would plausibly ask the author after reading the draft. These are the gaps the rewrite must close. 6. **Handoff note** — one sentence saying whether the draft needs jargon substitution (lightweight), structural rework (lead repositioning + abstraction concretization), or a full rewrite from the core message up. **WHY:** The user asked for diagnosis, not a pile of annotations. The top-3 ranking and the handoff note tell them what to DO with the report. Without prioritization, a long flagged-passage table produces analysis paralysis — the exact anti-pattern Made to Stick warns against in Chapter 1. **Save:** The full report to `curse-of-knowledge-report.md` in the user's working directory. ### Step 7: Structural self-check **ACTION:** Before returning, verify: (a) every flagged passage has a location, a reason, and a rewrite option — not just "unclear"; (b) the listener baseline is specific enough that someone else could re-run the audit and reach similar conclusions; (c) the top-3 are actually ranked, not just listed; (d) the handoff note is one decisive sentence, not a hedge. **WHY:** The audit's value is in its specificity. A report that says "some parts could be clearer" is indistinguishable from generic AI advice — it produces no delta over a baseline agent. Specificity (location + reason + rewrite) is what makes the skill book-derived rather than generic. --- ## Inputs - `draft` — the text to audit (markdown, pasted text, or file path). - `audience` — a description of the target reader, minimum role + "what they do not know." - Optional: `mode_note` — "lightweight pass" or "full four-pass audit" (default: full). ## Outputs A single file, `curse-of-knowledge-report.md`, with this shape: ```markdown # Curse of Knowledge Report — {draft name} ## Listener Baseline {audience role, known vocabulary, unknown vocabulary, known processes, unknown processes, held context, missing context} ## Tapper/Listener Gap Estimate {one-sentence delta} ## Top 3 Rewrite Targets 1. **{quote}** — Pass {X}. Why: {reason}. Rewrite: {concrete fix}. 2. ... 3. ... ## Flagged Passages (Pass A: Jargon) | Location | Passage | Why a listener cannot parse it | Rewrite | ## Flagged Passages (Pass B: Abstraction) | Location | Passage | Abstract level | Concrete translation | ## Flagged Passages (Pass C: Buried Assumptions) | Location | Passage | Implicit premise | Present in listener baseline? | Rewrite | ## Flagged Passages (Pass D: Buried Lead / Common Sense) | Location | Passage | Failure mode | Replacement sentence | ## Listener Simulation Questions - Q1: {a question the listener baseline-reader would ask after reading} - ... ## Handoff Note {one decisive sentence: jargon substitution | structural rework | full rewrite} ``` --- ## Key Principles - **You cannot cure the Curse, only route around it.** The Heaths are explicit: "There are only two ways to beat the Curse of Knowledge reliably. The first is not to learn anything. The second is to take your ideas and transform them." Detection means finding what must be transformed — not guilting the author into "trying harder to be clear." - **The listener baseline is the only ground truth.** Every flag is relative to a specific listener profile. A term that is "jargon" to a recruit is "common language" to an engineer on the same team. If you skip the baseline and audit against a generic reader, you produce generic feedback — which is exactly the delta gap the skill is supposed to close. - **Multi-pass beats single-pass.** Each pass targets a different axis (lexical, structural, tacit, prioritization). Fused into one pass, the agent defaults to the most visible axis (jargon) and misses the subtler ones (buried assumptions, common-sense sedation). The book's entire methodology is structured this way — six principles, each addressed on its own — because human authors cannot hold all axes at once. - **Specificity is the value.** "This paragraph is too abstract" is free advice. "Replace `maximize shareholder value` with `grow revenue by 20% this year by winning back 10 lapsed accounts` (actor + verb + measurable object)" is the skill. Every flag must include a concrete rewrite option or it is noise. - **Prioritize ruthlessly; report faithfully.** The top-3 is the action surface. The full table is the audit trail. Without the top-3, the user drowns in findings (decision paralysis — a named Made to Stick failure mode). Without the full table, the user cannot trust the top-3. Both are required. - **The author is not the villain.** Curse-of-Knowledge is a natural psychological tendency, not a skill deficit. Frame the report so the author can see the failure mode as structural — "here is where your expertise created a gap" — not as criticism. --- ## Examples **Scenario: Product announcement for a developer tool, audience is non-technical buyers** Trigger: User pastes a 400-word announcement that opens "We're shipping v2 of our feature-flag rollout engine with staged canaries and blast-radius controls." Audience: "VP of Engineering buyers at mid-market SaaS companies — they manage engineers but haven't written code in five years." Process: (1) Listener baseline notes "feature flag" = probably known, "canary", "blast radius" = probably not known, "staged rollout" = known in principle, "rollout engine" = ambiguous. (2) Pass A flags `canaries`, `blast-radius`, `rollout engine`. (3) Pass B flags the abstract noun "controls" with no concrete behavior. (4) Pass C flags the buried assumption that the reader already wanted v2. (5) Pass D flags the buried lead — the actual news ("our tool now prevents the top three rollout-caused outages buyers told us about") is in paragraph 4. Output: `curse-of-knowledge-report.md` with Top 3 = (1) move the paragraph-4 news to sentence 1, (2) define `canary` on first use as "a small slice of users who see the change first", (3) replace "blast-radius controls" with "automatic rollback if error rate crosses a threshold you set." Handoff note: "Structural rework — lead repositioning plus three jargon substitutions." **Scenario: Nonprofit fundraising letter, audience is first-time donors** Trigger: User pastes a 600-word letter from a global-health nonprofit that leads with program architecture, regional coverage statistics, and the M&E framework. Audience: "First-time individual donors, $25–$100 range, no prior engagement with global health." Process: (1) Listener baseline: knows what a nonprofit is, does not know `M&E`, `catchment area`, `DALY`, does not know the named regions, does not know the organization's history. (2) Pass A flags four acronyms. (3) Pass B flags "program architecture" and "regional coverage" as strategy-level. (4) Pass C flags the assumption that the reader already cares about sub-Saharan maternal health statistics. (5) Pass D flags the buried lead (there is no Rokia-style individual named person) and flags "we are committed to lasting impact" as common-sense sedation. Output: Top 3 = (1) open with a named beneficiary (the Mother Teresa / Rokia effect — identifiable victim beats statistics), (2) replace `M&E`, `DALY`, and `catchment area` with plain equivalents or cut them, (3) cut the "committed to lasting impact" sentence entirely. Handoff note: "Full rewrite from the core message — the current draft is architected around the organization's self-description, not the donor's decision." **Scenario: Internal all-hands memo about a strategy pivot, audience is all employees** Trigger: CEO pastes a memo that mentions "shareholder value," "synergies across business units," and "our North Star metric." Audience: "All 400 employees — roles range from engineers to facilities staff. Most have not attended exec strategy meetings." Process: (1) Listener baseline: broadly varied — assume the lowest-context reader does not know `North Star metric`, does not know which business units exist, does not know what "shareholder value" means for their day-to-day. (2) Pass A flags `North Star`, `synergies`. (3) Pass B flags the entire memo as strategy-level with no concrete behavior change. (4) Pass C flags the assumption that readers know why the pivot is happening. (5) Pass D flags severe common-sense sedation across three paragraphs that any reader would already agree with. Output: Top 3 = (1) add a concrete "what changes for you on Monday" paragraph per role category, (2) replace `North Star` with the actual metric and its target number, (3) cut the two paragraphs of values-language that add no news. Handoff note: "Full rewrite — this is the Made to Stick-canonical 'maximize shareholder value' failure at scale." --- ## References - For the full jargon-substitution decision tree and worked word-swap tables, see [jargon-detection-playbook.md](references/jargon-detection-playbook.md) - For the abstraction-ladder worked examples (Boeing 727, JFK moon mission, Commander's Intent, maximize shareholder value), see [abstraction-ladder-examples.md](references/abstraction-ladder-examples.md) - For the full listener-baseline template and audience-profile interview script, see [listener-baseline-template.md](references/listener-baseline-template.md) --- ## License This skill is licensed under [CC-BY-SA-4.0](https://creativecommons.org/licenses/by-sa/4.0/). Source: [BookForge](https://github.com/bookforge-ai/bookforge-skills) — Made to Stick: Why Some Ideas Survive and Others Die by Chip Heath and Dan Heath. ## Related BookForge Skills This skill is standalone (Level 0 foundation). Browse more BookForge skills: [bookforge-skills](https://github.com/bookforge-ai/bookforge-skills)

path: references/abstraction-ladder-examples.md
content: # Abstraction Ladder Examples

Worked before/after pairs for Pass B (Abstraction / Strategy-Level Talk). Each example shows a sentence that sounds clear to an expert but fails the Boeing-727 test, then a concrete rewrite.

## The ladder, briefly

| Level | What lives here | Readability | Coordinates action? |
|-------|-----------------|-------------|--------------------|
| 5. Values | "excellence", "integrity" | feels profound | no |
| 4. Strategy | "maximize shareholder value" | feels important | no |
| 3. Principle | "put the customer first" | feels true | weakly |
| 2. Behavior | "answer every support ticket within 4 hours" | boring | yes |
| 1. Object | "Tracy the flight attendant served complimentary champagne" | vivid | yes |

Made to Stick's central claim: experts drift upward (because they have already internalized the concrete layer). Non-experts can only anchor to levels 1 and 2. Every Pass B flag is a sentence stuck at levels 3–5 that needs a drop to level 1 or 2.

## Example 1 — The canonical contrast (from the book's Introduction)

**Before (level 4):** "Our mission is to maximize shareholder value through synergistic growth and operational excellence."

**After (level 2):** "Ship three new products this year. Double revenue in our European accounts. Cut support-ticket resolution time from 48 hours to 8."

**Why:** The "before" is readable, but after reading it, no employee knows what to do on Monday morning. The "after" specifies observable outcomes. The Heaths contrast this directly with JFK's moon-mission sentence — "put a man on the moon and return him safely to Earth by the end of the decade" — which is a level-1 constraint (man, moon, safely, decade) that coordinated a decade of action without further translation.

## Example 2 — The Boeing 727 test (from Chapter 3 Concrete)

**Before (level 4):** "Design the best single-aisle passenger jet in the world."

**After (level 1):** "Design a plane that seats 131 passengers, flies nonstop from Miami to New York City, and lands on Runway 4-22 at LaGuardia — which is less than a mile long."

**Why:** The "best" phrasing cannot coordinate thousands of engineers across wings, engines, landing gear, and cabin. The "level-1" version constrains every subsystem simultaneously. Wings must produce enough lift at that weight. Landing gear must handle that runway. Engines must reach cruise for that distance. A concrete constraint is a coordination device; an adjective is not.

## Example 3 — Commander's Intent (from Chapter 1 Simple)

**Before (level 3 principle):** "Execute the operational plan with agility and adapt to changing conditions."

**After (level 1 behavior + end state):** "Clear Hill 4305 of enemy remnants so 3rd Brigade can pass through."

**Why:** When the plan doesn't survive contact, the principle ("adapt") gives no guidance. The Commander's Intent sentence — one end state, one named object — lets a subordinate abandon the written plan and still win. If you can't write the one-sentence intent, you don't have a core.

## Example 4 — Southwest Airlines (from Chapter 1 Simple)

**Before (level 4):** "We want to be the best airline experience for value-conscious travelers through operational efficiency."

**After (level 3, but with a delegation test):** "We are THE low-fare airline."

Delegation test: Tracy from marketing wants to add a light chicken Caesar salad on the Houston-Las Vegas flight. Herb Kelleher's answer: "Tracy, is adding the Caesar salad going to make us THE low-fare airline? Because if it isn't, we're not serving it."

**Why this example is subtle:** "THE low-fare airline" sits at level 3, not level 1 — it's still a principle. What makes it work is the exclusion clause ("and nothing else"). A new hire at Southwest can make a contested trade-off from the core alone. "Maximize shareholder value" cannot pass this test. When auditing for Pass B, ask: **can a new hire resolve a contested decision from this sentence alone?** If yes, the sentence passes. If not, it is stranded above the coordination line.

## Example 5 — Nonprofit fundraising (maps to Rokia effect, Chapter 5 Emotional)

**Before (level 5 values):** "We are committed to improving outcomes for vulnerable populations in under-resourced regions."

**After (level 1 object + person):** "We bought mosquito nets for Amina, age 4, and her three siblings in Lilongwe. Last year they had malaria twice. This year: zero."

**Why:** "Vulnerable populations" cannot activate the identifiable-victim effect the Heaths document in the Save the Children Rokia study (donors gave $2.50 to the named child and $1.14 to the statistic). Every abstract population noun in a fundraising letter is a Pass B flag.

## Example 6 — Technical documentation, audience = ops engineers

**Before (level 3):** "The service uses eventual consistency semantics for cross-region replication."

**After (level 2):** "When you write a value in the US region, it appears in the Europe region within 2-5 seconds. During that window, a read from Europe may return the old value. A read from the US returns the new value immediately."

**Why:** "Eventual consistency semantics" is accurate and to an expert it feels precise. To a reader debugging a bug at 2am, it gives no operational prediction. The level-2 rewrite tells the reader what will happen in observable time.

## How to generate the concrete translation

When a Pass B flag fires, apply this template to produce the rewrite:

1. **Who is the actor?** (Not "the team" or "we" — a named role or person.)
2. **What observable verb?** (Not `leverage`, `enable`, `drive` — a verb the actor physically performs.)
3. **What object?** (A physical or digital thing the reader could point at.)
4. **Under what constraint?** (A number, a deadline, a named reference case.)

If any of these four cannot be filled in for the abstract sentence, you have confirmation that the abstract sentence is not actionable — not because you are being pedantic, but because the author has not yet decided what the sentence means in practice. This is a signal to the user: the Curse is covering a decision that has not been made.

## Edge case: when abstraction is intentional

Not every abstract sentence is a Curse-of-Knowledge hit. Values statements, brand voice lines, and aspirational mission text are sometimes supposed to live at levels 4-5. Before flagging, ask: **does the draft have ANY level-1 or level-2 anchor?** If there is at least one vivid concrete scene somewhere in the draft, the abstract sentences around it can stand. If EVERY sentence is at level 3+, the whole draft is Curse-of-Knowledge territory and needs a concretization pass, not a polish pass.


path: references/jargon-detection-playbook.md
content: # Jargon Detection Playbook

Detailed guidance for Pass A (Unexplained Jargon, Acronyms, and Named Frameworks). Use alongside the main SKILL.md Process → Step 2.

## What counts as jargon for this skill

A term is "jargon" relative to a listener baseline if ANY of these are true:

1. **Lexical opacity.** The reader cannot reasonably parse the term from its parts (e.g., `blast radius`, `eventual consistency`, `BATNA`).
2. **Semantic drift.** The term is a common English word used in a specialist sense the reader does not hold (e.g., `commit` for code, `surface` as a verb meaning "reveal", `ship` for release).
3. **Acronym opacity.** The reader may know ONE expansion but not YOURS (e.g., `CDP` = Customer Data Platform vs Continuous Delivery Pipeline vs Clean Development Mechanism).
4. **Named-framework shorthand.** The draft references a framework by name (`SUCCESs framework`, `Sinatra Test`, `STAR format`, `RICE scoring`) without a one-line gloss.
5. **Proper-noun opacity.** References to internal projects, tools, teams, or people the reader does not work with (`the Apollo migration`, `the Foundry team`, `what Sarah said last quarter`).
6. **Borrowed metaphor.** A metaphor taken from a sub-field the reader does not live in (`the chess strategy`, `the orchestration layer`, `the spine of the product`).

## Fast-scan heuristics

When auditing a draft, apply these in order. Each is cheap and catches a distinct failure mode.

### Heuristic 1: Capital-letter density
Count capitalized nouns per 100 words. Above ~6 per 100 is a strong signal of named-framework / proper-noun overload.

### Heuristic 2: Acronym expand-on-first-use test
For every acronym, check: is it expanded on first use in the draft? If no, flag. If yes, is the expansion itself parseable to the listener baseline? (Expanding `API` to `Application Programming Interface` is not parseable to a non-engineer — you need one more hop.)

### Heuristic 3: The "pause test"
Read each sentence aloud. If you have to pause to decide how to pronounce a term, the reader's eye will stutter there too. Flag it.

### Heuristic 4: The "swap test"
For each suspect term, mentally substitute a generic placeholder (`[thing]`, `[process]`). If the sentence still makes sense to the listener, the term was load-bearing jargon and needs a gloss. If the sentence loses nothing, the term was decorative and should be cut.

## Rewrite options (in order of preference)

For each flagged term, offer one of these four fixes. Prefer the earliest option that preserves meaning.

1. **Remove.** The term is decorative. Cut it.
2. **Substitute.** Replace with a common-language equivalent. (`leverage` -> `use`, `bandwidth` -> `time`, `surface` -> `show`.)
3. **Gloss inline.** Keep the term but add a short parenthetical definition on first use. (`We use feature flags (on/off switches that let us turn a new feature on for some users without redeploying)`.)
4. **Gloss in a footnote or sidebar.** Use only for terms the reader will see repeatedly and should learn.

Only keep a term unchanged if the listener baseline explicitly shows the reader knows it.

## Worked examples

### Example 1 — SaaS product announcement, audience = business buyers

Draft: "We are GA on the new idempotent retry handler with exponential backoff."

Flags:
- `GA` — acronym, not expanded. Substitute: "generally available" or just "launched".
- `idempotent` — lexical opacity for business buyers. Substitute: "safe-to-retry".
- `retry handler` — borrowed technical metaphor. Substitute: "automatic retry system".
- `exponential backoff` — named technique. Remove (buyers don't need the algorithm) or gloss: "waits longer between each retry".

Rewrite: "We launched a safe-to-retry system that automatically tries failed requests again with growing wait times between attempts."

### Example 2 — Internal HR memo, audience = all employees

Draft: "Per our new L&D OKR, all ICs should complete the DE&I module by EOQ."

Flags: `L&D`, `OKR`, `ICs`, `DE&I`, `EOQ`. All acronyms, none expanded, reader is "all employees" including facilities and operations staff who do not live in HR shorthand.

Rewrite: "Everyone except managers (we call these 'individual contributors' or ICs) should finish the new diversity, equity, and inclusion training by the end of September."

### Example 3 — Academic grant abstract, audience = program officers from another field

Draft: "We propose a mixed-methods investigation of non-cognitive skill formation using IRT-scaled assessments."

Flags: `mixed-methods` (known in some social sciences, unknown in STEM program offices), `non-cognitive skill formation` (opaque compound), `IRT-scaled` (named technique).

Rewrite options: define each on first use, OR reframe the abstract in plain language and move the technical terms to the methods section.

## Anti-patterns the playbook catches that a generic grammar pass misses

- **"Consultant stack" sentences.** Chains of four+ abstract business nouns: `strategic alignment`, `value creation`, `core competency`, `operational excellence`. Each term is technically English, but together they are pure tapping.
- **Hollow verbs.** `Leverage`, `enable`, `drive`, `facilitate`, `orchestrate`. These verbs carry no sensory information. Flag them as Pass B (abstraction) but note them in Pass A if they let a named framework hide.
- **Framework-name inflation.** Using `SUCCESs framework` in a draft for an audience that has not read the book is a dead giveaway. Same for `BATNA`, `NPS`, `PMF`.


path: references/listener-baseline-template.md
content: # Listener Baseline Template

A filled-in template for Step 1 of the skill. The listener baseline is the single most important artifact in the audit — every subsequent flag is scored against it — so this reference gives you a reliable shape and an interview script to fill in missing information.

## Why this template exists

The Curse of Knowledge experiment works because the listener's state of mind is knowable: they literally cannot hear the tune the tapper is hearing. For prose, we have to manufacture that knowability. The listener baseline is the manufactured listener — a written profile that the rest of the audit treats as ground truth.

Without a written baseline, the agent defaults to "generic reasonable reader" and produces generic feedback. The book is explicit: the Curse cannot be cured, only routed around, and the routing requires a specific listener.

## Template

```markdown
## Listener Baseline: {audience short name}

### Role and context
- **Role:** {e.g., "VP of Engineering at a 200-person B2B SaaS company"}
- **Reading context:** {async email / deck in meeting / landing page / onboarding doc}
- **Can they ask follow-up questions?** {yes / no / partial}
- **Time budget for this draft:** {how long they will realistically read before bouncing}

### Vocabulary they KNOW
- {term 1}: {why — e.g., "used daily in their role"}
- {term 2}: {why}
- {term 3}: {why}
...

### Vocabulary they do NOT know
- {term 1}: {why — e.g., "engineering-internal"}
- {term 2}: {why}
- {term 3}: {why}
...

### Processes they understand
- {process 1}: {depth — surface / working / deep}
- {process 2}: {depth}
...

### Processes they do NOT understand
- {process 1}: {why}
- {process 2}: {why}
...

### Prior context they hold
- {thing 1}: {source — e.g., "from previous email in thread"}
- {thing 2}: {source}
...

### Prior context they LACK
- {thing 1}: {what they do not know}
- {thing 2}: {what they do not know}
...

### Emotional/identity stakes
- **What they care about in this decision:** {the reader's actual motivation}
- **What they do NOT care about:** {items authors often assume the reader cares about but does not}
- **Identity frame:** {who they see themselves as when reading — "pragmatic operator", "strategic thinker", "worried parent", etc.}

### What would make this reader stop reading
- {reason 1 — e.g., "any sentence longer than 30 words in paragraph 1"}
- {reason 2}
...
```

## Interview script (when the user provides a thin audience description)

If the user's audience description is too vague to fill out the template, ask THESE questions — one at a time. Do not batch.

1. **"What is this reader's role and seniority?"** (You need the role to infer vocabulary and processes.)

2. **"Pick one: is this reader (a) a subject-matter expert in the same field as the author, (b) an adjacent expert from a related field, (c) an informed non-expert, or (d) a general reader?"** (This single multiple-choice question does most of the work — the four categories have very different jargon tolerances.)

3. **"Name three things the author knows that you are SURE this reader does not know."** (This is the most valuable question. Authors often know the answer immediately and it anchors the whole baseline.)

4. **"Name three things the author thinks this reader cares about that they actually might not."** (Catches the identity / motivation gap that Pass C will use.)

5. **"What decision do you want this reader to make after reading?"** (If the user cannot answer this in one sentence, flag it — the draft has no core, which is a bigger problem than the Curse.)

6. **"Will this reader see the draft in isolation or inside a thread / deck / conversation?"** (Changes what "prior context they hold" can include.)

Stop after question 6 — even if incomplete, you have enough to begin. Note remaining gaps at the top of the report as "assumptions the audit depends on."

## Worked baseline — Example 1

**Draft:** SaaS product announcement for a developer-tools company.
**User's audience description:** "VP of Engineering buyers at mid-market SaaS companies."

### Filled baseline

- **Role:** VP Eng, mid-market B2B SaaS, budget authority, manages 20-80 engineers
- **Reading context:** async email from their AE, probably on phone
- **Can they ask follow-up questions?** Yes but they will not — they will forward or delete
- **Time budget:** 60 seconds for paragraph 1, another 60 if hooked

**Knows:**
- `feature flag` (they have used LaunchDarkly or similar)
- `staging` and `production` environments
- `incident`, `outage`, `postmortem` (from their ops-review meetings)
- `SLA`, `uptime` (from their vendor contracts)

**Does NOT know:**
- `canary` (knows the concept of gradual rollout but not this word)
- `blast radius` (metaphor, not used outside of SRE subculture)
- `idempotent`, `eventual consistency` (they have not coded in 5 years)
- internal product names of the tool vendor

**Processes they understand:** vendor evaluation, budget cycles, incident-response escalation (at a management level, not at the keyboard level).

**Processes they do NOT understand:** the actual rollout mechanism at the code level. They know that engineers "turn features on for some users first" but not how.

**Prior context they hold:** they have heard of the vendor (probably), they know feature-flag tools exist as a category.

**Prior context they LACK:** what `v1` of this product did, what changed in `v2`, who else is using it.

**Cares about:** reducing incidents, team productivity, budget predictability, CVs for their engineers.
**Does NOT care about:** the algorithmic details of the rollout engine, the vendor's engineering-team size.

**Identity frame:** "pragmatic operator" — does not want to look foolish in front of their engineers by buying a toy, but also does not want to debug vendor pitches.

**Would stop reading if:** first paragraph is full of SRE jargon, or if the first sentence is organizational news ("We're excited to announce...").

## Worked baseline — Example 2

**Draft:** Grant application abstract from a social-science research group.
**User's audience description:** "Program officer at an interdisciplinary foundation — probably trained in a different field."

### Filled baseline

- **Role:** Program officer, PhD in some field (probably not this one), reviews ~200 abstracts per cycle
- **Reading context:** batch review, 3-5 minutes per abstract max
- **Can they ask follow-up questions?** No — the abstract is the decision
- **Time budget:** 90 seconds per abstract at the filter stage

**Knows:**
- general academic vocabulary (`hypothesis`, `sample`, `controls`, `significance`)
- how grants work, budget ranges, review criteria
- the foundation's own program areas

**Does NOT know:**
- field-specific named methods (`IRT scaling`, `difference-in-differences`, `fixed effects`)
- field-specific jargon compounds (`non-cognitive skill formation`)
- which researchers in the field are famous

**Cares about:** does this fit our funding priorities, is the team credible, is the method sound enough that our board won't embarrass us.
**Does NOT care about:** methodological novelty for its own sake.

**Identity frame:** gatekeeper who wants to say yes to good work but has to triage hard.

**Would stop reading if:** the first two sentences are pure methods jargon, or if the problem statement does not connect to a human-visible outcome.

## How to use the baseline

Once filled out, the baseline is the left-hand column of every subsequent flag. For each sentence in the draft, the agent asks:

- Pass A: Is every term in this sentence in the "knows vocabulary" list?
- Pass B: Does this sentence reach down to a process or object the reader understands?
- Pass C: Does this sentence depend on prior context the reader holds?
- Pass D: Does this sentence match what the reader actually cares about and identifies with?

If any answer is no, the sentence is a flag, and the rewrite guidance uses the baseline's vocabulary and context to produce a specific fix.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)