linersh 1.0.0 → 1.0.2

package/cli-update-docs/CURATION.md

@@ -1,290 +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 help an AI agent perform one hyper-specific task better than it could 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 reusable capability. Not the topic. The *specific thing a future AI agent should be able to do*.
-
-The user-facing prompt is:
-
-> What do you want this Liner to help your AI agent do?
-
-The user may answer in normal language. They do not need to provide source categories, research lanes, or a formal Job Story. Liner's job is to infer those from the desired capability, ask a few targeted follow-up questions only when the capability is under-specified, and then create a source-grounded resource that future AI sessions can load.
-
-Liner still derives an internal job-to-be-done because the downstream phases need a testable target. A Job Story is one useful internal shape: **"When [circumstance], I want [motivation], so I can [outcome]."** The user should not have to know or write this format. The AI may translate the capability into a Job Story silently, then expose the plain-language intent and research plan for review.
-
-"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 desired capability cannot be made hyper-specific, the mixtape will be unfocused. This is the single most common failure mode. "SEO" is a topic; "SEO keyword research for a mental-health startup specialized in brain surgery" is specific enough for Liner to infer research lanes such as search strategy, medical-content constraints, brain-surgery terminology, and Google guidance.
-
-Write a short Capability Brief alongside the internal JTBD. It should name:
-
-- what future AI sessions should be able to do,
-- what outputs or decisions the resource should support,
-- the research lanes Liner inferred,
-- source requirements and obvious exclusions,
-- runtime behavior for the future agent, including when to ask the user clarifying questions.
-
-Sketch a knowledge map alongside the Capability Brief and internal 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.
-
-Also write a capability brief and required source roles.
-
-The **capability brief** says what this mixtape should make a downstream AI agent better at. It is not a persona. It is the operational job the corpus must support.
-
-**Required source roles** name the kinds of evidence the corpus needs before it can be trusted. Each role should say why it matters, what good evidence looks like, and the minimum coverage needed. For a medical SEO mixtape, roles might include search-engine guidance, medical-topic authority, patient-language evidence, and compliance boundaries. For an art-direction mixtape, roles might include visual-analysis vocabulary, translation methods, high-craft examples, and critique language. The roles change with the JTBD; the requirement does not.
-
-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 and the required source roles. 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 an AI agent trying to [capability]?* AI is bad at recall and good at critique. Use it for the right thing.
-
-**Search by source role.** A knowledge-map section can look populated while a required evidence role is missing. Search directly for the role the source needs to play: canonical method, domain authority, applied example, boundary/risk, or whatever the Phase 1 source roles require.
-
-No fetching yet. This phase produces URLs and titles, not content.
-
-### Phase 3 — Fetching
-
-Pull content for every candidate into the cache. Transcripts, articles, PDFs, local files, and only then metadata when the content cannot be reached. 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 either readable content available for evaluation or an explicit failure state. Search snippets, titles, and URLs are not source evidence.
-
-### Phase 4 — Evaluation
-
-Read the fetched content and rate each candidate against the Capability Brief and internal JTBD. This is where keep/trim/drop decisions actually happen. Kept and trimmed sources must include `fetch_status`, `content_quality`, and at least two content-specific evidence bullets so the corpus can prove the decision came from content, not just URL plausibility.
-
-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
-
-Run the quality tests deliberately. This phase checks whether the corpus can actually support the future agent's task, not just whether it has plausible sources.
-
-**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 capability that's missing entirely — not just an individual source, but a whole way of thinking about the task? If yes, the framing was too narrow. Expand the knowledge map and revisit Phase 2.
-
-**The source-kind balance test.** Check the distribution of reference, principle, prescription, and example sources. A zero in any role is a decision, not an accident. Backfill or defend it.
-
-**The required source-role fit test.** Return to the roles from Phase 1. Does each role have fetched, readable, useful evidence? Is the evidence strong enough for the role, or merely adjacent? If a role is weak or absent, run a backfill pass, narrow the capability claim, or document the limitation and what custom source the curator should add.
-
-The framing-gap and source-role fit tests are the ones most curators skip. They are also the highest-leverage. Single-pass curation tends to produce mixtapes that are well-covered within one narrow framing. These tests catch what the first pass could not see.
-
-If a mixtape fails any of these tests, fix it before moving on when the fix is small enough for the quality phase. If the failure points to a wider source-role gap, write `working/05-operating-fit-audit.md` with `status: improvement_recommended`: name the missing role, explain why it matters, suggest search lanes, and list concrete custom sources the user could add if public research remains thin. Do not call the corpus ready with a limitation when the right next step is to run a focused improvement pass.
-
-### 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 to do something the mixtape's capability should support
-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 capability 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 capability brief, knowledge map, and source roles; 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 capability; 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 capability. 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.
-
-**The role-missing mixtape.** Every section has sources, but one required evidence role is absent. The corpus looks full while still failing the job. Fix by backfilling the role, narrowing the claim, or documenting the limitation.
-
----
-
-## 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
-- Filling knowledge-map sections while missing required source roles
-
-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/JTBD-MASTER-PROMPT-ABOUT.md

@@ -1,130 +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 `docs/curation-skill/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. That local source mixtape is archived at:
-
-```
-/Users/arturo/Documents/Projects/0-archive/liner-archive/2026-06-25-root-cleanup/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 `docs/curation-skill/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 current format spec: [`MIXTAPE-FORMAT.md`](./MIXTAPE-FORMAT.md)
-- The archived source mixtape: `/Users/arturo/Documents/Projects/0-archive/liner-archive/2026-06-25-root-cleanup/mixtapes/jtbd-master-prompt/`
-- The Liner curation methodology that places this work in Phase 1: [`CURATION.md`](./CURATION.md)
-- The skill that will likely embed this prompt: [`SKILL.md`](./SKILL.md)
-- The mixtape format spec defining the `jtbd:` field the prompt's output lands in: [`MIXTAPE-FORMAT.md`](./MIXTAPE-FORMAT.md)
-- Project-level overview of Liner: [`LINER-MASTER.md`](./LINER-MASTER.md)

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

@@ -1,147 +0,0 @@
-# JTBD Master Prompt
-
-A drop-in prompt that interviews a Liner user and emits one tight, hyper-specific Job Story — the kind that belongs in the `jtbd:` field of a `tape.yaml`. Paste it into any AI chat as the opening message, or load it as Phase 1 inside the `curating-mixtapes` skill. Its only output is the Job Story sentence; everything downstream (knowledge map, candidate discovery, evaluation, synthesis) is Liner's job, not this prompt's.
-
----
-
-## The prompt
-
-Copy everything between the `---BEGIN---` and `---END---` markers.
-
-```
----BEGIN---
-You run a focused interview that ends in exactly one sentence: a job-to-be-done (JTBD) statement for the `jtbd:` field of a Liner `tape.yaml`. That sentence drives every downstream Liner decision, so it has to be tight. Your only deliverable is that statement, on its own line.
-
-## What "tight" means
-
-The form: "When [circumstance], I want [motivation], so I can [outcome]."
-
-All three slots are required. The form is permissive on what fills them — a legal Job Story, a clinical Job Story, and an engineering Job Story share this shape but no vocabulary. The form's only structural guarantee is that no slot can be empty; the rubric below catches the rest.
-
-Failures to refuse:
-
-- "When I'm working in healthcare, I want to do healthcare marketing, so I can grow the business." — All slots filled but each is mush; circumstance and motivation both restate the topic.
-- "When I'm practicing law, I want to be a better lawyer, so I can serve clients well." — Motivation is aspiration, not a concrete job.
-- "When our database hits scale limits, I want to migrate to PostgreSQL using Prisma, so I can ship features faster." — Solution baked into the motivation.
-- "When I'm prepping a class, I want to design a curriculum and teach it, so I can finish the term." — Two motivations joined by "and."
-- "When I'm doing marketing, I want to do it the right way, so I can succeed." — Circumstance, motivation, and outcome are all undefined.
-
-## Hard rules
-
-- No vendor, framework, library, methodology, or tool name in any slot of the final statement.
-- No "and," comma, or slash joining two circumstances, two motivations, or two outcomes. If the user describes two, ask which one this mixtape is for.
-- A bare noun phrase ("mobile design," "contract law") is not a JTBD. A JTBD has a scoped circumstance, a concrete motivation, and a meaningful outcome.
-- Do not invent context. If you don't know the user's role, platform, deadline, or audience, ask.
-- Do not credentialize ("As an expert JTBD practitioner..."). Name the task instead.
-- Do not narrate, summarize, or restate the conversation.
-- Output the statement alone on its own line. No quotes, code fence, header, or commentary.
-- Hard cap: five questions across the entire interview. Three is typical. If you're about to ask a fourth follow-up, draft instead.
-
-## Step 0: Offer to read project material
-
-Your first reply is one short question, before any interview questions:
-
-> Before we begin, do you have any documents or project material I should look at first? If yes, drop them into this chat (or point me at a folder if I have filesystem access here). If not, just say so and we'll talk it through.
->
-> A few well-chosen files beat a full dump.
-
-This question does not count against the question budget.
-
-**If the user shares material:** Read it. Stop when you can name domain, audience, stage, and an explicit goal. Then go to confirmation (below).
-
-**If the user has no material to share:** Go straight to the interview protocol.
-
-**If the user points at a folder and you have no file tools:** Say so plainly and ask them to drop files into the chat or describe the project. Do not pretend you read something you couldn't.
-
-## Confirmation (after reading, if material was shared)
-
-One turn, one message:
-
-> 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?
-
-Candidates are casual-language scopings, not Job Stories yet — you translate at emit time. `(d)` is required. If the user picks it, ask one descent question and draft.
-
-If the user contradicts what you read, the user wins. Probe the contradiction once if it changes the circumstance, motivation, or outcome; otherwise accept and proceed.
-
-## Interview protocol
-
-Open with a single batched message asking only what you can't infer from material the user shared:
-
-1. What domain or topic is this mixtape about?
-2. Who are you in this work — what role or context shapes which sources count as canonical?
-3. What will you actually do with an AI that has this context — one concrete activity, not a vibe?
-
-Skip any of those that shared material already answered.
-
-After the batch, one question at a time, walking down the scope ladder. The user expresses each level in casual language; you translate the micro level into Job Story form at emit time. Three illustrative fields (substitute the user's actual field):
-
-- **Clinical:** "be a great doctor" → "communicate diagnoses well" → "explain new diagnoses to patients" → "explain a new Type 2 diabetes diagnosis to an adult with low health literacy at a first visit."
-- **Engineering:** "ship faster" → "reduce CI runtime" → "speed up the integration test suite" → "speed up the integration test suite for a Rails 7 monolith with 3,200 tests while keeping coverage above 85%."
-- **Creative:** "write better" → "improve my essays" → "structure long-form essays" → "structure 4,000-word tech essays for a developer audience reading on mobile."
-
-The corresponding final Job Story for the clinical example would be: "When I deliver a new Type 2 diabetes diagnosis to an adult with low health literacy at a first visit, I want to explain the condition and the immediate care plan, so the patient leaves able to describe what diabetes is and one thing they need to do this week."
-
-The JTBD is done when the micro level is single-circumstance, single-scope, concrete enough that a mixtape built against it could be measurably better than no mixtape.
-
-**Prefer multi-choice over free-form.** Offer 2–4 candidate scopings in casual language; the user picks or overrides.
-
-**Stop when the next question wouldn't change the draft.** After the second descent question, draft silently. Only ask another question if the draft fails the rubric *and* the fix requires user input you don't already have.
-
-## Internal rubric (silent)
-
-Before emitting, check the draft. If any fail, fix and re-check.
-
-1. **Structural.** "When [X], I want [Y], so I can [Z]" — all three slots present and non-empty.
-2. **Solution-free.** No tool, framework, vendor, library, methodology, or specific method named in any slot.
-3. **Single scope.** No "and"/comma/slash joining two circumstances, two motivations, or two outcomes. If a slot decomposes into two complete jobs when split, you had two.
-4. **Specific, not generic or aspirational.** Circumstance is scoped to a real situation, not "when I'm working." Motivation is a concrete action, not "be better at X." Outcome is meaningful, not "so I can succeed."
-5. **Externally readable.** A stranger who has never seen this project could read it and understand what's being asked. Strip "my app," "the team," "our process" unless enough scope makes them legible cold.
-6. **Slot hygiene.** Audience and situational context belong in the circumstance, not the motivation. The motivation describes the action the user is taking; the circumstance describes who it's for and the situation around it. If the draft reads "I want to [action] for [audience]" or "I want to [action] that [explains/serves/teaches] [audience]," move the audience clause into the circumstance and tighten the motivation to the action alone. Sequential clauses in the outcome ("install, then understand, then build") are not a violation — they're one composite outcome.
-
-## Emit
-
-One line. The Job Story. Alone. No preamble, no "Here's your JTBD," no quotes, no code fence.
-
-If the user pushes back, do not defend. Take the correction, re-run the rubric, emit a new statement in the same format.
----END---
-```
-
----
-
-## Why it's shaped this way
-
-A few choices that aren't obvious:
-
-**Job Story format, not Liner's older house form.** Earlier versions of Liner used "Help me [verb] [object] [scope]." That form was easy to write and matched existing Liner artifacts, but it had no required slots — "Help me with healthcare marketing" looks like the form but isn't a job. The Job Story format ("When [circumstance], I want [motivation], so I can [outcome]") fails structurally when any slot is missing, which raises the floor on what counts as a JTBD before the rubric even runs. This realigns with the recommendation in the mixtape's own synthesis.
-
-**The first question is always the context-sharing offer.** This prompt is only ever used for one purpose: to help a user create a fresh JTBD for a Liner mixtape from scratch. Users won't paste pre-drafted JTBDs (the whole point is they don't have one yet) and they may not think to attach material unprompted. The single context-sharing question puts the affordance in front of them once, then gets out of the way. Earlier drafts of this prompt had a longer routing question and multiple "fast paths" for pre-attached material; both turned out to be friction solving for scenarios that don't happen in this prompt's actual deployment.
-
-**Slot hygiene as a sixth rubric check.** The other rubric tests catch missing slots, solution leakage, multi-scope jobs, mush, and unreadable references. They miss a recurring quieter failure: audience-scoping camped in the motivation slot. "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 ("to people who already use AI") belongs in the circumstance. When audience drifts into the motivation, the circumstance gets thinner and the JTBD reads as less situated than it actually is. The sixth rubric check makes this generalizable rather than per-curator-judgment.
-
-**No persona block.** Recent empirical work on persona injection (Zheng et al., 162 personas / 2,410 questions) shows persona prompts don't improve task accuracy on average and that optimal-persona prediction is no better than random. Telling the model "you are an expert JTBD practitioner with twenty years of experience" buys nothing and costs a hedge in the output. The prompt names the task instead.
-
-**Failure modes listed 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 here — the prompt's job is to prevent the five specific failure modes (solution-baked-in, conflated jobs, topic-as-JTBD, aspirational mush, death-by-questions) more than it is to teach JTBD theory.
-
-**Hard question budget.** Five questions, three typical. The most common interview failure mode is death by clarification — the model keeps asking because "one more question" feels safer than committing. The budget forces a draft.
-
-**No rationale or knowledge map in the output.** This prompt has one job: produce the Job Story line. Anything else belongs to the next phase of curation, which Liner already runs.
-
-## How to use it
-
-The prompt's first move is always the same — ask the user whether they have project material to share, then either read what they hand over or interview them directly. What changes by environment is what counts as "shareable":
-
-**Pure chat (Claude.ai, ChatGPT, Cowork web).** Users paste the prompt block (between the BEGIN/END markers) into a fresh chat. They can drop files into the chat when the context-sharing question fires; folder paths aren't viable.
-
-**Agent with filesystem access (Claude Code, Cowork desktop, Codex, the Liner TUI as a subprocess).** Both file attachments and folder paths work. If the user gives a path, the agent reads from disk.
-
-**Inside the `curating-mixtapes` skill.** Drop the prompt block into `docs/curation-skill/SKILL.md` as the body of Phase 1 — Framing, replacing the current paragraph about asking the user for the JTBD. The skill's outer context handles Liner-specific framing; this prompt handles the Job Story elicitation. The skill runs in environments with full filesystem access.
-
-**Inside the TUI as a dedicated subprocess.** A `liner jtbd <folder>` command can spawn the agent with the folder path already in context. The agent still asks the context-sharing question — the user might want to add files or skip the folder — but the path is available if they want to use it.
-
-## Where it can still go wrong
-
-Three known soft spots worth knowing:
-
-- **Cooperative-user assumption.** The prompt has no defenses against a user trying to coax a JTBD that legitimizes a harmful product, or against prompt injection from pasted material. If you ever ship this in a context with hostile input, add a refusal clause.
-- **Asymmetric examples by design.** The prompt includes failing Job Story examples but no passing ones. Failing examples teach a rule (the failure mode generalizes the moment you read it); passing examples teach a style and anchor the model on whatever domains they're drawn from. The clinical example in the descent section illustrates *process shape*, not target output shape, which is a weaker anchor — but it's nonzero. If you observe users in adjacent fields pattern-matching on it, swap in two more descent examples from different fields, or strip the example entirely.
-- **Structural and slot-hygiene checks are necessary, not sufficient.** Slot 1 of the rubric only catches *omitted* slots, and slot 6 only catches misplaced audience clauses. They don't catch mush, weak audience scoping, or product-positioning that doesn't earn its slot — those remain curator-level judgments. The qualitative rubric stays load-bearing. The format and the structural checks raise the floor; they don't replace the rubric.