@deftai/directive-content 0.55.0

package/references/cost-models.md

@@ -0,0 +1,163 @@
+# Cost Model Methodology (cost-models.md)
+
+This reference describes how Deft estimates pre-build cost & budget for a
+project produced through the deft-directive workflow. It is the canonical
+methodology consumed by `skills/deft-directive-cost/SKILL.md` and the
+`templates/COST-ESTIMATE.md` artifact body.
+
+Audience: agents producing cost estimates AND non-technical end users
+reading the resulting `COST-ESTIMATE.md`. Plain-English voice throughout
+(no spreadsheets, no scientific notation, no industry jargon).
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+## Scope
+
+This document covers cost estimation for the **pre-build phase** of a
+deft project -- after the spec is approved but before any build work
+starts. Its purpose is to give the user enough cost information to
+decide whether to proceed (build), pull back scope (rescope), or stop
+(no-build).
+
+Out of scope:
+
+- Hard cost numbers tied to specific 2026 vendor pricing
+- Real-time pricing API integration
+- Currency / region localisation -- USD-only first pass
+- Cost forecasting beyond a 12-month horizon
+- Cost optimisation / FinOps for already-running projects
+
+## Core Principles
+
+- ! Use **loose ranges**, not single point estimates. A \$5-\$20 / month
+  band is more honest than \$12.50 / month for a category whose real
+  variance is huge (e.g. egress, LLM tokens, image generation).
+- ! Express ranges as plain-English bands: **low**, **typical**, **high**.
+  Avoid "p10 / p50 / p90" or other statistical jargon.
+- ! Always state the **assumption** behind each range (e.g. "100 daily
+  active users, 5 saved photos each"). The same project shape can be
+  \$10/month or \$10,000/month depending on traffic.
+- ! USD-only first pass. The artifact MUST say "USD" explicitly so
+  international users know to convert.
+- ⊗ Do NOT pretend a range is exact. If the agent does not know, write
+  "unknown -- ask vendor" rather than guessing a number.
+
+## Where Costs Come From
+
+For a typical deft project, costs roll up into a small number of
+categories. The agent walks the spec and identifies which categories
+apply, then fills in plain-English bands for each.
+
+### 1. Pre-flight account / sign-up costs
+
+Things the user must sign up for before the project can run at all.
+Often \$0 to start (free tier), but the user needs to know the list of
+accounts up front so they are not surprised mid-build.
+
+Examples (loose, illustrative):
+
+- Cloud hosting account (free tier ~\$0; paid tier varies)
+- Domain name (typical: \$10-\$20 / year)
+- Email-sending provider (free tier; paid tier ~\$10-\$50 / month)
+- Payment processor (no monthly fee; ~3% per transaction)
+- LLM / AI API account (pay-as-you-go; can be \$0 if unused)
+
+### 2. Hosting / infrastructure
+
+The recurring monthly cost of running the application. Bands:
+
+- **Static site / serverless** (low-traffic): \$0-\$10 / month typical
+- **Single small VM / app service**: \$5-\$30 / month typical
+- **Managed database** (small): \$10-\$50 / month typical
+- **CDN / edge** (low-traffic): \$0-\$10 / month typical
+- **Egress at scale**: this is where the high band can blow up; flag if
+  the project shape involves serving large media to many users
+
+### 3. API / third-party fees
+
+Per-call or per-event fees for services the project depends on.
+Examples (illustrative bands, not authoritative):
+
+- LLM API calls (text): a few cents to a few dollars per 1M tokens,
+  depending on model tier
+- Image generation: a few cents per image typical
+- Search / embeddings: a few cents per 1M tokens typical
+- Telephony (SMS / voice): a few cents per message / minute typical
+- Maps / geocoding: free tier exists; can scale to \$ hundreds / month
+  for high-volume apps
+
+### 4. Build & maintenance time
+
+Not strictly a recurring cost, but worth surfacing so the user
+understands the time cost too:
+
+- Initial build effort (rough hours)
+- Ongoing maintenance (rough hours / month)
+
+## Building the Monthly Band
+
+After categories are filled in, the artifact rolls them up into a single
+**monthly band**:
+
+- **Low**: free tier / minimal usage (e.g. demo, internal use only)
+- **Typical**: realistic everyday usage as described in the spec
+- **High**: stretch scenario (popular launch, viral spike, growth)
+
+Rules:
+
+- ! The roll-up MUST stay loose. Adding a range to a range gives a
+  range; do NOT collapse to a single number.
+- ! State the **scale assumption** (e.g. "100 daily users") in the same
+  block as the typical band so the reader can scale up or down.
+- ~ When the high band is more than ~10x the typical band, surface a
+  separate **scale considerations** note explaining what would push the
+  project from typical -> high (e.g. "media-heavy traffic blows up
+  egress").
+
+## Decision Point
+
+Every cost estimate ends with an explicit, four-way decision. All four
+options are first-class outcomes; the build skill's Cost Phase Gate
+treats each one as a recorded decision (a `skip` with no reason is the
+same as no decision and the gate refuses kickoff).
+
+1. **Build** -- user accepts the cost and proceeds to the build phase.
+2. **Rescope** -- user wants to keep building but reduce cost (drop a
+   feature, swap a vendor, lower the scale assumption). Loops back to
+   spec edits, then re-runs the cost phase.
+3. **No-build** -- user stops the project at this stage. Recorded
+   explicitly so the deft project history shows the decision.
+4. **Skip** -- explicit escape hatch (e.g. hobby project where cost is
+   irrelevant, or a follow-up project where cost was already estimated
+   for the parent project). The skip MUST record a short skip reason so
+   the artifact's existence is auditable.
+
+## Plain-English Voice
+
+The artifact and skill prose are read by non-technical users. Hard
+rules:
+
+- ! Use **dollars, not "USD"** in body text where it reads naturally
+  (the artifact still states "all figures in USD" up top).
+- ! Use **whole numbers** in bands where the precision does not matter
+  (\$5-\$20, not \$5.37-\$19.84).
+- ! When using a technical term that the user might not know, define it
+  in a short parenthetical (e.g. "egress (data leaving the cloud)").
+- ⊗ Do not use jargon like "TCO", "burn rate", "p50", "OPEX vs CAPEX",
+  "amortised", "blended rate", "unit economics", or "FTE".
+
+## Anti-Patterns
+
+- ⊗ Quote single-point estimates ("this will cost \$47.12 / month")
+- ⊗ Quote ranges without an assumption (e.g. \$5-\$5,000 with no
+  context is useless)
+- ⊗ Cite live vendor pricing as if it were a guarantee (vendor pricing
+  changes; the artifact must read as a snapshot)
+- ⊗ Skip the decision point -- the build skill MUST refuse kickoff
+  until the user has explicitly chosen build / rescope / no-build /
+  skip(+reason)
+- ⊗ Use jargon that a non-technical user will not understand
+- ⊗ Promise that the project will "definitely" stay within a band --
+  always say "expected", "typical", or "in our estimate"
+- ⊗ Generate the artifact and proceed silently to build without
+  surfacing the decision point to the user

package/references/ip-risk.md

@@ -0,0 +1,246 @@
+# IP / Legal Risk -- Heuristic, Question Script, and Minimum-Protection Checklist
+
+Reference document for skill authors and interview-running agents who need to
+flag third-party intellectual-property (IP) risk during the research /
+interview phase. Issue: [#738](https://github.com/deftai/directive/issues/738).
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ Note**: This document is *advisory*. Deft is not a law firm. It does
+not provide legal advice and ⊗ MUST NOT be used as a substitute for lawyer
+consultation when the project is commercial and IP-adjacent.
+
+**⚠️ See also**: [skills/deft-directive-interview/SKILL.md](../skills/deft-directive-interview/SKILL.md) | [strategies/research.md](../strategies/research.md) | [scripts/ip_risk.py](../../scripts/ip_risk.py)
+
+---
+
+## Why This Document Exists
+
+The #151 playtester walked through the full Deft interview + PRD +
+SPECIFICATION approval flow building a Magic: The Gathering deck-builder app
+**without Deft ever flagging Wizards of the Coast copyright**, recommending a
+disclaimer, or suggesting a lawyer. The framework currently has no surface
+that prompts users about IP risk, monetization intent, or legal protection
+when building on established third-party IP (games, music, film, characters,
+sports leagues, branded products).
+
+This reference codifies a permissive heuristic, an explicit
+monetization-intent question, a plain-English risk summary, and a minimum-
+protection checklist that the interview / research skills MUST surface
+whenever the heuristic detects an IP-adjacent project.
+
+---
+
+## Heuristic (Permissive Detection)
+
+! Use a permissive heuristic that errs on the side of false positives. The
+cost of one extra "is this Magic: The Gathering related?" question is
+trivial; the cost of letting a commercial IP-adjacent project ship without
+the question is potentially substantial.
+
+The canonical implementation lives at
+[`scripts/ip_risk.py`](../../scripts/ip_risk.py) and exposes
+`detect_ip_terms(text)`, `is_ip_adjacent(text)`, `ip_risk_scope_items(monetization_intent)`,
+and `plain_risk_summary(hits, monetization_intent)` for callers.
+
+### Categories Scanned
+
+The detector scans the user-supplied project description (and any
+research-phase notes) for terms in these categories:
+
+1. **Recognisable IP names** -- branded games and franchises (Magic: The
+   Gathering, Pokemon, Yu-Gi-Oh, Dungeons & Dragons, Warhammer, Final
+   Fantasy, etc.).
+2. **Fictional-universe terms** -- proper nouns from established universes
+   (Hogwarts, Tatooine, Jedi, Klingon, Quidditch, Mandalorian, etc.).
+3. **Branded characters** -- named characters owned by a single rights
+   holder (Mickey Mouse, Spider-Man, Batman, Pikachu, Master Chief, etc.).
+4. **Sports leagues** -- NFL, NBA, MLB, NHL, FIFA, UEFA, Olympics, etc.
+5. **Trademarked products** -- iPhone, Xbox, PlayStation, Lego, Coca-Cola,
+   etc.
+6. **Music / film** -- artist names and platform names that are commonly
+   misappropriated (Taylor Swift, Beyoncé, Spotify, Netflix, HBO, etc.).
+
+### Matching Rules
+
+- ! Case-insensitive.
+- ! Word-boundary scoped (substring matches inside a longer word do NOT
+  trigger -- "magicwand" is not "Magic", "starcraft" is not "Star Wars").
+- ! Deduplicated by `(term, category)` pair so repeated mentions count
+  once.
+- ⊗ Treat the absence of detected terms as proof that the project is
+  IP-free -- the heuristic only knows about the curated lists. When the
+  user describes a project in vague terms, the interview SHOULD ask
+  directly "is this based on a game / film / sports league / brand?".
+
+### Updating the Term Lists
+
+! When you add a recurring miss (a real IP-adjacent project that slipped
+through), append the term to the matching category in
+`scripts/ip_risk.py` AND mention it here in the relevant category. The
+two surfaces MUST stay in sync. The unit tests in
+`tests/scripts/test_ip_risk.py` verify the helpers; add a positive
+detection test for any new term you introduce.
+
+---
+
+## Question Script (Monetization Intent)
+
+When `detect_ip_terms` returns at least one hit, the interview MUST ask the
+user the monetization-intent question before generating the SPECIFICATION.
+
+### Canonical Question
+
+```
+Your project description references third-party intellectual property (IP)
+that someone else owns. How do you plan to use this project?
+
+  0. Discuss with agent (pause interview to talk it through)
+  ─────────────────────────────────────────────────────────
+  1. Personal use only -- private learning, personal play, no public
+     distribution, no monetization.
+  2. Commercial use -- I plan to sell access, charge subscriptions,
+     run ads, or distribute publicly to paying users. [default: 2]
+  3. Other / I don't know
+
+Enter confirm / b back / 0 discuss
+```
+
+### Defaulting to Commercial
+
+! The `[default: 2]` in the canonical question is intentional. When the
+user is unsure, the **commercial** path produces the stricter checklist
+and the lawyer recommendation. Defaulting away from the stricter path
+when intent is unclear is the wrong-side-of-safe choice.
+
+### Branching Behavior
+
+- ! On `commercial`: emit the plain-English risk summary AND the
+  non-optional `MUST consult a lawyer before public release`
+  recommendation. Both go into the interview output AND into an
+  `IPRisk` narrative on the specification vBRIEF.
+- ! On `personal`: emit the plain-English risk summary noting that
+  personal use is lower risk but not zero risk; warn explicitly that if
+  the project ever goes public, becomes monetized, or is shared widely,
+  the risk profile changes and a lawyer review becomes worthwhile.
+- ! On `Other / I don't know`: do NOT proceed to spec generation. Re-ask
+  the question or open a freeform discussion until an explicit answer is
+  captured.
+
+---
+
+## Plain-English Risk Summary
+
+! After the monetization-intent question is answered, emit a plain-English
+risk summary in the interview output. The summary:
+
+- ! Opens with `not legal advice` -- this is a hard line.
+- ! Names the detected categories and the actual matched terms.
+- ! For commercial intent: states explicitly that lawyer consultation is
+  not optional output from this interview.
+- ! For personal intent: states that the risk profile changes if the
+  project goes public / monetized.
+- ⊗ Use legalese ("hereby", "tortious", "in perpetuity", "without
+  prejudice"). The audience is the project owner, not a court.
+
+The canonical builder is `plain_risk_summary(hits, monetization_intent)`
+in `scripts/ip_risk.py`.
+
+---
+
+## Minimum-Protection Checklist (SPECIFICATION Scope Items)
+
+! When IP is detected, the SPECIFICATION generation step MUST inject the
+following three protection scope items into the
+`specification.vbrief.json` `plan.items` array (and therefore into the
+rendered SPECIFICATION.md).
+
+The canonical generator is `ip_risk_scope_items(monetization_intent)`
+in `scripts/ip_risk.py` -- it returns the three items shaped for vBRIEF
+v0.6 PlanItem (`title`, `status`, `narrative`). All three items are
+emitted regardless of monetization intent because even personal
+IP-adjacent projects can leak into commercial use over time. The
+`Acceptance` narrative is tightened to the commercial-level checklist
+(lawyer-confirmed terms, written license, counsel-reviewed hosting) for
+**any intent other than `personal`** -- per the wrong-side-of-safe
+policy, `unknown` (interview hasn't captured an explicit answer yet)
+inherits the stricter checklist. Only the explicit `personal` answer
+relaxes the acceptance language.
+
+### Item 1: Disclaimer Stub (`IP-1`)
+
+> Add a "not affiliated with / not endorsed by" notice on the app's
+> first user-visible surface (splash screen, landing page, or CLI banner).
+
+- Acceptance (personal): reviewed by the project owner before any public
+  release.
+- Acceptance (commercial): lawyer-confirmed wording before public release.
+
+### Item 2: API-Only Third-Party Asset Access Policy (`IP-2`)
+
+> Never bundle third-party IP assets (images, audio, video, text, card
+> data, character likenesses) in the repository or build artifacts.
+> Access only via official APIs that grant a license.
+
+- Acceptance (personal): all third-party assets reach the app via
+  official APIs only; no assets bundled in the repository or build
+  artifacts.
+- Acceptance (commercial): same, plus a license that explicitly permits
+  the planned use, plus lawyer-confirmed before public release.
+
+### Item 3: Hosting Policy Gated on Monetization Intent (`IP-3`)
+
+> Document the hosting plan and gate it on the captured monetization
+> intent. Self-hosted private use is the default; commercial hosting
+> requires lawyer review.
+
+- Acceptance (personal): self-hosted private use only; do not deploy
+  publicly until a monetization decision is made and re-reviewed
+  against this rule.
+- Acceptance (commercial): hosting plan reviewed by counsel; written
+  license terms cover the deployment region and audience; revenue model
+  documented.
+
+### Why These Three?
+
+- The disclaimer is the cheapest defense -- a single line of text on the
+  splash / landing surface meaningfully reduces consumer confusion about
+  endorsement.
+- The API-only-asset policy is the structural defense -- it prevents the
+  most common copyright incidents (bundling sprite sheets, card images,
+  audio clips) from being possible at all.
+- The hosting policy is the deployment-time gate -- self-hosted private
+  use is a different legal posture than a publicly-marketed commercial
+  service, and the spec should make the gate explicit so it is not
+  forgotten when the project drifts toward "let's just put it online".
+
+---
+
+## Out of Scope
+
+⊗ Do not attempt to:
+
+- Provide legal advice.
+- Catalogue specific IP holders or trademark owners.
+- Run automated trademark / copyright lookups against external services.
+- Make a "is this fair use?" determination.
+
+The heuristic exists to **surface the question**, not to answer it.
+
+---
+
+## Workflow Summary (for Interview / Research Skills)
+
+```
+1. Capture project description (and research notes if research strategy ran).
+2. Run scripts/ip_risk.py:detect_ip_terms(text).
+3. If empty -> proceed normally.
+4. If non-empty:
+   a. Ask the monetization-intent question (Personal / Commercial / Other).
+   b. Loop on the freeform follow-up if "Other" is chosen until intent is captured.
+   c. Emit plain_risk_summary(hits, intent) into the interview output.
+   d. Inject ip_risk_scope_items(intent) into the spec vBRIEF.
+   e. On commercial intent, surface the non-optional lawyer-consultation
+      recommendation in the interview output AND in the IPRisk narrative.
+5. Continue to the rest of the interview flow.
+```

package/references/plain-english-ux.md

@@ -0,0 +1,275 @@
+# Plain-English UX Guidelines for Skill Authors
+
+Reference document for skill authors writing user-facing prompts in interview,
+PRD review, and SPECIFICATION review skills. Issue:
+[#740](https://github.com/deftai/directive/issues/740).
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also**: [skills/deft-directive-interview/SKILL.md](../skills/deft-directive-interview/SKILL.md) | [strategies/interview.md](../strategies/interview.md)
+
+---
+
+## Why This Document Exists
+
+The #151 playtester only completed the planning flow because they had a
+second AI translating jargon, decoding ambiguous approval actions, and
+explaining red/green diff views. Defects clustered into three buckets:
+
+1. **Jargon without explanations** -- frontend, backend, DB, auth,
+   deployment, PRD, Next.js -- shipped raw at users with no plain-English
+   context note.
+2. **Unclear approval actions** -- "Accept / Refine / Edit" buttons did
+   not say what would actually happen on each choice.
+3. **Alarming red/green diff view at PRD/SPEC review** -- the diff looked
+   like an error report; the user had to ask their other AI whether
+   anything was wrong.
+
+This reference codifies the rules that fix all three buckets and the
+patterns skill authors should follow going forward.
+
+---
+
+## Rule 1 -- Plain-English Context Note on Every Technical Question
+
+! Every technical question MUST carry a one-line plain-English context
+note that explains what the answer affects in non-technical terms.
+
+The context note appears as preamble ABOVE the structured-tool call (per
+the interview SKILL Rule 2 Preamble Placement subsection). It does NOT
+replace the structured question -- both the preamble AND the structured
+options are required.
+
+### Anti-pattern
+
+```
+Which deployment platform?
+
+  1. Linux server
+  2. Web hosting (cloud)
+  3. Embedded
+```
+
+### Correct
+
+```
+Where will this app actually run for users? This decides whether you
+need a server you maintain, a cloud account someone else manages, or
+a tiny computer that ships with the product.
+
+  0. Discuss with agent
+  ────────────────────
+  1. Server you maintain (Linux machine, you handle updates)
+  2. Cloud you rent (a hosting service runs it; you pay monthly)
+     [default: 2]
+  3. Tiny dedicated device (ships inside hardware -- e.g. a thermostat)
+  4. Other / I don't know
+  5. Discuss
+  6. Back
+
+Enter confirm / b back / 0 discuss
+```
+
+The plain-English preamble explains the *consequence* of the choice.
+The numbered options use plain-English labels with the technical term
+in parenthesis (or omit it entirely when the technical term is not load-
+bearing).
+
+---
+
+## Rule 2 -- Acronyms Defined Inline on First Use
+
+! Every acronym MUST be defined inline the first time it appears in a
+user-facing message within a skill session. The definition format is
+`ACRONYM (full expansion)`. Subsequent uses MAY use the acronym alone.
+
+Common acronyms in Deft's interview surface and their canonical
+expansions:
+
+- **PRD** (Product Requirements Document) -- "what to build" doc reviewed
+  before implementation.
+- **NFR** (Non-Functional Requirement) -- a performance / security /
+  scalability rule rather than a feature.
+- **FR** (Functional Requirement) -- a numbered behavior the spec MUST
+  implement.
+- **SPEC** (Specification) -- the implementation plan derived from the
+  PRD.
+- **API** (Application Programming Interface) -- the way two pieces of
+  software talk to each other.
+- **DB** (Database) -- where the app's data is stored.
+- **CI** (Continuous Integration) -- the automated checks that run on
+  every change.
+- **MVP** (Minimum Viable Product) -- the smallest version of the
+  product worth shipping.
+
+### Anti-pattern
+
+```
+After PRD review, we'll generate the SPEC and run CI before merging.
+```
+
+### Correct
+
+```
+After PRD (Product Requirements Document) review, we'll generate the
+SPEC (Specification) and run CI (Continuous Integration -- the automated
+checks) before merging.
+```
+
+After this first sentence, the agent MAY use the acronyms unadorned for
+the rest of the session.
+
+---
+
+## Rule 3 -- Framework Justifications Explained or Removed
+
+! When a skill recommends a framework, library, language, or tool, the
+recommendation MUST either:
+
+- **Explain why** in plain-English terms the user actually cares about
+  (cost, speed, hiring, hosting compatibility, etc.); OR
+- **Remove the justification** entirely and present it as a default the
+  user can override.
+
+⊗ Drop a framework name with a one-word "modern" or "industry-standard"
+justification. That phrasing is jargon-flavoured advertising and the
+user has no way to evaluate it.
+
+### Anti-pattern
+
+```
+Recommended: Next.js (industry-standard, modern).
+```
+
+### Correct (explained)
+
+```
+Recommended: Next.js -- a popular toolkit for building websites that
+need both pages and live data. Picking it now means more example code
+on the internet and easier hiring later.
+```
+
+### Correct (removed)
+
+```
+Default: Next.js. Pick "Other" below if you want a different web
+framework and we'll capture your reason in the spec.
+```
+
+---
+
+## Rule 4 -- Numbered Approval Menu After PRD and SPEC Review
+
+! After every PRD review AND every SPECIFICATION review, the agent MUST
+present an explicit numbered approval menu. The menu replaces ambiguous
+buttons like "Accept / Refine / Edit" with action-shaped labels that
+state what will happen.
+
+### Canonical Menu Shape (PRD review)
+
+```
+What would you like to do with the PRD?
+
+  1. Approve and continue (lock the PRD, generate the SPECIFICATION)
+  2. Suggest changes (you describe what to change; the agent rewrites)
+  3. Edit yourself (you edit the PRD directly; the agent waits)
+  4. Discuss
+  5. Back
+
+Enter confirm / b back / 0 discuss
+```
+
+### Canonical Menu Shape (SPECIFICATION review)
+
+```
+What would you like to do with the SPECIFICATION?
+
+  1. Approve and continue (lock the SPEC, proceed to implementation)
+  2. Suggest changes (you describe what to change; the agent rewrites)
+  3. Edit yourself (you edit the SPEC directly; the agent waits)
+  4. Discuss
+  5. Back
+
+Enter confirm / b back / 0 discuss
+```
+
+### Discuss + Back Are the Final Two Options (#767 framework rule)
+
+! Every numbered approval menu MUST follow the #767 deterministic-
+question framework rule: the final two numbered options MUST be
+`Discuss` and `Back`, in that order. This is consistent with the
+interview SKILL's Rule 9 (back-navigation) and Rule 10 (slot-0
+discuss-with-agent escape) and provides a uniform exit path on every
+menu the user sees.
+
+! When `contracts/deterministic-questions.md` lands (Agent 1, #767),
+this reference doc and the canonical menu shapes MUST be re-read against
+that contract; any inconsistency is fixed by editing this doc, not the
+contract.
+
+⊗ Add a numbered approval menu where Discuss and Back are not the
+final two options. ⊗ Use plain "Accept / Refine / Edit" buttons without
+explanatory parentheticals.
+
+---
+
+## Rule 5 -- Diff-View Preface (Non-Alarming)
+
+! When a PRD or SPECIFICATION review surfaces a red/green diff (e.g. via
+`git diff` or any structured-diff renderer), the agent MUST emit a one-
+line non-alarming preface ABOVE the diff. The preface MUST set
+expectations that red lines are removals and green lines are additions
+in the new version, NOT errors.
+
+? Alternatively, hide the diff entirely on the FIRST review pass and
+present a plain-English summary of changes; only show the diff on the
+second pass or when the user explicitly asks for it.
+
+### Canonical Preface
+
+```
+Here's what changed since the previous draft. Red lines were removed,
+green lines were added. Nothing here is broken -- this is a normal
+review.
+```
+
+### Anti-pattern
+
+```
+[diff output starts immediately with no preface]
+```
+
+The user sees red and green and reads it as an error report; this is
+exactly the #151 #11 playtest defect.
+
+---
+
+## Rule 6 -- Audience Test
+
+! Before shipping a question or output line in a user-facing skill, run
+the **audience test**: read the line aloud and ask "would a non-technical
+person understand the *consequence* of this choice?". If the answer is
+no, rewrite or add a context note.
+
+The audience test is not a heuristic the agent runs at runtime -- it is
+a content-review rule for skill authors at edit time.
+
+---
+
+## Anti-Patterns
+
+- ⊗ Drop a technical question on the user without a plain-English
+  context note above it.
+- ⊗ Use an acronym for the first time without inlining `(full
+  expansion)`.
+- ⊗ Recommend a framework with one-word jargon-flavoured justification
+  ("industry-standard", "modern", "scalable").
+- ⊗ Present an approval menu without explicit numbered actions whose
+  labels state what will happen.
+- ⊗ Place Discuss / Back anywhere except as the final two numbered
+  options of an approval menu (per #767).
+- ⊗ Show a red/green diff at first review without a non-alarming
+  preface.
+- ⊗ Treat "the user can ask their other AI to translate" as an
+  acceptable mitigation for jargon. The user's other AI is not a Deft
+  surface and is not a reliable communication channel.