Jeff Bullas

Nice shortcut — you nailed the quick win: paste one paragraph, get usable nodes in minutes. That extraction → structure → layout flow is the secret sauce. I’ll add a compact, do-first refinement that makes the AI output map-ready and trustworthy.

What you’ll need

• Source text (one paragraph or a 200–400 word section)
• An AI assistant (ChatGPT/GPT-4 or similar)
• A simple canvas (Miro, MindMeister, Obsidian+Excalidraw, or PowerPoint)
• 5–90 minutes

Step-by-step (fast, repeatable)

1. Define the single question (5 min): What should this map answer? Keep it one sentence — it focuses extraction.
2. AI extraction (5–15 min): paste one paragraph and use the prompt below. Ask for 6–10 concepts, one-line definitions, relationship types, and Core/Supporting/Example tags.
3. Clean & cap (5–10 min): merge duplicates, enforce a 7–10 node cap. Rename vague labels to plain-English phrases.
4. Draft relationships (10 min): pick link types — causes, enables, is part of, contrasts with — and draw simple arrows or dashed lines.
5. Visual layout (15–30 min): put cores centrally, color-code tiers, keep notes short. If the map is crowded, split into two linked maps.
6. Validate (5–10 min): show to one person; revise one pass only.

Copy-paste AI prompt (use this exactly)

Read the following text I will paste. Return: 1) a numbered list of up to 10 core concepts, each with a one-sentence plain-English definition; 2) for each concept, list up to three related concepts and the type of relationship (causes, enables, is part of, contrasts with); 3) tag each concept as Core / Supporting / Example; 4) suggest which 3 nodes should be central on a visual map. Output as plain text, ready to paste into a concept-mapping tool.

Quick example (remote-work paragraph)

Sample paragraph: “Remote work productivity depends on clear goals, good communication tools, manager trust, and boundary-setting to avoid burnout.”

1. Concepts returned: 1) Clear goals — one-line definition; 2) Communication tools; 3) Manager trust; 4) Boundary-setting; 5) Burnout. Each gets relations (e.g., Clear goals causes focused work; Boundary-setting reduces Burnout) and tags (Core/Supporting).

Common mistakes & fixes

• Too many nodes — fix: merge similar concepts & enforce a 10-node cap.
• Vague labels — fix: force one-line definitions and plain-English wording.
• No clear links — fix: pick a small set of relationship types and use arrows consistently.

1-week action plan (do-first)

1. Day 1: Pick a dense article and one question.
2. Day 2: Run the extraction prompt on one section.
3. Day 3: Clean, cap, and tag nodes.
4. Day 4: Draft relationships and build the map.
5. Day 5: Share with one person, revise once.
6. Day 6: Turn the map into a one-paragraph executive summary (use AI).
7. Day 7: Repeat with a new section or topic.

Small, repeated wins beat one perfect map. Start with a paragraph — you’ll learn faster than you think.

Totally agree on “LLMs as a scalpel.” Your privacy-first, rules-first stance is the right backbone. Let me add a playbook that gets you fast wins without breaking speed, trust, or sanity.

Do / Do not (quick guardrails)

• Do: Set a 200ms latency budget for any personalized block and fall back to a safe default if exceeded.
• Do: Use a simple Signal Confidence Score (high: referrer/landing page; medium: on-site clicks; low: time-on-page) and personalize only on medium+high.
• Do: Personalize only 1–2 blocks at first (hero + CTA). Keep the rest universal.
• Do: Add a “Preview as…” switch for QA so anyone can see each variant before it goes live.
• Do: Log every decision (intent, signals, variant ID) for audit and rollback.
• Do: Respect consent; if opt-out, serve the baseline and suppress AI.
• Do not: Personalize legal/compliance content or pricing numbers dynamically.
• Do not: Make identity claims (“Since you’re a CFO…”) from inferred signals.
• Do not: Wait on AI to render the page. Render default immediately; swap the block asynchronously.
• Do not: Ship untested prompts; always run a human QA pass.

What you’ll need (tightened)

• One high-traffic page (pricing, product, or services overview).
• Signal capture: referrer, landing page path, UTM, key clicks, time-on-page (via tag manager).
• A simple rules engine or feature flag to swap the hero block + CTA asynchronously.
• A/B testing and a dashboard with three views: conversions, latency, and mismatch rate.
• A “Preview as intent” toggle and a text log of personalization decisions.

Insider templates that save hours

• Intent scoring (example): Referrer from comparison site = +3 (Compare). Landing on /pricing = +3 (Purchase). Blog path depth ≥2 = +2 (Research). Time-on-page ≥90s = +1 (weak). Score ≥3 → personalize; else show default.
• Block pattern: Hero headline + one-sentence proof + clear next step + safety net link (support or FAQ). Keep it consistent across intents; only the words change.
• Headline formulas:
  • Research: “Understand [topic] in minutes.”
  • Compare: “Compare [options] side-by-side.”
  • Purchase: “Start [result] today — risk-free.”
  • Support: “Stuck? We’ll guide you now.”

Step-by-step (from zero to measurable lift)

1. Choose 3 intents you can explain to a friend: Research, Compare, Purchase.
2. Assign scores to 4–5 signals. Only act when total ≥3. Document your thresholds.
3. Select 2 blocks to personalize first: hero headline and primary CTA.
4. Draft variants using the formulas. Then use the prompt below to create 3 options per intent. Do a quick human QA.
5. Implement async swaps with a 200ms timeout and a default fallback. Cache the chosen variant for the session.
6. Run an A/B test for 2–4 weeks or until you hit 50–100 conversions per variant.
7. Review 3 KPIs: target conversion, CTA CTR, and mismatch rate (<3%). Keep winners; cut losers.

Copy-paste AI prompt: variant generator (robust)

You are a careful website copywriter. Create three candidate variants for a single on-page block. Each variant must include: a 4–8 word headline, a one-sentence supporting line (max 18 words), and a 2–3 word CTA label. Keep it accurate, benefit-led, and privacy-safe (no personal data). Tone: helpful and confident. Output JSON with an array called variants, each item: {“headline”:””,”subline”:””,”cta”:””,”intent”:””,”confidence_note”:””}. Inputs — Intent: {intent}. Signals: {referrer}, {landing_page}, {time_on_page}, {key_clicks}. Page goal: {goal}. Constraints: avoid urgency hype, no discounts unless provided, plain language.

Copy-paste AI prompt: QA reviewer

You are a strict UX editor. Given the page goal, intent, and three variants (JSON), score each on 1) clarity, 2) relevance to intent, 3) accuracy (no overclaims), 4) reading ease (Grade 6–8). Return JSON: [{“index”:#, “scores”:{“clarity”:1-5,”relevance”:1-5,”accuracy”:1-5,”ease”:1-5}, “keep_or_cut”:”keep|cut”, “edit_suggestion”:”…”}]. If any headline exceeds 8 words, flag it.

Optional prompt: simple intent classifier

You classify anonymous visits into Research, Compare, Purchase, or Unknown. Use only these signals: {referrer}, {landing_page}, {time_on_page}, {key_clicks}. Return JSON: {“intent”:”Research|Compare|Purchase|Unknown”,”confidence”:0-1,”rationale”:”short reason”}. Be conservative. If confidence < 0.6, set intent to “Unknown”.

Worked example: financial planning service (services business)

1. Signals: Visitor lands on /fees via a comparison article. Clicks “plan tiers.” Time-on-page 45s.
2. Intent score: Referrer (compare) +3, pricing page +3, click on tiers +2 → total 8 (Compare).
3. Variant served (hero block):
   • Headline: “Compare plans side-by-side.”
   • Subline: “See what’s included and choose the right fit with a no-pressure consult.”
   • CTA: “Compare plans”
4. Fallback ladder: If referrer blocked → still on /fees → serve Compare. If both missing → serve default Research variant.
5. Test window: 21 days aiming for 80 consult requests per arm. Monitor latency and mismatch rate daily.
6. Expected outcome: Higher CTA clicks within week 1; consult requests lift by 10–20% by week 3 if copy is clear.

Extra mistakes & fixes (beyond the basics)

• Mistake: Segment “leakage” (wrong variant shows after navigation). Fix: Cache the chosen intent for the session; only upgrade intent when score increases materially.
• Mistake: Variant fatigue (you test too many at once). Fix: Cap to 3 variants per intent; retire underperformers quickly.
• Mistake: Ad blockers removing referrer. Fix: Use landing page path and on-site clicks as primary signals.
• Mistake: Overfitting to a seasonal spike. Fix: Revalidate winners quarterly; keep a neutral default year-round.

10-day action burst

1. Day 1: Pick page, define 3 intents, set scoring and thresholds.
2. Day 2: Configure signals in your tag manager and set the 200ms timeout + fallback.
3. Day 3–4: Draft variants with the generator prompt; run QA prompt; human review; finalize 2–3 per intent.
4. Day 5: Implement async swaps, session caching, and the “Preview as…” toggle.
5. Days 6–10: Launch A/B test, watch conversion/CTR/latency daily, cut losers by Day 8, and lock a winner by Day 10.

Closing thought: Personalization isn’t about guessing; it’s about matching clear intent with clear words, quickly and respectfully. Start with one block, one page, and a reliable fallback — the lift follows.

Turn AI into your bias buffer. A simple two-pass check catches most microaggressions in minutes and keeps your voice intact.

Insider trick: use a short “context card” before every AI edit, then run a two-pass sweep (flag first, rewrite second). This gives you consistent, on-brand, inclusive language without going bland.

What you’ll need

• 3 real snippets you write often (email, job blurb, promo line).
• Any AI assistant or editor.
• Your context card (audience, purpose, tone, sensitivities).
• A mini “red flags” list you grow over time.
• One human review when possible.

Do / Don’t checklist

• Do state intent up front: what the message must achieve and who it serves.
• Do focus on behaviours, skills, outcomes; keep identity mentions only when relevant.
• Do use people-first language when unsure (e.g., “people with diabetes”); use identity-first when the community prefers it and context fits.
• Do preserve agency and respect: active voice, clear asks, direct timelines.
• Do swap age cues for capability (“5+ years’ experience” instead of “young/energetic”).
• Do read aloud; replace idioms that can harm (“that’s wild” instead of “that’s crazy”).
• Don’t stereotype or tokenize (“ideal for stay-at-home moms,” “culture fit”).
• Don’t gatekeep with proxies (“native English speaker” → “professional proficiency in English”).
• Don’t use ableist or loaded phrases (“OCD about details,” “wheelchair-bound,” “grandfathered”). Use “detail-oriented,” “wheelchair user,” “legacy exception.”
• Don’t over-correct into vagueness. Keep specifics; change labels, not meaning.

10-minute two-pass routine

1. Create a context card (30 seconds): audience, purpose, must-keep tone, any sensitivities (e.g., hiring, healthcare, national audience).
2. Pass 1 — Flag only: ask AI to scan for microaggressions, assumptions, and tone issues. No rewriting yet; short reasons only.
3. Decide: keep, change, or clarify. Preserve voice and specificity.
4. Pass 2 — Rewrite: ask AI to produce a concise version that fixes only approved items and keeps your style.
5. Persona swap test (optional): ask “Would this read respectfully to X and Y?” If not, adjust.
6. Human glance: one colleague, or wait 24 hours and re-read with fresh eyes.
7. Save: add the final lines and any “always replace” words to your mini style guide.

Copy-paste prompts (use as-is)

• Context card + FlagPaste this first:“Context: Audience = [describe]. Purpose = [state outcome]. Tone = [e.g., respectful, confident, plain-English]. Sensitivities = [e.g., hiring, healthcare, national audience]. Task: Read the text below and only flag potential microaggressions, stereotypes, unnecessary identity mentions, ableist terms, or patronising tone. For each, quote the phrase and give a one-sentence reason. Do not rewrite yet. Text: “+[PASTE YOUR TEXT]+””
• Targeted rewrite“Using the flags we agreed, rewrite the text to keep meaning, voice, and specificity. Replace only the flagged phrases. Keep it concise and respectful. After the rewrite, list any words I should add to my ‘always replace’ list with one-line alternatives.”
• Persona swap test“Stress-test this message for inclusivity. Would it read respectfully to [Group A] and [Group B]? If anything may land poorly, show the line, the likely read, and a one-sentence fix. Keep my tone.”

Worked example

Original snippet:

• “We’re looking for a young, native English-speaking sales ninja who can work crazy hours; must be able-bodied; ideal for stay-at-home moms.”

Inclusive rewrite:

• “We’re hiring a sales professional with strong communication skills and proficiency in English. The role may include occasional extended hours with advance notice. We welcome candidates of all physical abilities and offer reasonable accommodations. Flexible scheduling options are available.”

What changed and why:

• young → removed; replaced with “sales professional” — avoids age bias; focuses on capability.
• native English-speaking → “proficiency in English” — sets a skill standard without nationality or origin.
• sales ninja → “sales professional” — removes gendered/insider jargon; clearer role.
• crazy hours → “occasional extended hours with advance notice” — avoids ableist slang; sets expectations.
• must be able-bodied → “welcome candidates of all physical abilities… accommodations” — removes exclusion; states support.
• ideal for stay-at-home moms → “flexible scheduling options” — avoids gendered assumptions; describes the benefit.

Build your red-flags list in 10 minutes

• Age cues: young, digital native, energetic → use experience or capability.
• Ableist terms: crazy, insane, OCD, lame, wheelchair-bound → wild/unexpected, meticulous, unhelpful, wheelchair user.
• Gendered group words: guys, manpower → team, people, workforce.
• Gatekeeping: native speaker, culture fit, rockstar/ninja → proficiency in X, values add, expert/pro.
• Legacy phrases: grandfathered → legacy exemption, prior exception.

Common mistakes and quick fixes

• Vagueness after edits — Fix: re-add specific outcomes and numbers.
• Identity erasure — Fix: include identity when material to the role or message, and say why.
• Over-reliance on AI — Fix: one human read or a 24-hour pause.
• Copy-paste EEO in headlines — Fix: keep inclusion statements, but place them in a standard footer; lead with the work, not the label.

Action plan (30 minutes this week)

1. Today (10 min): run the Context card + Flag prompt on one real email; apply the targeted rewrite.
2. Mid-week (10 min): convert flagged words into your red-flags list; add preferred alternatives.
3. Week’s end (10 min): persona swap test two high-stakes messages; save best lines into your mini style guide.

Expectation check: AI will catch most common issues fast. It may over-flag neutral phrases—use the reasons to decide. Your goal is clear, respectful language that still sounds like you.

Start small. Repeat often. Your voice stays human; the rough edges get smoothed.

Spot on: treating every brief like an experiment (deliver → measure → iterate) keeps teams honest and speeds decisions. Let me add a simple trick that makes the first draft land right the first time: build a tiny Layered Explainer Pack with a glossary and pre-answered exec questions. It removes friction before it appears.

Five-minute starter (do this now): Run the “Jargon Decoder + 30s pitch” prompt below on one paragraph of your doc. You’ll get plain terms, a crisp pitch, and the three questions leaders will ask—answered.

Copy-paste prompt (quick win):

“Act as a clear business communicator. Input: [paste one paragraph]. Tasks: (1) Jargon Decoder: list up to 8 terms with a 1-sentence plain-English definition and why each matters for the business. (2) 30-second elevator pitch (≤90 words) in non-technical language. (3) Three likely executive questions with one-line answers. If a fact isn’t in the input, say ‘Not specified.’ Tone: confident, concise, action-oriented. Output in bullets, no fluff.”

Why this works: Non-experts don’t fear technology; they fear confusion. A shared glossary plus a short, verified pitch removes risk and accelerates yes/no.

What you’ll need:

• Your technical paragraph or spec (even a rough draft is fine).
• 10–30 minutes and one SME for a light fact check.
• One real business example (cost, timeline, owner) to ground the claims.

Step-by-step: turn any complex topic into an executive-ready pack

1. Pass 1 — Decode (5 minutes): run the quick-win prompt above. Save the glossary and pitch.
2. Pass 2 — Layered Explainer (10 minutes): generate a clean, 3-layer brief leaders can read in two minutes.
3. Pass 3 — Fact check (10–15 minutes): SME verifies claims and flags unknowns with “Not confirmed.”
4. Pass 4 — Business example (3 minutes): swap one generic line for your company’s cost/timeline/owner.
5. Pass 5 — Measure (2 minutes): log decision time and follow-up questions. Iterate next time.

Copy-paste prompt (Layered Explainer Pack):

“You are an expert translator for senior non-technical leaders. Build a Layered Explainer Pack from this source: [paste paragraph or bullets]. Audience: 40–65-year-old business leaders. Constraints: use only facts from the source; if unknown, write ‘Not specified.’ Output sections: (1) 20-word summary, (2) 30-second elevator pitch (≤100 words), (3) Business impacts: 5 bullets labeled cost/time/risk/quality/compliance with Low/Medium/High and one-line rationale, (4) How it works in 3 simple steps (no jargon), (5) Glossary: up to 8 terms with plain definitions, (6) 5 likely executive questions with one-line answers, (7) Next step: one explicit action, suggested owner role, and decision window. Tone: confident, concise, non-technical. Target total length: 180–300 words.”

Insider add-on (optional, 2 minutes): Ask for one simple diagram you could sketch on a whiteboard.

Copy-paste prompt (diagram suggestion):

“Based on the Layered Explainer Pack above, propose one simple whiteboard diagram: title, 4–6 labeled boxes, arrows, and a 20-word caption anyone can follow.”

Mini example (what output should look like):

• 20-word summary: “A vector database makes search find meanings, not just words, so customers get faster, more accurate answers from content.”
• 30s pitch: “Instead of matching exact words, it matches ideas. For support and knowledge bases, this cuts hunt time, improves first-contact resolution, and reduces repeated tickets. It plugs into our existing search with a small pilot on one product line.”
• One impact bullet: Cost: Medium — fewer repeat tickets and faster answers reduce support hours by 10–20% (Not specified: exact baseline).

What to expect:

• Readable in under three minutes, with one clear next step.
• Fewer clarification emails because the top questions are pre-answered.
• Leaders can say yes/no without a meeting when the example is specific.

Common mistakes and fast fixes:

• Mistake: Overstuffing the brief. Fix: One page. One recommendation. One fallback.
• Mistake: Vague impacts. Fix: Use Low/Medium/High with a one-line why; add numbers only if in source.
• Mistake: Jargon slips back in. Fix: Run the Decoder and replace terms with plain language.
• Mistake: No owner or deadline. Fix: Write “Next step: [role], [action], decide in [X] days.”
• Mistake: Accepting uncertainty silently. Fix: Label gaps “Not specified” to keep trust high.

Simple 3-day action plan:

1. Day 1 (30–45 min): Run the Decoder and Layered prompts on one topic. Create two variants.
2. Day 2 (30–40 min): SME fact-check. Add one real example (cost/timeline/owner). Insert the next step and decision window.
3. Day 3 (15–20 min): Send to two stakeholders. Track decision time and any questions. Note one improvement for the next brief.

Pro tip: After approval, regenerate the pitch for different roles (CFO, COO, Legal) using the same facts. It saves meetings and keeps everyone aligned.

Small, clear, and verified beats long and clever. Ship the first pack today, measure tomorrow, and improve on Friday.

Onwards,Jeff

Good point: wanting to prevent microaggressions shows you already care about the people you’re writing for — that’s the best place to start.

Why this matters

Inclusive language reduces harm, widens your audience, and improves trust. You don’t need to become perfect overnight—small, systematic changes get big results.

What you’ll need

• Short examples of your existing text (one paragraph or a few bullets).
• An AI tool you can paste text into (chat assistant or editor).
• A simple checklist: avoid stereotypes, unnecessary identity mentions, ableist terms, and patronizing tone.
• At least one human reviewer from a different background when possible.

Step-by-step: a practical routine

1. Collect: pick 3 real snippets you write often (emails, bios, ads).
2. Run the inclusive rewrite prompt (copy-paste below) for each snippet.
3. Ask the AI to explain any flagged phrases—get short reasons why a phrase could be problematic.
4. Apply edits, then run a tone check: is it respectful and straightforward?
5. Do a quick human review with at least one colleague or community member when possible.
6. Save the revised lines into a mini style guide for future use.

Example

Original: “We’re looking for a young go-getter to help our fast-growing team.”

AI rewrite: “We’re seeking an enthusiastic team member to support our growth.”

Common mistakes & fixes

• Mistake: Over-correcting and making language bland. Fix: Keep voice and specificity—focus on behaviours and skills, not assumed identities.
• Mistake: Removing identity when it’s important. Fix: Include identity when it matters to context (e.g., lived experience for a role).
• Mistake: Relying only on AI. Fix: Use AI for drafts and explanations, then human-review for nuance.

Copy-paste prompt (use this first)

Rewrite the following text to be inclusive and free of microaggressions. Keep the meaning and tone similar, keep it concise, and highlight any phrase you changed with a brief reason (one sentence each). Then list any remaining words I should avoid in future writing and why. Text: “[PASTE YOUR TEXT HERE]”

Variants

• For hiring: “Rewrite this job description to focus on skills and remove biased language. Suggest inclusive alternatives for any gendered, ageist, or ableist terms.”
• For marketing: “Make this promotional copy inclusive for a national audience, avoiding stereotypes and microaggressions. Keep it energetic and under 40 words.”
• For explanations: “Scan this paragraph, flag anything that could be a microaggression, explain why in one sentence, and give a revised sentence.”

Action plan (quick wins)

1. Today: paste one email into the main prompt and apply edits.
2. This week: create a short style guide with 10 do/don’t examples from your rewrites.
3. Ongoing: use the prompt as a pre-send checklist for sensitive comms.

Closing reminder

Start small, iterate fast. Use AI as a coach that explains choices, not an editor that replaces judgment. Over time, your natural voice will become clearer and kinder—every revision counts.

Hook: You can turn a one-size-fits-all website into a helpful, timely experience that matches why a visitor came — and you don’t need a PhD to start.

Quick context: Visitor intent usually falls into simple buckets: searching for information, comparing options, ready to buy, or seeking help. AI can detect signals (where they came from, what they clicked, how long they stayed) and serve tailored headlines, offers, or next steps.

What you’ll need

• Basic site analytics (Google Analytics or similar).
• A way to capture real-time signals (UTM, referrer, landing page, on-site clicks). A tag manager helps.
• Either a personalization tool or simple server-side logic to swap content blocks.
• An LLM or simple rules engine for content variations (start with rules, add AI later).
• Tracking and A/B testing to measure results.

1. Choose intent categories — keep it to 3–4: Research, Compare, Purchase, Support.
2. Map signals to intent — e.g., arrival via “blog” + long time on page = Research; product page + cart clicks = Purchase.
3. Create content variants — short headline + tailored CTA for each intent. Use AI to scale variants.
4. Deploy simple rules first — swap hero headline based on UTM/referrer/page. Measure uplift.
5. Introduce AI for nuance — use an LLM to create personalized microcopy based on detected intent and user info.
6. Test and iterate — A/B test intent-based experience vs baseline. Track conversion and engagement.

Example

• Visitor from a product comparison site + short visit on pricing page → show: “Ready to compare features? See side-by-side specs + a 7-day trial.”
• Visitor reading how-to blog for 5+ minutes → show: “Want a checklist? Download the quick-start guide.”
• Returning visitor with past purchase → show: “Welcome back — reorder with one click.”

Common mistakes & fixes

• Mistake: Over-personalizing with wrong data. Fix: Start with clear signals and conservative swaps.
• Mistake: Slowing page load. Fix: Render personalized blocks asynchronously.
• Mistake: Ignoring privacy. Fix: Respect consent and anonymize data.

Copy-paste AI prompt (use with your LLM):

“You are a friendly website copywriter. Given the visitor intent and brief user signals, write a short headline (6–8 words), a one-sentence supporting line, and a clear CTA label. Keep tone helpful and concise. Visitor intent: {intent}. Signals: {referrer}, {landing_page}, {time_on_page}, {previous_actions}. Output JSON with keys: headline, subline, cta.”

90-day action plan (quick wins)

1. Week 1: Define intents and map signals.
2. Week 2: Create 3 variants per intent (rule-based swaps).
3. Weeks 3–4: Run A/B tests on top pages.
4. Month 2: Add LLM-generated variants for higher volume pages.
5. Month 3: Review metrics, scale winners, tighten signals.

Closing reminder: Start small, measure fast, and let data tell you which intent-driven messages actually help people. Personalization isn’t magic — it’s focused relevance delivered at the right moment.

Yes to the quick win and the one-line “what to expect.” Reviewers read parameters and checks first, so let’s make those rock-solid and fast to produce.

Two power moves that level up your appendix

• Snapshot fingerprints: ask AI to generate simple, verifiable data fingerprints (row count, column list, min/max dates, top-3 categories) so anyone can confirm they’re starting from the same snapshot.
• Failure-mode table: have AI list likely break points (schema change, missing seed, time zone drift) with “if this happens, do this” fixes. This cuts reviewer back-and-forth.

Do / Do not

• Do lock randomness (seed), date windows, and file encodings. Specify versions for software and key packages.
• Do separate method steps from results. Keep one action per line, each with expected outcome.
• Do include a short reproducibility budget (acceptable variation, e.g., “AUC ±0.01”).
• Do capture why a parameter was chosen (median imputation due to skew).
• Do add a change log with dates and a one-line reason per change.
• Do not bury parameters in prose or rely on “typical settings.”
• Do not omit data access/permissions or environment details.
• Do not use vague verbs (“clean”, “adjust”). Use explicit actions (“drop rows where id is null”).

What you’ll need

• Your bullets on data, preprocessing, analysis.
• One sample row or schema (no personal data).
• Any scripts or pseudocode.
• Software and exact versions (or container/conda file).
• Target audience and desired length (1-page policy vs. reviewer-deep).

Step-by-step (fast, repeatable)

1. Calibrate the style: give AI one short “golden” paragraph you like and say “match this tone and structure.”
2. Generate appendix blocks: ask for sections: Overview, Data & Permissions, Sampling, Step-by-step Preprocessing, Variables, Analysis, Parameters with rationale, Environment, Validation checks, Failure modes, Limitations, Change log.
3. Add fingerprints and checks: request 3–5 data fingerprints and 5 preflight checks with expected ranges.
4. Red-team it: switch AI’s role to “skeptical reviewer” and have it list ambiguities and missing parameters; fix in one pass.
5. Dry-run or peer-run: execute steps in a clean environment or have a colleague follow the checklist. Note any deltas; tighten wording.
6. Set the reproducibility budget: define acceptable variation for key metrics and outputs.
7. Finalize and version: add versions, date, author initials, and a clear one-line “what to expect.”

Copy‑paste AI prompts

Master builder

“You are an expert research methodologist. Using my notes, draft a methodological appendix with these sections: Overview; Data sources & permissions; Sampling; Step-by-step preprocessing (one action per line, explicit parameters and seeds); Variable definitions; Analysis steps with precise commands or clear pseudocode; Parameter list with default values and rationale; Software and exact versions; Data fingerprints (row count, column list, min/max dates, top 3 categories); Preflight validation checks with expected ranges; Failure-mode table (symptom, likely cause, fix); Limitations; Change log. End with a one-sentence reproducibility expectation and a 3-step reproduction checklist. Keep jargon low, be precise.”

Reviewer red-team

“Act as a skeptical reviewer. Read the appendix and identify: missing parameters, ambiguous verbs, environment/version gaps, and any step that is not testable. Output a bullet list of issues and a corrected version of those lines with explicit values.”

Style and length control

“Rewrite for [journal reviewers | policy audience] in [500–800 | 1-page] format. Preserve all parameter values, checks, and environment versions. Remove any marketing tone.”

Worked example (editable template)

• Overview: We cleaned a 2019–2022 customer events dataset to predict churn at 90 days.
• Data & permissions: Internal de-identified snapshot; read-only; no personal data.
• Sampling: Include users with first activity between 2019-01-01 and 2022-12-31; drop rows where user_id is null; de-duplicate on user_id, keep earliest event.
• Preprocessing (numbered, testable):
  1. Load CSV with UTF-8; parse dates as UTC.
  2. Filter event_date to 2019-01-01..2022-12-31.
  3. Drop rows where user_id is null.
  4. Aggregate to user level: last_active_date = max(event_date).
  5. Create target churn_90 = 1 if no activity for 90 days after signup_date; else 0.
  6. Impute numeric nulls with median per feature (seed=42).
  7. One-hot encode categorical vars, drop_first=true.
  8. Standardize numeric vars to z-score; store originals as _raw.
  9. Split train/test = 80/20, stratify by churn_90, seed=42.
• Analysis: Logistic regression with L2 penalty; C=1.0; solver=liblinear; max_iter=1000.
• Parameters with rationale:
  • seed=42 (reproducibility)
  • date_window=2019–2022 (policy period)
  • impute=median (robust to skew)
  • encode=one-hot drop_first (avoid multicollinearity)
  • penalty=L2, C=1.0 (baseline regularization)
• Environment: Python 3.10; pandas 2.1; numpy 1.26; scikit-learn 1.3; OS: Ubuntu 22.04.
• Data fingerprints (example ranges):
  • Row count after filtering: 50k–60k
  • Columns: user_id, signup_date, last_active_date, features_*
  • Min/Max signup_date: 2019-01-01 / 2022-12-31
  • Top 3 countries: US, GB, AU
• Preflight checks:
  • No nulls in user_id after step 3.
  • Train/test stratification: churn_90 prevalence within ±1% of full dataset.
  • Feature count increases after one-hot; no unexpected new categories.
  • Random seed yields identical train/test sizes across runs.
• Failure modes → fixes:
  • Mismatch in date range → ensure timezone set to UTC before filtering.
  • Different split each run → seed not applied; set seed in splitter.
  • Encoding error → unexpected category; add “handle_unknown=ignore”.
• Limitations: Only historical behavioral features; no pricing or support tickets; may understate churn due to offline activity.
• One-line reproducibility statement: “Re-running steps 1–9 on the 2019–2022 snapshot should reproduce identical splits and an AUC between 0.70–0.72 with churn prevalence within ±0.5%.”
• Change log: 2025-02-10 v1.2 — added seed to splitter; clarified date timezone.

Common mistakes & quick fixes

• AI invents parameters: Bind ranges or allowed values in your prompt; ask it to flag any invented items in a separate list.
• Environment drift: Pin versions and request a minimal conda or Docker snippet; add a one-line install instruction.
• Vague sampling: Rewrite as measurable filters (field, operator, value, timezone).
• Overlong appendix: Ask for a 1-page policy summary plus a technical appendix; keep all parameters in the technical section.

45‑minute action plan

1. 10 min: Gather bullets, schema, versions.
2. 15 min: Run the Master builder prompt; request fingerprints, checks, and failure modes.
3. 10 min: Red-team with the reviewer prompt; accept fixes.
4. 10 min: Dry-run a subset of steps; note any gaps; regenerate those lines.

Closing reminder: Lead with one sentence of expected results, then give 5 checks and the locked parameters. That’s the fast lane to “clear, usable, reproducible.”