linersh 0.5.7 → 1.0.1

package/cli-update-docs/CURATION.md

@@ -1,261 +0,0 @@
-# Curating Mixtapes
-
-A methodology for assembling AI-consumable context bundles that actually work.
-
----
-
-## What this document is
-
-A methodology for building mixtapes — curated bundles of sources designed to give an AI substantive context on a specific topic, so it can produce better answers, better drafts, and better judgments than it would from its training data alone.
-
-This document is platform-agnostic. It describes *how to curate well*, not how any specific tool implements curation. Liner is one implementation; the methodology applies equally to mixtapes built with other tools or by hand.
-
-The methodology has two intended audiences:
-
-- **Tools running the methodology automatically** — like the Liner skill, which encodes this document as instructions for an AI executing the lifecycle on a curator's behalf.
-- **Curators practicing the methodology themselves** — building library-quality mixtapes by engaging substantively at each step.
-
-Most users will be in the first group. Their tool runs the methodology for them; they confirm or lightly edit. The second group is the minority that produces the best mixtapes — including everything in the Liner library. This document serves both.
-
----
-
-## The bar
-
-A good mixtape demonstrably improves the AI's output on tasks within its domain. That's the only test that matters.
-
-A bad mixtape is one of three things: a bookmark dump (no curation), a popular-content collection (no taste), or a topical Wikipedia-style overview (no specificity). All three are easy to produce. None of them help.
-
-What makes a mixtape useful for an AI is different from what makes a reading list useful for a human. An AI doesn't need motivation, doesn't get bored, doesn't benefit from inspirational framing. What it does benefit from:
-
-- **Primary sources over commentary.** The original specification beats someone explaining the specification.
-- **Concrete over abstract.** "Touch targets should be 44pt minimum because..." beats "design with users in mind."
-- **Specific over general.** A 20-minute deep dive on one pattern beats a 60-minute survey of ten.
-- **Recent enough to be accurate, old enough to be durable.** The sweet spot for most topics is one to four years old for principles, very recent for platform specifics.
-- **Diverse perspectives where the field is contested.** If experts disagree, include both sides. The AI synthesizes better from disagreement than from echo chambers.
-
-A mixtape stuffed with motivational talks will produce worse AI output than a mixtape of three dense technical specifications. Counterintuitive but real.
-
----
-
-## The lifecycle
-
-Every mixtape moves through the same phases. The phases are ordered because each one's output is the next one's input. Skipping phases or running them out of order produces lower-quality mixtapes — even if the result looks complete.
-
-### Phase 1 — Framing
-
-Define the job-to-be-done. Not the topic. The *use case*.
-
-The JTBD is written as a Job Story: **"When [circumstance], I want [motivation], so I can [outcome]."** All three slots are required. The form is permissive on what fills them — a legal, clinical, or engineering Job Story share this shape but no vocabulary. What it guarantees is that no slot can be empty, which raises the floor on what counts as a JTBD before any qualitative judgment kicks in.
-
-"Mobile design" is a topic. It is too vague to curate against. Three Job Stories in that same topic produce three different mixtapes:
-
-- *When I'm designing the core UI of a consumer iOS app, I want to follow Apple's interaction conventions while choosing where to deviate visually, so I can ship something that feels native without looking generic.*
-- *When I review mobile design portfolios as a senior IC hiring manager, I want to compare candidates against a consistent rubric of taste and decision-making, so I can decide who to advance with confidence.*
-- *When I'm choosing a platform strategy for a new mobile product, I want to weigh native vs. cross-platform against the specific constraints of my team and timeline, so I can commit to one path without re-litigating the question every quarter.*
-
-If the job-to-be-done can't be stated as a tight Job Story — single circumstance, single motivation, single outcome, no solutions named, no aspirational mush — the mixtape will be unfocused. This is the single most common failure mode. The [JTBD Master Prompt](JTBD-MASTER-PROMPT.md) is a drop-in interview that elicits one in a single human turn; use it (or have the AI use it) at the start of any new mixtape.
-
-Sketch a knowledge map alongside the JTBD: the major areas of the domain, the sub-areas, the edge cases. For mobile design, that might be foundations, patterns, craft, process, edge cases. For another domain, the buckets are different. The map serves three purposes: it structures research, it surfaces gaps, and it becomes the section structure of the finished mixtape.
-
-Treat the map as a hypothesis. It will get revised during research.
-
-### Phase 2 — Candidate discovery
-
-Generate a long list of candidate sources covering the knowledge map. Lots of them. This phase is about recall, not precision — gather more than you need; you'll cut later.
-
-Methods that produce better candidates than generic search:
-
-**Follow the citations.** Pick one excellent piece on the topic and find what *it* cites or links to. Then follow those sources' citations. Three or four hops in, you'll find the canonical sources nobody links to anymore because everyone assumes you've read them.
-
-**Reverse-engineer experts' reading lists.** Many domain experts publish their own reading lists or syllabi. Constrain searches to platforms like Notion, GitHub, Are.na, or personal blogs. Are.na in particular is underused.
-
-**Mine course syllabi.** University courses, bootcamp curricula, and serious online courses have already done curation work. `"<topic> syllabus" filetype:pdf` is a productive query.
-
-**Find who experts cite.** Pick three to five acknowledged experts. Look at *their* references — bibliographies, acknowledgments, who they cite in their own writing. The overlap is your shortlist.
-
-**Conference proceedings.** Going through three years of a specific conference is more efficient than searching for talks topic-by-topic.
-
-**Ask the AI to find gaps, not sources.** Once you have a candidate list, ask: *what's missing from this collection for someone trying to [job-to-be-done]?* AI is bad at recall and good at critique. Use it for the right thing.
-
-No fetching yet. This phase produces URLs and titles, not content.
-
-### Phase 3 — Fetching
-
-Pull content for every candidate into the cache. Transcripts, articles, metadata. This is the expensive phase — network calls, transcript scraping, content extraction.
-
-Two things matter here. First, fetching is part of research, not a tail step. A source can't be honestly evaluated without reading it. Second, fetched content should be cached. The same source used in multiple mixtapes should be fetched once.
-
-After fetching, every candidate has readable content available for evaluation.
-
-### Phase 4 — Evaluation
-
-Read the fetched content and rate each candidate against the job-to-be-done. This is where keep/trim/drop decisions actually happen.
-
-Source quality, roughly in order of preference:
-
-1. **Canonical references.** Apple HIG, Material Design docs, W3C specs, RFC documents, official platform documentation. Always include the primary source if one exists.
-2. **Practitioner deep-dives from people who built things.** Engineers and designers at credible companies writing about specific decisions they made. Concrete and battle-tested.
-3. **Conference talks from credible speakers.** Pre-filtered by the conference's curation. Better than random video search.
-4. **Books, but chapters not whole books.** Link to a specific chapter or excerpt. A tape isn't a book club.
-5. **Long-form interviews with practitioners.** Best when you cite a specific episode for a specific point.
-6. **Academic papers when relevant.** Often underrepresented in design and engineering mixtapes.
-
-What to avoid:
-
-- Listicles ("10 tips for...")
-- AI-generated content (now widespread, often subtly wrong)
-- Twitter threads as primary sources
-- Vendor blog posts with promotional angles
-- Most TED-style talks — too much narrative, not enough density
-- "Ultimate guides" — usually shallow despite the name
-
-Evaluations should include a brief reason. "This source is canonical for the foundations section." "This source duplicates Source 4 — drop the weaker one." "This source has a strong perspective; useful but read alongside Source 7." These reasons go into the working notes.
-
-### Phase 5 — Quality checks
-
-Four tests every mixtape should pass. Run them deliberately.
-
-**The redundancy test.** Read each source's role in the mixtape. Are any two sources making essentially the same point? If yes, keep the better one and cut the other. Mixtape volume is not a virtue. Five excellent sources beat fifteen good ones.
-
-**The coverage test.** Walk through the knowledge map. Any bucket with zero sources? Either fill it or explicitly note that the mixtape doesn't cover that area. A mixtape that silently omits a major area is worse than one that says "this mixtape doesn't cover X — see [other mixtape] for that."
-
-**The disagreement test.** Pick the strongest claim made by sources in the mixtape. Find someone credible who disagrees with it. Either include the disagreement or explicitly note that the mixtape takes a position. A mixtape that only includes one side of a contested question produces worse AI output, because the AI then can't see the contested-ness.
-
-**The framing-gap test.** Step back and look at the whole mixtape. Is there a major perspective on this topic that's missing entirely — not just an individual source, but a whole way of thinking about the JTBD? If yes, the framing was too narrow. Expand the knowledge map and revisit Phase 2.
-
-This last test is the one most curators skip. It's also the highest-leverage. Single-pass curation tends to produce mixtapes that are well-covered within one narrow framing. The framing-gap test catches this.
-
-If a mixtape fails any of these tests, fix it before moving on.
-
-### Phase 6 — Synthesis
-
-Write the synthesis. This is the distilled understanding of the domain expressed in the curator's own voice — the principles, the contested questions, the framework distinctions, the recommended applications.
-
-The synthesis lives at the top of the compiled mixtape. It's the first thing the consuming AI reads. Without a synthesis, the AI gets a list of sources and curator notes; with a synthesis, the AI gets the curator's framing of the entire domain. The difference in downstream AI output is substantial.
-
-Length: 800–2000 words is typical. Shorter for narrow topics; longer for broader ones.
-
-The synthesis is required, not optional. In automated curation, the AI drafts it. In methodology-mode curation, the curator writes or substantially edits it. Either way, every mixtape has one.
-
-### Phase 7 — Final assembly
-
-Compile the mixtape. The compile step:
-
-- Reads the recipe and the synthesis
-- Reads cached source content for every kept source
-- Writes the master file (synthesis + how-to-use + source index)
-- Writes individual source files referenced by the master file
-
-The output is a self-contained mixtape folder ready to share, publish, or paste into an AI conversation.
-
-### Phase 8 — Empirical test (optional but recommended)
-
-Theory aside — here's how to know if the mixtape is actually working:
-
-1. Compile the mixtape
-2. Paste it into an AI conversation as context
-3. Ask the AI a question that the mixtape's job-to-be-done should help with
-4. Ask the same question without the mixtape in a separate conversation
-5. Compare the answers honestly
-
-If the answer with the mixtape is meaningfully better — more specific, more correct, more nuanced, less generic — the mixtape is working. If the answers are similar, the mixtape isn't earning its place. Either the sources are too generic, the synthesis isn't doing enough work, or the JTBD is too broad.
-
-This empirical check is required for library contributions. Run it. Document the result.
-
----
-
-## Curator notes
-
-Every source in a mixtape has a curator note. The note tells the AI (and the human reading the mixtape) three things:
-
-- *Why this source is in the mixtape.* Signals weight. "Watch first — this is the foundational piece" vs. "Skim if time permits — useful for context but not essential."
-- *Where the high-value portion is.* "The first ten minutes are setup, the load-bearing content starts around 10:30."
-- *What the source's limitations are.* "Dated on platform specifics, durable on principles."
-
-Good notes are 15–40 words. Shorter is fine when the source is self-explanatory. Longer is usually a sign the source needs more framing — or that the note is doing work the synthesis should be doing.
-
-In automated curation, the AI drafts notes during evaluation. In methodology-mode curation, the curator writes or substantially edits them. Notes are not optional.
-
----
-
-## Personal sources
-
-Not every source has a public URL. The strongest mixtapes often draw on material that isn't publicly available — book chapters, gated articles, course transcripts, personal notes. These are often the highest-density material in a mixtape and shouldn't be excluded just because they aren't on the public web.
-
-Cite non-public sources clearly. Author, title, publication, date. The compiled mixtape uses these citations to signal what kind of source the AI is looking at, which matters for how it weights the content. A passage labeled as a 2019 book chapter gets read differently than one labeled as a recent newsletter post.
-
----
-
-## Sharing mixtapes
-
-Most mixtapes are personal — built for your own thinking, used by you, drawing on whatever you have legitimate access to. There's nothing to think hard about here.
-
-Sharing is different. A mixtape passed to a colleague or posted publicly distributes its contents to people other than you. Sources that are fine for personal use may not be appropriate to redistribute. Use your own judgment.
-
-When in doubt, share the recipe (the tape file) rather than the compiled mixtape. The recipe references sources; the compiled mixtape contains them. They have different properties when they leave your hands.
-
----
-
-## The two modes
-
-The methodology supports two intensities of engagement.
-
-**Quick mode** runs the methodology automatically. The curator provides the JTBD and confirms the AI's proposals at each gate. The AI does the heavy lifting — generating candidates, evaluating, drafting curator notes, drafting the synthesis. The curator's job is to catch obvious errors and make final calls. A complete mixtape takes 15–30 minutes. Output is good enough for personal use.
-
-**Methodology mode** treats the AI as a research assistant rather than the curator. The curator engages substantively at each gate — revises the knowledge map, reviews evaluation rationales, makes deliberate keep/drop decisions, writes their own synthesis. The AI accelerates the tedious work; the judgment stays human. A complete mixtape takes several hours. Output is library-eligible.
-
-Both modes use the same lifecycle and produce the same artifact shape. They differ in how much human judgment shows up in the working notes and the synthesis. Quick mode mixtapes can be upgraded to methodology mode by going back and doing the substantive work; methodology mode mixtapes can be produced in one pass by curators who already know the domain.
-
-The default is quick mode because that's what most users want. Methodology mode is the path for serious curation work, including all library contributions.
-
----
-
-## Common failure modes
-
-Patterns that produce bad mixtapes. Watch for them.
-
-**The greatest-hits mixtape.** A list of the most famous resources on a topic. Looks impressive, adds little value because the AI already knows about famous resources from training. Curate for *non-obvious* sources, not popular ones.
-
-**The unfocused mixtape.** No clear job-to-be-done; tries to cover the entire field. Result: shallow on everything, deep on nothing.
-
-**The author-tribute mixtape.** Three of the five sources are by the same person, because the curator is a fan. This narrows perspective and reduces the AI's ability to synthesize across views.
-
-**The transcript dump.** Many video transcripts, no articles, no specifications, no primary sources. Transcripts are useful but conversational and low-density. Mix sources.
-
-**The noteless mixtape.** Sources without curator notes. Either the curator was lazy or didn't actually have a reason for each source. Both are problems. If a source's role can't be articulated, it doesn't belong.
-
-**The aspirational mixtape.** Sources the curator thinks people *should* read, not sources that help with the actual job-to-be-done. Mixtapes are tools, not reading recommendations.
-
-**The single-pass mixtape.** Curated without a framing-gap test. Well-covered within one narrow framing, blind to whole perspectives the curator didn't think to look for.
-
----
-
-## A note on AI assistance
-
-Most curators will use AI to help with research, source discovery, and drafting. This is fine and expected. The work goes better when the AI is treated as a collaborator with biases, not an oracle.
-
-AI is especially prone to:
-
-- Suggesting popular and recent sources at the expense of canonical or older ones
-- Hallucinating sources that sound plausible but don't exist (always verify URLs)
-- Producing generic curator notes that say "this is a useful resource" without specificity
-- Missing primary documents (specs, papers) in favor of secondary commentary
-- Failing the framing-gap test because it doesn't notice what it didn't search for
-
-Compensate deliberately. Search for primary sources yourself even when AI doesn't surface them. Verify every URL. Treat AI-drafted notes as first drafts. Run the framing-gap test with intent.
-
-The methodology assumes a human in the loop. Quick mode reduces what the human does; it doesn't eliminate it. The minimum is reviewing the AI's proposals at each gate. Anything less is automated source-listing, not curation.
-
----
-
-## What this is not
-
-Not a content recommendation system. Not a way to compile reading lists. Not optimized for human learning paths — those are different artifacts with different constraints.
-
-This is a way of producing artifacts that make AI systems demonstrably more useful within a specific domain. Everything in this document serves that goal.
-
-If decisions start prioritizing human readability or aesthetic completeness over AI utility, the methodology is drifting. Drift back.
-
----
-
-*Current version: 2.0. Changes are tracked in the repository changelog.*

package/cli-update-docs/JOB-STORY-MIGRATION.md

@@ -1,99 +0,0 @@
-# Job Story Format Migration
-
-The `jtbd:` field in every Liner `tape.yaml` is changing from the old "Help me [verb] [object] [scope]" house form to the Intercom Job Story format: "When [circumstance], I want [motivation], so I can [outcome]." This document is the full checklist for that change.
-
-## The new canonical form
-
-Spec: `When [circumstance], I want [motivation], so I can [outcome].`
-
-All three slots required. Failure modes the validator (or rubric) should catch:
-
-- Missing slot
-- Solution in any slot (vendor, framework, library, methodology, or tool name)
-- Two jobs joined by "and" / comma / slash within a single slot
-- Aspirational mush ("be better at X," "succeed," "do it well")
-- Topic-as-JTBD (bare noun phrase masquerading as a Job Story)
-- Generic circumstance ("when I'm working") with no scoping
-
-Until a real validator exists, the JTBD master prompt's internal rubric is the authoritative test.
-
-## Files to update (known)
-
-| File | What changes |
-|------|-------------|
-| `cli-update-docs/MIXTAPE-FORMAT.md` | Update the `jtbd:` field spec to require Job Story form. Add structural and qualitative checks. |
-| `cli-update-docs/CURATION.md` | Phase 1 (Framing) references the house form throughout. Replace examples. Update the "single specific sentence" guidance to name the three required slots. |
-| `cli-update-docs/SKILL.md` | The `curating-mixtapes` skill's Phase 1 paragraph defines what a tight JTBD looks like. Replace examples and any embedded house-form templates. |
-| `cli-update-docs/JTBD-MASTER-PROMPT.md` | Drop in the revised version from the previous turn. |
-| `cli-update-docs/JTBD-MASTER-PROMPT-ABOUT.md` | Substantial rewrite. The current doc explicitly defends choosing the house form over Job Story as a deliberate deviation from the mixtape's synthesis. The new framing inverts: "we initially diverged, then realigned." Update §"Where it came from," the Liner's-house-form choice in §"Design choices worth understanding," and any other instances. |
-| `cli-update-docs/LINER-MASTER.md` | Project-level overview. Sweep for house-form references and example JTBDs. |
-
-## Files to check (categories — likely exist, names not confirmed)
-
-Worth grepping the repo for:
-
-- `README.md` files at root and in subdirectories
-- Any `tape.yaml.template` or scaffolding used by `liner init` (or equivalent)
-- CLI help text — `liner --help`, `liner jtbd --help`, anywhere example JTBDs appear in user-facing strings
-- Test fixtures and sample mixtapes used in automated tests
-- Documentation site source if it lives separately from `docs/`
-- Any top-level index or table of contents inside `cli-update-docs/`
-
-Suggested sweep: `rg -l 'Help me ' --type md` and `rg -l 'jtbd:' --type yaml` should surface most of them.
-
-## Existing mixtapes to migrate
-
-Every existing mixtape's `tape.yaml` has a `jtbd:` in the old form (or, in one known case, no form at all — see Bootstrap below).
-
-Two strategies:
-
-**Option A — Migrate all at once.** Walk every `mixtapes/*/tape.yaml`, translate each JTBD to Job Story form (manually or with a one-shot prompt), commit together. Cleaner end state; no transition logic needed in code.
-
-**Option B — Accept both forms during a transition window.** Validator warns on old-form JTBDs but doesn't reject. Migrate as you touch each mixtape. Lower upfront cost; longer drift window; risk that some mixtapes never get touched.
-
-Recommendation: **Option A**, given the small corpus. Transition logic in a validator is permanent maintenance cost for what should be a one-time migration.
-
-Known mixtapes:
-
-- `examples/mobile-design-foundations/tape.yaml`
-- `mixtapes/jtbd-master-prompt/tape.yaml` (see Bootstrap problem below)
-
-## The bootstrap problem
-
-The mixtape that informed the JTBD master prompt — `mixtapes/jtbd-master-prompt/` — has this as its own `jtbd:`:
-
-> "A guide to help an AI agent create a master prompt that will be used to create a short Job To Be Done description about a hyper-specific task inside a project."
-
-This is neither form. It starts with "A guide to..." — a noun phrase describing the artifact, not a Job Story. No circumstance, no motivation slot, no outcome slot.
-
-Why it matters:
-
-1. **Structural seed-corn problem.** The mixtape that taught the methodology has a JTBD that wouldn't pass the methodology's own rules. When validation goes live, this mixtape fails.
-2. **Whitelisting is worse than fixing.** A permanent exception for the seed mixtape ships inconsistent rules on day one.
-3. **Migrating is mildly retroactive.** The synthesis was generated against this loose JTBD; a stricter one might have produced a tighter synthesis. But the synthesis is good enough that this is a small effect, and the alternative is permanent technical debt.
-
-Recommended action: migrate it. Proposed Job Story:
-
-> "When I'm designing the master prompt an AI agent will use to elicit a Job Story from a Liner user, I want a curated bridge between JTBD theory and prompt engineering, so I can write a prompt that produces tight, hyper-specific Job Stories in a single human turn."
-
-That passes the rubric. Tighten further if useful, but it's a defensible starting point.
-
-## Transition strategy (recommended ordering)
-
-The order matters because some changes invalidate others.
-
-1. **Spec docs first** — `MIXTAPE-FORMAT.md`, `CURATION.md`, `SKILL.md`. Any new mixtape created from this point uses Job Story form.
-2. **Drop in the revised JTBD master prompt** (`JTBD-MASTER-PROMPT.md`).
-3. **Rewrite `JTBD-MASTER-PROMPT-ABOUT.md`** so the rationale matches the new reality.
-4. **Migrate the two known mixtapes** (`examples/mobile-design-foundations/`, `mixtapes/jtbd-master-prompt/`).
-5. **Grep for stragglers** (`rg 'Help me ' --type md`, `rg 'jtbd:' --type yaml`) and migrate anything found.
-6. **Only then add a validator** — and start it in warn-only mode for one release cycle before rejecting.
-
-Doing the spec docs and the prompt before the validator means new mixtapes are correct from the start. Doing the migration before the validator means you don't ship a validator that rejects your own seed mixtape on day one.
-
-## What this doesn't cover
-
-- **Format versioning.** Whether to support both forms long-term via a `format_version` field in `tape.yaml`. Probably not worth the complexity for a small corpus; flagged in case it becomes relevant.
-- **Validator design.** The rubric in the JTBD master prompt is qualitative. An LLM-as-judge pattern (Promptfoo `llm-rubric`, Source 28 of the mixtape synthesis) is the natural implementation. A pure regex/parser check can only catch slot absence, not mush — necessary but insufficient.
-- **Distribution backward compatibility.** If mixtapes are ever distributed via a package registry, users may hold old-form copies after a format change. If mixtapes only live in user repos, this isn't a concern.
-- **The migration of any third-party or external mixtapes.** Scope this doc to your own repo; signal the format change to anyone downstream separately.

package/cli-update-docs/JTBD-MASTER-PROMPT-ABOUT.md

@@ -1,133 +0,0 @@
-# About the JTBD Master Prompt
-
-Companion document to [`JTBD-MASTER-PROMPT.md`](./JTBD-MASTER-PROMPT.md). Explains what the prompt is, why it exists, how it works, where it came from, and where it can still go wrong.
-
----
-
-## Why this exists
-
-Liner's curation methodology has eight phases. Phase 1 — Framing — is the single highest-leverage step in the lifecycle. The job-to-be-done statement defined here drives every downstream decision: which sources land in the candidate longlist, how the knowledge map is sectioned, what gets cut at evaluation, how the synthesis is framed. A bad JTBD propagates through everything else and produces a mixtape that looks complete but doesn't measurably improve AI output. A good JTBD makes every downstream phase easier.
-
-The methodology already knows what a tight JTBD looks like. `CURATION.md` says it must be a "single specific sentence." `SKILL.md` says the AI must "push back" if the user offers a topic. `MIXTAPE-FORMAT.md` documents the `jtbd:` field. But that guidance is spread across multiple docs and lives in the curator's head, not in a deployable prompt. The result, in practice: users land at "topic" level ("mobile design," "SEO content," "contract law") instead of "job" level. Once they do, the rest of curation drifts.
-
-The JTBD Master Prompt fixes that gap. It's a single, drop-in prompt that takes a user from wherever they are — a vague topic, a folder of content, a half-formed idea — to one tight Job Story that passes a rubric. That Job Story is the input to the rest of Liner's pipeline. Everything else (knowledge map, candidate discovery, evaluation, synthesis) is already handled.
-
-## What it is
-
-A self-contained master prompt stored at `cli-update-docs/JTBD-MASTER-PROMPT.md`. The body sits between `---BEGIN---` and `---END---` markers and is meant to be copy-pasted into an AI conversation, embedded inside the `curating-mixtapes` skill, or spawned as a TUI subprocess.
-
-The prompt's sole deliverable is a single sentence in the Intercom Job Story form: *"When [circumstance], I want [motivation], so I can [outcome]."* No rationale, no knowledge map, no commentary — those belong to later phases. One sentence on one line.
-
-The prompt is interactive: it offers to read project material, conducts a small interview (capped at five questions, three typical), runs the draft through an internal rubric, and emits.
-
-## How it works
-
-Five moves, in order:
-
-**Step 0 — Offer to read project material.** The agent's first message is a single short question: *"Do you have any documents or project material I should look at first?"* The user can drop files into the chat, point at a folder (if the agent has filesystem access), or say no and move straight into conversation. This question fires unconditionally and does not count against the question budget. The reason for asking rather than detecting: users frequently have load-bearing material they wouldn't think to share unprompted, and silent inference of context produces wrong JTBDs that propagate through every downstream phase.
-
-**Step 1 — Read what the user shared, if any.** If the user shared material, the agent reads enough to confidently characterize the project — start with project-description files (`README`, `CLAUDE.md`, `synthesis.md`, `tape.yaml`), then any flagged content, then any additional material needed to name domain, audience, stage, and explicit goal. Token cost is not optimized; user-time is. If the agent has no file tools and the user pointed at a folder, it says so plainly and asks for files-in-chat or a description instead. It never invents file contents.
-
-**Step 2 — Confirm what was inferred.** After reading, the agent's next message is a confirmation: *"I see your project is [X] for [Y], focused on [Z]. Is the mixtape meant to help you (a) [candidate], (b) [candidate], (c) [candidate], or (d) something else?"* One turn, one confirmation. Option (d) is required. The agent never bakes inferred context into the JTBD silently.
-
-**Step 3 — Run a budgeted interview, if needed.** If the user shared no material, or if reading wasn't enough, the agent opens with a single batched message of two or three basic questions (domain, role, concrete activity), then descends the scope ladder one question at a time. Each follow-up walks the user from aspiration → big → little → micro. The agent stops asking when the next question wouldn't change the draft. Hard cap: five total questions, three typical.
-
-**Step 4 — Draft, critique, refine, emit.** The agent drafts the Job Story silently. Before emitting, it runs the draft through a six-test rubric: structural (all three slots present and non-empty), solution-free (no vendor / framework / tool named), single-scope (one job per slot), specific (not generic or aspirational), externally readable (a stranger could understand it without context), and slot hygiene (audience clauses live in the circumstance, not the motivation). If a test fails, the agent fixes the draft and re-checks. The rubric is never shown to the user. Output is one line — the Job Story, no preamble, no commentary, no quote marks, no code fence. If the user pushes back, the agent doesn't defend; it takes the correction, re-runs the rubric, and emits a revised statement in the same format.
-
-## Where it came from
-
-The prompt is the engineering output of a mixtape compiled specifically for this question. The mixtape lives at:
-
-```
-mixtapes/jtbd-master-prompt/
-├── MIXTAPE.md              # compiled master file
-├── tape.yaml               # the recipe
-├── synthesis.md            # the curator's framing
-├── sources/                # 32 extracted sources
-└── working/                # the curation trace
-```
-
-**Curator:** cmdux. **Compiled:** 2026-05-27. **Mode:** quick.
-
-Thirty-two sources span two literatures that don't usually meet: JTBD theory (Ulwick, Christensen, Klement, Kalbach, Moesta, the Intercom Job Story canon and its critics) and prompt engineering (Anthropic's prompting best practices, the meta-prompting literature, elicitation patterns for agentic AI, the evaluator-optimizer pattern, the persona-injection ablation studies). The synthesis bridges them: how do you design a system prompt that talks to a human and produces a tight JTBD sentence on demand?
-
-Six generative rules from that synthesis show up directly in the prompt:
-
-1. **Job Story format with three required slots.** The synthesis recommends the Intercom "When [circumstance], I want [motivation], so I can [outcome]" form over alternatives because the required slots fail structurally when missing — a sentence-shaped non-job ("Help me with healthcare marketing") can't survive the Job Story format's structural check, where it could survive a single-slot form.
-2. **Solution-free, single-scope, specific, externally readable** as the spine of the tightness rubric — those tests come from Ulwick's outcome-statement grammar via the SIVO clarity rubric, adapted to the Job Story slots.
-3. **The aspiration → big → little → micro scope ladder** as the structure of the descent interview — from User Interviews' UX field guide on hyper-specificity.
-4. **Evaluator-optimizer loop (draft → critique → refine)** as the internal generation pattern — from Anthropic's "Building Effective Agents" pattern taxonomy and the LLM self-critique prompting literature.
-5. **One question at a time, hard budget, stop when next question wouldn't change the draft** — from the active-questioning and elicitation literature on agentic AI.
-6. **No persona in the prompt** — from the Zheng et al. 2023 ablation showing persona injection doesn't improve task accuracy and optimal-persona prediction is no better than random.
-7. **Failure-mode-first engineering register** — from the Claude 4 system-prompt teardown and the prompt-engineering anti-patterns catalog. Production system prompts are lists of mistakes the model used to make; the JTBD prompt is shaped the same way.
-
-A few choices in the prompt deliberately diverge from the mixtape's center of gravity, and they're worth naming:
-
-- **No passing examples in the final prompt.** The synthesis recommends concrete examples as a teaching tool. We dropped them because passing examples carry an anchoring risk — the model copies surface features from the example domain. Failing examples teach a rule that generalizes; passing examples teach a style that doesn't. The rubric is doing the work passing examples normally would. The single passing example that does appear (the clinical Job Story for the diabetes case in the descent section) illustrates *the casual-language-to-Job-Story translation*, not the target shape itself.
-- **Quality over token economy in the read step.** Early drafts capped reads at "two or three sampled files." That cap is gone. If the user shared material, the agent reads enough to confidently characterize the project. Stopping condition is *confidence*, not file count.
-- **Single context-sharing question, not a multi-path router.** An earlier draft offered the user three explicit routing options (folder / files / skip) in a ~120-word message. That turned out to be friction solving for the wrong problem. The deployment scenario is narrower than the router assumed: this prompt is only ever used to create a fresh JTBD from scratch. Users don't paste pre-drafted JTBDs (the whole point is they don't have one), and the choice between "files" and "folder" is mechanical, not strategic. The single short question — *"Do you have any documents or project material I should look at first?"* — surfaces the affordance without forcing the user through a decision tree.
-
-### Historical note: the house form
-
-Earlier versions of Liner — and the first published version of this prompt — used a different JTBD form: *"Help me [verb] [object] [scope]."* That form matched the surface shape of every Liner artifact at the time (the methodology docs, the example mixtapes, the schema), so the prompt was designed to produce what Liner already consumed.
-
-The trade-off became clear once the prompt was used in practice. The house form has no required slots: a sentence like "Help me with healthcare marketing" satisfies the form template but is not a JTBD. That meant the qualitative rubric had to do all the work of catching topic-shaped non-jobs — a soft check rather than a hard one. The Job Story format has the same forgivingness against mush in its individual slots but fails structurally when a slot is empty, which raises the floor before the rubric runs.
-
-The format switch realigned the prompt with the original synthesis recommendation. The cost is a one-time migration of existing artifacts; the benefit is a structurally tighter floor on every future JTBD.
-
-## How to use it
-
-Three deployment paths, all using the same prompt:
-
-**Pure-chat (Claude.ai, ChatGPT, Cowork web).** User pastes the prompt block into a fresh chat. When the context-sharing question fires, the user can drop files into the chat or say they have no material. Folder paths aren't viable in this environment; the prompt handles that case gracefully.
-
-**Agent with filesystem access (Claude Code, Cowork desktop, Codex, the Liner TUI as a subprocess).** Both file attachments and folder paths are live. The user picks; the agent reads accordingly.
-
-**Embedded inside the `curating-mixtapes` skill.** Drop the prompt block into `cli-update-docs/SKILL.md` as the body of Phase 1 — Framing, replacing the current "Ask the user for the JTBD" paragraph. The skill's outer context provides Liner framing; this prompt handles JTBD elicitation. Filesystem access is the default in the skill's runtime.
-
-**As a TUI subprocess.** A future `liner jtbd <folder>` command could spawn this prompt with the folder path in context. The context-sharing question still fires — the user might want to add files or skip the folder — but the path is available if they want it.
-
-## Design choices worth understanding
-
-A few decisions in the prompt aren't obvious and have been pushed back on during design:
-
-**Why fire the context-sharing question unconditionally?** Capability detection is brittle: file tools may be advertised but broken, sandboxed, or scoped to a different path than the user expects. Silent inference of context is worse than no context. Asking once is one extra turn; getting it wrong is a wrong JTBD that propagates through every downstream phase. Asking respects user agency and removes a class of silent-failure bugs. The question is short — three sentences — to keep the friction low.
-
-**Why a hard question budget?** The most reliable failure mode for interview prompts is death by clarification — the model keeps asking because "one more question" feels safer than committing. A budget forces a draft. Five questions max, three typical. If the model finds itself drafting a fourth follow-up, the prompt instructs it to draft the JTBD instead.
-
-**Why no persona block?** Empirically (Zheng et al., 2023, 162 personas × 2,410 questions) persona injection doesn't improve task accuracy and optimal-persona prediction is no better than random. "You are an expert JTBD practitioner with twenty years of experience" buys hedging language, not skill. The prompt names the task instead.
-
-**Why failure modes before instructions?** Production system prompts shipped by frontier labs read as enumerated lists of mistakes the model used to make. That's the right register: the prompt prevents the five specific failures (solution baked in, conflated jobs, topic-as-JTBD, aspirational mush, death-by-questions) more than it teaches JTBD theory.
-
-**Why no passing examples (mostly)?** Asymmetric example design — failing examples teach a generalizable rule, passing examples anchor on style and domain. The one passing example in the prompt (the clinical Job Story for the diabetes case) appears only to demonstrate the casual-language-to-Job-Story translation, not the shape of the target output. If users in adjacent fields start pattern-matching on it, swap or strip it.
-
-**Why a slot hygiene check?** The first five rubric checks (structural, solution-free, single-scope, specific, externally readable) caught most failures in early use but consistently missed one: audience-scoping camped in the motivation slot. A draft like "I want to design a single-page site that explains the tool to people who already use AI" is technically one motivation, but the audience clause belongs in the circumstance. When audience drifts into the motivation, the circumstance reads thinner than the JTBD actually is, and the synthesis underneath misses signal it should have caught. Slot hygiene is the rule that promotes this from per-curator judgment to a generalizable check. It does not police mush, weak audience scoping, or product-positioning that doesn't earn its slot — those remain curator-level judgments and the qualitative rubric stays load-bearing.
-
-## What this prompt does NOT do
-
-- It does not produce a knowledge map. Phase 1 of curation wants both JTBD and knowledge map; this prompt produces only the JTBD. The knowledge map is the next move in the skill.
-- It does not produce sources, citations, or curator notes. Those are Phase 2 and Phase 4.
-- It does not produce a synthesis. Phase 6.
-- It does not validate the JTBD against a real mixtape. The rubric is necessary but not sufficient. The empirical test (Phase 8) is the only real validation.
-- It does not defend against adversarial users. Cooperative-user assumption is baked in. If the prompt ever ships in a context with hostile input (public web form, untrusted API), add a refusal clause.
-- It does not accept a pre-drafted JTBD as input. The deployment scenario is fresh JTBD creation from scratch; users with an existing draft don't need this prompt.
-
-## Known limits and watch items
-
-- **Anchoring risk on the process examples.** The descent section contains examples from clinical, engineering, and creative domains. These illustrate *the scope-ladder shape*, not target output, so the anchoring risk is weaker than it would be for passing JTBD examples — but it's nonzero. If users in those fields consistently produce ladder-shaped artifacts that don't fit their actual work, swap or strip them.
-- **The structural and slot-hygiene rubric checks are necessary, not sufficient.** Slot 1 catches *omitted* slots; slot 6 catches misplaced audience clauses. Neither catches mush, weak audience scoping, or product-positioning that doesn't earn its slot. A Job Story like "When I'm doing marketing, I want to do it well, so I can succeed" passes both structural checks and fails on the qualitative ones. The qualitative rubric stays load-bearing.
-- **Soft dependency on user calibration.** The prompt assumes the user can identify their most relevant material. Almost always true for someone curating a mixtape; less true for a first-time user. If you observe weak JTBDs from less-experienced users, the fix is a checklist of *kinds* of content that tend to be load-bearing (project briefs, requirements docs, customer research, prior synthesis attempts), not more rules in the prompt.
-- **Big-repo reads.** If a user points the agent at a very large folder, the "read enough to confidently characterize" rule may still under-sample the part of the repo that defines domain. The fix isn't a token cap; it's better signposting in the context-sharing question if you observe drift.
-
-## Related files
-
-- The prompt itself: [`JTBD-MASTER-PROMPT.md`](./JTBD-MASTER-PROMPT.md)
-- The format migration plan: [`JOB-STORY-MIGRATION.md`](./JOB-STORY-MIGRATION.md)
-- The source mixtape: [`mixtapes/jtbd-master-prompt/`](../mixtapes/jtbd-master-prompt/)
-  - Synthesis (the bridge between JTBD theory and prompt engineering): [`mixtapes/jtbd-master-prompt/synthesis.md`](../mixtapes/jtbd-master-prompt/synthesis.md)
-  - Tape recipe: [`mixtapes/jtbd-master-prompt/tape.yaml`](../mixtapes/jtbd-master-prompt/tape.yaml)
-  - 32 source extracts: [`mixtapes/jtbd-master-prompt/sources/`](../mixtapes/jtbd-master-prompt/sources/)
-- The Liner curation methodology that places this work in Phase 1: [`cli-update-docs/CURATION.md`](./CURATION.md)
-- The skill that will likely embed this prompt: [`cli-update-docs/SKILL.md`](./SKILL.md)
-- The mixtape format spec defining the `jtbd:` field the prompt's output lands in: [`cli-update-docs/MIXTAPE-FORMAT.md`](./MIXTAPE-FORMAT.md)
-- Project-level overview of Liner: [`LINER-MASTER.md`](./LINER-MASTER.md)