linersh 1.1.2 → 1.2.0

package/cli-update-docs/source-finding-tactics.md

@@ -1,224 +0,0 @@
-# Source-finding tactics
-
-Loaded by the `curating-mixtapes` skill at the start of Phase 2 (Candidate discovery).
-
-This file describes tactics that produce better candidates than generic search. When you reach Phase 2, work through the relevant tactics — not all of them for every mixtape, but enough that the candidate pool covers the knowledge map and required source roles from multiple angles.
-
-The goal of Phase 2 is recall, not precision. You're producing roughly two to four times the eventual kept count, but the real stop condition is coverage of the required source roles and capability-pattern lanes. You will cut in Phase 4. Casting wide here is the methodology working as designed.
-
----
-
-## 1. Follow the citations
-
-Pick one excellent source you already have. Find what *it* cites — the references, the linked sources, the "see also" pointers. Then open one of those and find what *it* cites. Three or four hops in, you'll find the canonical sources nobody links to anymore because everyone assumes you've read them.
-
-This tactic is the single highest-leverage move for discovering primary documents. It works against your popularity bias: cited-by-the-canon sources don't surface in keyword search, but they're what serious work in the field rests on.
-
-**How to apply:** Open the most credible source you have. Scan the references, footnotes, or "further reading" section. Note every source that's cited *and* recurs in another credible source's references. Recurrence across multiple credible sources is the signal — it's how you find the references nobody links anymore.
-
----
-
-## 2. Reverse-engineer experts' reading lists
-
-Many domain experts publish their own reading lists or syllabi. These already encode someone else's curation work. Use them.
-
-**Where to look:** Notion (search "site:notion.so reading list <topic>"), GitHub (`awesome-<topic>` repositories, individual `README.md` files in personal repos), Are.na (channels — Are.na in particular is underused for this), personal blogs, course-instructor pages.
-
-Are.na deserves a specific note: it's a network designed for visual and textual reference-collecting. Practitioners use it to curate the kind of sources that don't make it into mainstream publications. Constrain a search with "site:are.na <topic>" and look for channels related to your JTBD.
-
-**How to apply:** Find three to five experts in the domain. Search each one's name plus "reading list" or "syllabus" or "references." Catalog what they recommend. Cross-reference with the candidates already on your long-list — overlaps are strong signal; uniques are leads.
-
----
-
-## 3. Mine course syllabi
-
-University courses, bootcamp curricula, and serious online courses have already done curation work for their domain. A well-designed syllabus is a curated reading list optimized for learning. Use them.
-
-**Productive queries:**
-
-- `"<topic> syllabus" filetype:pdf`
-- `"course readings" <topic>`
-- `<topic> "required reading"`
-- University course catalogs for the relevant department
-
-**How to apply:** Find two to three syllabi on your topic. Note the readings that appear across multiple syllabi — those are the canonical pieces. Note the readings that appear once but are written by people you recognize — those are the practitioner-credible additions.
-
-Course syllabi skew toward foundations. They're best for the early-section knowledge-map buckets. Recent practitioner work is rarely on them.
-
----
-
-## 4. Find who experts cite
-
-Pick three to five acknowledged practitioners in your domain. Look at *their* references — bibliographies, acknowledgments, who they cite in their own writing. The overlap across these experts is your shortlist.
-
-This tactic is structurally similar to citation-chasing (#1), but starts from people rather than from sources. Use it when you have a clear sense of who the credible practitioners are but no clear sense of which of their works is canonical.
-
-**How to apply:** Identify three to five practitioners credible in the domain. Open their most recent significant work. Note the sources they cite. Open the sources cited by two or more practitioners. Those are your high-priority candidates.
-
----
-
-## 5. Conference proceedings
-
-Going through three years of a specific conference is more efficient than topic-by-topic search. The conference's curation has already filtered for credibility and substance.
-
-**How to apply:** Identify one or two conferences serious in the domain. Open their proceedings, talk lists, or YouTube channels for the last three years. Skim titles and abstracts. Flag any talk whose abstract addresses a knowledge-map section.
-
-Conference talks vary widely in density. The same talk reposted across multiple conferences is one signal of substance. Talks from speakers who are also cited by other practitioners (tactic #4) are another.
-
----
-
-## 6. Ask the AI to find gaps, not sources
-
-Once you have a candidate list, stop searching and ask: *what's missing from this collection for someone trying to [JTBD]?*
-
-AI is bad at recall — at remembering and surfacing sources you don't know about. AI is good at critique — at looking at a list and noticing structural gaps. Use it for the right thing.
-
-**How to apply:** Show the candidate list (titles and one-line rationales) along with the JTBD and knowledge map. Ask explicitly: "What perspective is missing? What discipline is underrepresented? What kind of source is this list short on?" Then go find sources to fill the gaps named.
-
-This tactic is structurally related to the framing-gap test in Phase 5, but earlier and lower-stakes. Doing it in Phase 2 is cheaper than discovering the gap in Phase 5 and having to backtrack.
-
----
-
-## 7. Search for the core action and the curator anchors
-
-A good candidate list is not just "sources about the topic." It must contain
-sources that help the consuming AI do the job.
-
-Start by extracting the JTBD's core action. Examples:
-
-- "translate moodboards into UI"
-- "turn bug reports into reproduction steps"
-- "write grant narratives from research evidence"
-
-Then search for candidate URLs that might directly teach, demonstrate, or argue
-for that action. Bridge candidates are allowed, but they cannot carry the corpus
-by themselves. For a moodboard-to-interface mixtape, CSS layout, design tokens,
-and design systems are bridge leads: useful after a direction exists, but not
-enough to teach how to read images, extract mood, or create a new interface
-artifact. The keep/drop decision still happens only after the content is fetched
-and read.
-
-When the curator names a person, studio, product, software tool, YouTube
-channel, or site they like, deepen the anchor. Search for their case studies,
-interviews, talks, process notes, docs, essays, videos, and worked examples.
-Do not stop at the homepage, gallery index, or crawler metadata unless that is
-the only readable evidence available. If it is only a pointer, say so in the
-candidate reason.
-
-For visual-output jobs, deliberately search for visual and worked-example
-evidence: image-heavy case studies, moodboard breakdowns, design rationale,
-portfolio projects with process, talks, and videos. A source list made mostly
-of UX primers, CSS references, and design-system docs is probably under-serving
-the job even if every knowledge-map section has a source.
-
----
-
-## 8. Fill required source roles, not just sections
-
-The Capability Brief should name **Required source roles**: the jobs the corpus
-needs sources to perform for the future AI. These are not the same as source
-`kind` (`reference / principle / prescription / example`) and not the same as
-knowledge-map sections.
-
-Examples:
-
-- "core-action method" — sources that teach the exact action the agent must do
-- "worked examples / case studies" — sources that show good output, process, or taste
-- "domain authority" — primary/official sources the agent can cite for accuracy
-- "implementation constraints" — specs, APIs, platform docs, safety limits, or production rules
-- "critique / validation" — sources that help judge whether output is good
-- "dissent / alternate stance" — sources that prevent one-frame bias
-- "domain data" — keyword data, epidemiology, market signals, legal text, or other evidence specific to the niche
-
-When you build the long-list, make sure every required role has candidates. A
-populated section is not enough if a required role is thin. For a visual-output
-mixtape, two dozen UX/design-system articles do not substitute for worked
-visual/craft examples with rationale. For a medical SEO mixtape, SEO practice
-articles do not substitute for authoritative medical sources and domain-specific
-keyword or patient-language evidence.
-
-**How to apply:** For each required source role, search until you have 3–6
-plausible candidates or until it is clear public sources are thin. In the
-candidate reason, name the role the source might satisfy. If you cannot find
-credible candidates for a required role, write a "Role gaps" note in
-`working/02-candidate-longlist.md` so Quality can recommend a focused
-improvement pass instead of quietly accepting weak coverage.
-
-Candidate count should fall out of the role plan:
-
-- Narrow, single-domain projects may need fewer than 20 candidates.
-- Ordinary projects usually land around 20–35 candidates.
-- Broad, multi-domain, or `reference-translation` projects may need 40–60
-  candidates because each source domain and translation lane needs its own
-  candidate pool.
-
-Do not pad the list to hit a number. Do not stop at a number when a material
-role is still empty. Stop when every required role has credible candidates, the
-knowledge map is covered, and any capability-pattern lanes named in Phase 1 have
-enough evidence to evaluate.
-
-Good candidate notes should say which role the source might serve:
-
-- `source role: canonical method` — teaches the process the AI should follow
-- `source role: domain authority` — grounds claims in a credible source
-- `source role: applied example` — shows what good looks like in context
-- `source role: boundary / risk` — prevents harmful or misleading output
-
----
-
-## 9. Build a source ecology for reference-translation jobs
-
-Some mixtapes are not just about a topic. They ask a future agent to read inputs
-from one world and turn them into outputs in another. Common examples:
-
-- images, moodboards, art direction, visual references, or style examples into a
-  product/interface brief
-- screenshots, bug reports, logs, or user complaints into engineering actions
-- research evidence, interview notes, or case studies into a narrative or plan
-
-These are **reference-translation** capabilities. Their candidate pool needs a
-source ecology, not a stack of sources from the final output medium.
-
-For visual/reference work, search at least these lanes:
-
-- **Input/reference-domain interpretation:** how practitioners read the source
-  worlds themselves, such as art, photography, architecture, interiors, posters,
-  editorial design, fashion, packaging, sports/media identity, film, or product
-  imagery.
-- **Translation methods:** sources that show how observed qualities become new
-  decisions: design-language extraction, style tiles, creative direction,
-  case-study rationale, annotated redesigns, or critique.
-- **Target-output constraints:** the platform/output realities that the final
-  work must survive, such as web responsiveness, accessibility, motion safety,
-  design systems, typography, or implementation mechanics.
-- **Caller handoff language:** brief formats, vocabulary, do/don't lists,
-  validation checks, and clarification patterns that make the result executable
-  by another designer, engineer, or AI agent.
-
-For an art-direction-to-web mixtape, CSS references, design-token specs, and
-accessibility docs are valuable bridge sources. They are not substitutes for
-visual-culture sources that teach the agent how to look, compare, interpret, and
-translate. A candidate list made mostly of web-craft sources should include a
-"Role gaps" note and keep searching for the missing input/reference domains.
-
-**How to apply:** Before writing `working/02-candidate-longlist.md`, add a short
-"Reference-translation source ecology" note to your own scratchpad or the
-long-list: target output medium, input/reference domains represented, translation
-method candidates, handoff candidates, and bridge/constraint candidates. If the
-input/reference domains are thin, search those domains directly instead of doing
-another generic target-output search. Do not stop at the ordinary 20–35 candidate
-range if the ecology is still missing a source world the future agent must learn
-to interpret.
-
----
-
-## What not to do
-
-- **Don't rely on generic search alone.** The first page of search results is what your audience could also find. The point of curation is to surface what they couldn't.
-- **Don't accept candidates without verifying URLs.** AI hallucinates plausible-looking URLs. Web-fetch every URL before it goes on the long-list. A 404 candidate is worse than a missing one.
-- **Don't filter at Phase 2.** That's Phase 4's job. If a source might be useful, it goes on the long-list. Quality decisions come after fetching and reading. A URL is a lead, not evidence that the content is any good.
-- **Don't over-research one section while leaving others empty.** Walk the knowledge map. Each section should have a reasonable candidate pool before you go deep on any one section.
-- **Don't let adjacency satisfy the JTBD.** A CSS reference is not an art-direction source just because the final artifact is HTML. A process article is not a writing source just because the writer needs a process. Label these as bridge candidates unless they directly teach the core action.
-- **Don't collapse reference-translation work into the output medium.** If the future agent must translate paintings, photos, architecture, sports identity, or moodboards into a product direction, the candidate pool needs sources from those source worlds and from the translation move. Output-medium craft docs are necessary constraints, not the whole corpus.
-- **Don't let "not absent" pass a required role.** If a required role is material to the future AI's job, thin coverage should trigger backfill or an improvement-pass recommendation.
-- **Don't treat source roles as decorative.** A section can look populated while a required evidence role is absent. That is still a corpus gap.

package/cli-update-docs/source-quality-hierarchy.md

@@ -1,209 +0,0 @@
-# Source-quality hierarchy
-
-Loaded by the `curating-mixtapes` skill at the start of Phase 4 (Evaluation).
-
-This file describes how to rank sources, what to avoid, and the patterns to watch for when deciding keep / trim / drop. Apply it after you've fetched every candidate in Phase 3 and before you write `working/03-evaluation.yaml`.
-
-The goal of Phase 4 is honest assessment against the JTBD. Not breadth. Not completeness. Not even fairness to every source. *Does this source help the consuming AI do the JTBD better?* If yes, keep it. If partially, trim it. If no, drop it.
-
-A URL is only a lead. The source is the readable content. Do not keep or trim a candidate from its URL, title, search snippet, crawler metadata, or your memory of the source. Keep/trim decisions require source evidence.
-
----
-
-## Source-quality hierarchy
-
-Roughly in order of preference. This is not a strict ranking — context matters — but it's the order to default to when comparing sources of similar topical relevance.
-
-### 1. Canonical references
-
-Specs, standards, official platform docs, RFC documents. The primary source for whatever the topic is.
-
-Examples by domain: Apple Human Interface Guidelines, Material Design specs, W3C standards, IETF RFCs, language specifications, official API documentation, government regulatory documents.
-
-**Always include the primary source if one exists.** No piece of commentary on a spec is a substitute for the spec itself. The AI synthesizes better from the primary document than from anyone's interpretation of it.
-
-### 2. Practitioner deep-dives from people who built things
-
-Engineers, designers, and operators at credible companies writing about specific decisions they made. Concrete, battle-tested, often with consequences described honestly. The opposite of motivational content.
-
-Hallmarks: a specific decision is named, the trade-offs are named, the outcome is described (including when the outcome was bad). The post-mortem genre is the canonical form.
-
-### 3. Conference talks from credible speakers
-
-Pre-filtered by the conference's curation. A talk that made it onto a credible conference's main track has already passed at least one quality gate. Better baseline than random video search.
-
-Two notes: (a) talk transcripts are lower-density than articles — assume more skim, less detail. (b) Same talk reposted at multiple conferences indicates substance; keep the longest cut and drop the duplicates.
-
-### 4. Book chapters
-
-Specific chapters or excerpts, not whole books. A mixtape isn't a book club — the consuming AI doesn't need 300 pages on a topic when 30 will do. Link to the chapter or include the excerpt.
-
-Books are particularly valuable for foundational concepts and frameworks that take a chapter to develop. They're less valuable for recent specifics, which change faster than books update.
-
-### 5. Long-form interviews with practitioners
-
-Useful when you can cite a specific episode for a specific point — "Episode 47, the section on incident response, 18 minutes in." Less useful as a general "this practitioner is interesting" reference.
-
-Interview transcripts are conversational and lower-density than written work. They earn their place when the practitioner says something in the interview they haven't written down anywhere else.
-
-### 6. Academic papers when relevant
-
-Often underrepresented in design and engineering mixtapes because the field skews toward practitioner blogs. When a question is genuinely empirical or has been studied formally, the paper beats any number of blog posts. Don't skip them by default just because the format is intimidating.
-
----
-
-## What to avoid
-
-Source types that consistently produce low-value mixtapes. Drop these unless a specific exception applies.
-
-- **Listicles ("10 tips for...", "7 things every X should know").** Optimized for clicks, not depth. Almost always shallow despite specificity in the title.
-- **AI-generated content.** Now widespread, often subtly wrong, frequently fluent enough to mislead. Detection is imperfect but the tells are: generic phrasing, no specific examples or named cases, no opinionated stance, suspiciously even coverage across sub-topics.
-- **Twitter / X threads as primary sources.** Real expertise sometimes lives on Twitter, but threads are usually a teaser for longer-form work elsewhere. If a thread is the primary source, look for the article it was excerpted from. If there isn't one, ask whether a thread really earns a place in the corpus.
-- **Vendor blog posts with promotional angles.** Even when the technical content is good, the promotional framing distorts the analysis. Use as background, not as primary references.
-- **Most TED-style talks.** Optimized for narrative, emotional resonance, and applause moments. Low density of transferable content per minute. Exceptions exist but are rare.
-- **"Ultimate guides," "complete guides," "everything you need to know."** The promise in the title is almost never met. Treat as a yellow flag.
-
----
-
-## Decision rubric
-
-For each fetched source, decide one of: kept, trim, dropped. Rate kept and trim sources 1–5.
-
-- **Keep (4–5).** Strong fit with JTBD. Canonical, distinctive, or load-bearing for a knowledge-map section that would otherwise be empty. The AI's downstream output is clearly better with this source than without it.
-- **Trim (3).** Real content but selective. Worth including with a curator note flagging what to read and what to skip. Trim is not "kept with reservations" — it's "kept *because* the note tells the consuming AI how to use this source." The note is doing real work.
-- **Drop (1–2).** Tangential, generic, low-density, or redundant with stronger sources already kept. Drop without guilt. The cost of dropping a marginal source is low; the cost of keeping it is higher than it looks because it dilutes the corpus.
-
-**Rating calibration.** A 5 is "this source alone makes the mixtape meaningfully more useful." A 4 is "this source clearly belongs and pulls weight." A 3 is "this source belongs only with selective framing in the note." A 2 is "this source duplicates a stronger one or has shallow content." A 1 is "this source actively makes the corpus worse if included."
-
-If you find yourself rating most sources 4–5, you're under-discriminating. The point of evaluation is to discriminate.
-
-## Evidence fields
-
-Every kept or trimmed source must include these fields in `working/03-evaluation.yaml`:
-
-- `fetch_status: readable | partial` — `readable` means the substantive article, transcript, PDF body, or local content was retrieved. `partial` means enough real source content was retrieved to judge, such as an abstract plus substantial excerpt.
-- `content_quality: high | medium` — `high` means dense, distinctive, and directly useful; `medium` means useful but selective. If the content is shallow, generic, AI-generated, SEO filler, a homepage/gallery without rationale, or a low-density transcript, drop it.
-- `evidence:` — at least two bullets naming source-specific claims, examples, sections, methods, transcript moments, or limitations actually seen in the content.
-
-`metadata_only` and `unavailable` candidates must be dropped. They can remain in the evaluation file as evaluated candidates, but they must not enter `tape.yaml` as normal corpus sources.
-
----
-
-## JTBD-fit labels
-
-Every kept or trimmed source must also get a `jtbd_fit` label. This prevents
-topic adjacency from passing as source quality.
-
-- **direct** — the source teaches, demonstrates, or argues for the core action
-  in the JTBD.
-- **bridge** — the source helps execute the result after the core decision is
-  made: implementation mechanics, tokens, layout, process, API references, or
-  operational constraints.
-- **background** — broad vocabulary, primer, historical context, or generic
-  orientation.
-
-Bridge sources are valuable, but they are not the same as direct fit. If the job
-is "turn moodboards into HTML interface concepts," then a moodboard analysis
-method, a studio case study with rationale, or a talk on translating visual
-references can be direct. A CSS layout guide, token spec, or design critique
-process is a bridge unless it specifically teaches the translation move.
-
-For a `reference-translation` capability, use an even stricter direct-fit test:
-the source must help the future agent interpret the input/reference domain or
-demonstrate the translation from reference qualities into target-output
-decisions. Target-medium mechanics, accessibility standards, design-token
-formats, style-guide infrastructure, and implementation docs are usually bridge
-sources. They are important, but they cannot carry the core action alone.
-
-Background sources should rarely be marked required. A kept background source
-needs a narrow note explaining why its vocabulary or context is worth carrying.
-
-If a knowledge-map section contains only `bridge` or `background` sources, mark
-that as weak coverage in the rationale or quality report and backfill a direct
-source if the section is central to the JTBD.
-
-Quality also checks source roles at the corpus level. `reference / principle /
-prescription / example` is only the generic kind distribution; some projects
-need more specific roles. A visual art-director corpus may need high-craft case
-studies and worked image-to-interface translations. A medical SEO corpus may
-need clinical authority, search-intent evidence, and Google guidance. If those
-role-specific sources are missing, write an operating-fit audit and recommend a
-focused improvement pass instead of calling the corpus ready with a limitation.
-
----
-
-## Bounded fetch fallback
-
-Phase 4 should read enough to make honest decisions, but it must not stall on
-unavailable content. For each candidate, try one direct fetch/read. If that
-fails, make at most one recovery attempt: alternate transcript source, search
-result, mirror, metadata page, or equivalent.
-
-After two failed retrieval attempts total, stop searching for that candidate and
-evaluate from verified metadata, the Phase 2 reason, and any partial content you
-have. Usually that means `dropped`. If you have enough partial content to judge,
-set `fetch_status: partial` and write the evidence bullets. If you only have
-metadata, set the decision to `dropped`; the rationale can say the candidate
-looked promising but was metadata-only. Every candidate still gets a decision in
-`working/03-evaluation.yaml`; no source may keep the phase open indefinitely.
-
----
-
-## Patterns to watch for
-
-These are the recurring failure modes during evaluation. Each one is a moment where a source seems worth keeping but isn't.
-
-### Redundancy
-
-Two sources making the same point with similar examples. Keep the stronger one; drop the other. Two sources covering the same ground from different angles is not redundancy — it's coverage. The test is whether the AI would generate meaningfully different output from one vs. both. If not, redundant.
-
-### The duplicate trap
-
-Same talk reposted at different conferences. Same article republished on different sites. Same interview transcribed by multiple outlets. Keep one — usually the longest, most-cited, or earliest-published version. Drop the rest.
-
-### Framework boilerplate masquerading as design content
-
-Common with implementation tutorials. The video or article uses design vocabulary ("usability," "user experience," "accessibility") but teaches no transferable principles — it's a walkthrough of how to use a specific framework's API.
-
-Drop unless the source encodes a genuinely transferable pattern. A Ratatui tutorial that happens to mention layout principles is a Ratatui tutorial. A Ratatui tutorial that articulates the immediate-mode rendering principle and shows why it matters for terminal UI architecture is a design source.
-
-### The rescue move
-
-A source flagged as "low-value" during candidate discovery (Phase 2) sometimes turns out to be the only one that addresses a specific gap once you've actually read every candidate. If a low-priority source uniquely covers a knowledge-map section that would otherwise be empty or thin, rescue it. Mark the decision and the rationale clearly.
-
-### Author overrepresentation
-
-Three of five sources in a section are by the same author. This narrows perspective and reduces the AI's ability to synthesize across views. Keep the single strongest piece by that author; replace the others with sources by different practitioners. The exception: if the author has genuinely written the canonical work in multiple sub-areas, and no other practitioner has equivalent work, keeping multiple pieces is justified — but you should be able to defend it.
-
-### Recency without substance
-
-Recent does not mean better. A 2024 article that summarizes well-known points is weaker than a 2018 article that originated them. Don't auto-prefer recent. Don't auto-discount old. Apply the same JTBD-fit test regardless of publication date.
-
----
-
-## Output: `working/03-evaluation.yaml`
-
-Write every candidate's decision, regardless of whether it was kept or dropped. The dropped decisions matter — they're how the working notes show that evaluation actually happened.
-
-For large candidate sets, write decisions incrementally under `working/evaluation-decisions/` as section-sized YAML fragments. Use names like `01-foundations.yaml` and keep each fragment small enough to inspect. Liner assembles those fragments into `working/03-evaluation.yaml` in the original longlist order, so the fragment files are the durable work surface and `03-evaluation.yaml` is the canonical assembled artifact.
-
-```yaml
-candidates:
-  - url: https://example.com/source
-    title: Source title
-    decision: kept            # kept | trim | dropped
-    rating: 5                 # 1-5; required for kept and trim
-    jtbd_fit: direct          # direct | bridge | background
-    fetch_status: readable    # readable | partial; metadata_only/unavailable are dropped
-    content_quality: high     # high | medium; low is dropped
-    evidence:
-      - Specific claim or example found in the readable source content.
-      - Specific method, constraint, result, or limitation found in the content.
-    section: foundations
-    rationale: One-sentence reason this decision was made.
-    note: >
-      Role: Why this source belongs in the corpus. Value: What it contributes
-      to the job-to-be-done. Limitations: What the source cannot prove.
-```
-
-For dropped sources, the rationale should name *why* dropped — "duplicates Source 4," "shallow listicle," "AI-generated," "off-topic relative to JTBD." Generic "low quality" is not useful. Be specific.

package/cli-update-docs/synthesis-guidance.md

@@ -1,151 +0,0 @@
-# Synthesis guidance
-
-Loaded by the `curating-mixtapes` skill at the start of Phase 6 (Synthesis).
-
-This file describes how to draft `synthesis.md`. Apply it after Phase 5's quality checks have passed and the keep-list is locked. The synthesis is the most personal artifact in the mixtape and the one with the largest effect on downstream AI output. Don't shortcut it.
-
----
-
-## What the synthesis is
-
-The synthesis is the curator's distilled understanding of the domain expressed as continuous prose. It lives at the top of the compiled `MIXTAPE.md` and is the first thing the consuming AI reads.
-
-Without a synthesis, the AI gets a list of sources and curator notes. It has to construct its own framing of the domain from those pieces, which dilutes the curator's view.
-
-With a synthesis, the AI gets the curator's framing of the entire domain *before* it sees any source. The synthesis shapes how the AI reads everything that follows. This is the largest single lever for changing downstream AI output, and why the synthesis is required, not optional.
-
-Length: **800–2000 words.** Shorter for narrow topics; longer for broader ones. If you find yourself below 600 words, the synthesis is probably too thin. If you're above 2500, the synthesis is doing work the sources should be doing.
-
----
-
-## What goes in
-
-Six kinds of content earn their place in the synthesis.
-
-### Principles or framework
-
-The conceptual structure the curator sees in the domain. Not a definition list — a framework. "Good CLI design rests on four pillars: predictable command shape, humane errors, useful defaults, and machine-readable output." That framework, once articulated, shapes how the AI reads every source in the corpus.
-
-### Generative rules
-
-The rules the consuming AI should apply when it is making decisions with the mixtape. Include a `## Generative rules` section with about five imperatives. These are not summaries of sources; they are portable constraints the AI can carry into new work.
-
-Example: "Channel discipline: stdout is for data, stderr is for humans, and exit codes mean what they say." A rule like this resolves dozens of downstream questions without the AI needing to re-open every source.
-
-### Stances this corpus takes
-
-The opinionated positions the mixtape wants to preserve. Include a `## Stances this corpus takes` section that names what the corpus leans toward, what it resists, and where a dissenting source should temper the rule.
-
-This is different from the contested-questions section. Contested questions name the debate; stances state the operating answer this mixtape chooses for its JTBD.
-
-### Contested questions
-
-Where credible practitioners disagree, name the disagreement and where the curator stands. "There's an ongoing argument about whether CLIs should mirror existing tool conventions or break them deliberately when the underlying behaviour differs. This mixtape leans toward mirroring; sources 7 and 12 represent the dissenting view."
-
-Contested questions are gold for downstream AI output. They give the AI permission to represent the domain as contested rather than collapsing it into one answer.
-
-### Distinctions between concepts that get confused
-
-Where the domain has terms or concepts that get used interchangeably but shouldn't, draw the line clearly. "A *wizard* and a *form* are not the same thing. A form collects fields. A wizard collects fields *in a specific order, one at a time, with the option to navigate back*. The distinction matters because [...]."
-
-These distinctions are what an AI without the synthesis would have to infer from context. With the synthesis, they're explicit and load-bearing.
-
-### When to use the mixtape and when to look elsewhere
-
-A short paragraph at the end: what kinds of questions this mixtape is meant to help with, and what kinds it isn't. This is honest about the corpus's scope. "This mixtape is calibrated for designing CLIs that humans will use interactively. It's less useful for non-interactive CI/CD scripts or for shell-script ergonomics — those are adjacent topics with different conventions."
-
----
-
-## What doesn't go in
-
-Content that looks like it belongs in the synthesis but doesn't.
-
-### Source-by-source recap
-
-"Source 1 argues X. Source 2 argues Y. Source 3 builds on Source 1 to argue Z." This is what a literature review does for an academic paper. The mixtape doesn't need it — the source index handles that role, and the consuming AI will read individual sources when it needs the specifics.
-
-If the synthesis is recapping sources, the curator hasn't actually synthesized yet. Force the harder question: what does the curator think about the *domain*, given all these sources?
-
-### Generic introductions
-
-"Mobile design is the practice of designing applications for mobile devices, including smartphones and tablets, which have specific constraints around screen size, input methods, and connectivity." This is what the AI already knows. The synthesis isn't a Wikipedia stub. Start where the AI's training data ends.
-
-### Tutorial content
-
-"To design a good CLI, first identify your audience, then decide on a command structure, then..." This is how-to writing, not synthesis. The synthesis is *what the curator thinks about the domain*, not *how to do the work*.
-
-### Cheerleading or motivation
-
-"Good CLI design matters more than ever in an age of..." Cut. The AI doesn't need motivation. The curator's enthusiasm is irrelevant to the synthesis's job.
-
----
-
-## Structure
-
-A typical synthesis runs:
-
-1. **Opening framing** (1–2 paragraphs). What this domain is fundamentally about. The frame the curator uses to organize their understanding. Not a definition — a stance.
-2. **The framework or principles** (2–4 paragraphs). The structure the curator sees. Named, not just described.
-3. **Generative rules** (`## Generative rules`, about five imperatives). The small set of rules the consuming AI should remember and apply.
-4. **Stances this corpus takes** (`## Stances this corpus takes`, 1–3 paragraphs or bullets). The opinionated positions and trade-offs this mixtape adopts.
-5. **Contested questions** (1–3 paragraphs). Where credible practitioners disagree. Where the curator stands.
-6. **Important distinctions** (1–2 paragraphs). Concepts the AI is likely to conflate without correction.
-7. **Scope and limits** (1 short paragraph). What this mixtape covers and what it doesn't.
-
-This is a default. Vary it when the topic warrants — some domains lead with contested questions, some with distinctions, some with a different opening move. The structure serves the content.
-
----
-
-## Voice and stance
-
-The synthesis is written in the curator's voice. First-person is fine. Strong stances are fine — preferred, actually. The AI synthesizes better from a confident framing than from a hedged one.
-
-"I think the most important distinction in CLI design is..." is better than "Many practitioners consider one of the important distinctions to be..." The first is a stance the AI can engage with; the second is mush.
-
-This doesn't mean overconfidence. Hedging is appropriate where the curator is genuinely uncertain. But default to stance. Mush in the synthesis produces mush in downstream output.
-
----
-
-## Quick mode vs. methodology mode
-
-**Quick mode.** The AI drafts the synthesis. Apply this guidance during drafting. Show the curator the draft. Default is "looks good, save it." The curator lightly edits if they want.
-
-The risk in quick mode is that AI-drafted synthesis drifts toward source-by-source recap because that's the easier output shape. Resist this actively. The AI's draft should already be a real synthesis, not a placeholder that says "the curator will rewrite this."
-
-**Methodology mode.** The AI drafts a starting point. Expect the curator to rewrite it substantially in their own voice. The methodology-mode synthesis is the curator's voice on the domain — AI-drafted starting points with light edits don't meet the bar.
-
-Library contributions require methodology-mode synthesis. A synthesis that reads as AI-drafted is a signal the mixtape is quick-mode in methodology-mode clothing. The reviewers will catch it.
-
----
-
-## A failure mode worth naming
-
-The most common synthesis failure is one I'll call **synthesis-as-recap.**
-
-An AI drafting a synthesis gravitates toward describing what each source says, because that's the immediately available material in context. It produces something that reads like a research summary: "Sources 1, 4, and 9 argue X. Sources 2 and 6 take a different view, arguing Y. Source 7 offers a synthesis of both positions."
-
-This is not a synthesis. It's a recap. The consuming AI can produce its own recap from the source list; what it can't produce is the curator's framing of the domain.
-
-The fix: stop describing sources, start describing the domain. The synthesis should be readable as a coherent essay on the domain by someone who happens to have read all these sources — not as a tour of the corpus.
-
-If the synthesis names source numbers ("Source 1 argues..."), it's probably synthesis-as-recap. Real synthesis names ideas, not sources. The source index handles attribution; the synthesis handles framing.
-
----
-
-## Worked examples
-
-Good synthesis shape:
-
-> This corpus treats onboarding as a trust-building sequence, not as a checklist. The useful question is not "which screens does the user see?" but "what does each step prove before asking for the next commitment?" Sources disagree on how much explanation belongs up front, but they converge on one rule: every prompt should reduce uncertainty before it increases work.
-
-Bad synthesis-as-recap shape:
-
-> Source 1 explains onboarding screens. Source 2 covers empty states. Source 3 discusses progressive disclosure. Together, these sources show that onboarding is important.
-
----
-
-## Output: `synthesis.md`
-
-Plain markdown. No front matter. Begins with a top-level heading that matches the mixtape title (e.g., `# Mobile Design Foundations — Synthesis`). The full file gets included verbatim at the top of `MIXTAPE.md` by `liner compile`.
-
-Write the synthesis to `synthesis.md` in the corpus folder (`mixtape/synthesis.md` in v2 projects). Show the curator the result before declaring Phase 6 complete.