Flavor Bootstrap

# Phase 0: analyze unresolved link targets before the next round
PYTHONPATH=. python3.11 flavor_graph/analyze_link_violations.py

# After reviewing _system/link-violation-analysis.md, append safe aliases and
# rerun deterministic passes:
PYTHONPATH=. python3.11 flavor_graph/analyze_link_violations.py --apply-aliases

# Build prioritized fill batches from the current manifest:
PYTHONPATH=. python3.11 flavor_graph/prepare_fill_batches.py

# Build one concrete operator packet for the next fill wave:
PYTHONPATH=. python3.11 flavor_graph/build_fill_wave.py --wave high_ref

# Inspect research cache status:
PYTHONPATH=. python3.11 flavor_graph/research_cache.py stats

# Read a cached research payload for one title:
PYTHONPATH=. python3.11 flavor_graph/research_cache.py get --title "Soda water"

# Run one bootstrap round (deterministic passes only):
cd /home/mango/workspace/Obsidian/Flavors
PYTHONPATH=. python3.11 flavor_graph/bootstrap_round.py

# Run until convergence (up to 5 rounds):
PYTHONPATH=. python3.11 flavor_graph/bootstrap_round.py --until-convergence

# Run with all auto-fixes disabled (audit only):
PYTHONPATH=. python3.11 flavor_graph/bootstrap_round.py --no-fix-links --no-fix-schema

# Inspect current quality state without modifying anything:
PYTHONPATH=. python3.11 run_checks.py --note-quality --tier-report

# Review the unresolved-link analysis artifact before fill waves:
python3.11 -c "import json; print(json.dumps(json.load(open('_system/link-violation-analysis.json')), indent=2)[:4000])"

# View what's in the create-manifest (notes ready for LLM fill):
python3.11 -c "import json; print(json.dumps(json.load(open('_system/bootstrap-create-manifest.json')), indent=2)[:4000])"

# View the manual review queue:
python3.11 -c "import json; print(json.dumps(json.load(open('_system/bootstrap-manual-review.json')), indent=2)[:4000])"

Fill is a manual LLM operator step. After running the deterministic round, read the create-manifest and launch fill agents using the protocol below. The orchestrator does not launch fill agents itself.

Phase 0 — Link Resolution Runbook

Run this once before the next fill cycle whenever unresolved links spike or the create-manifest looks suspiciously small.

1. Run PYTHONPATH=. python3.11 flavor_graph/analyze_link_violations.py
2. Review _system/link-violation-analysis.md
3. Confirm the Safe Alias Proposals section looks correct
4. Apply them with PYTHONPATH=. python3.11 flavor_graph/analyze_link_violations.py --apply-aliases
5. Run PYTHONPATH=. python3.11 run_checks.py --bootstrap-round
6. Build the next fill packet with PYTHONPATH=. python3.11 flavor_graph/prepare_fill_batches.py
7. Select the next concrete wave with PYTHONPATH=. python3.11 flavor_graph/build_fill_wave.py --wave <generic_parents|high_ref|medium_ref|low_ref> [--offset N] [--limit N]

Interpret the analysis buckets like this:

• Safe Alias Proposals — append to Reference/Ingredient aliases.md; rerun deterministic passes immediately
• Generic Missing Parents — create/fill these notes before product-specific waves when they are true routing parents ([[Soda water]], [[Port wine]], etc.)
• True New Note Candidates — leave for manifest-driven fill waves
• Noise / Scraper Artifacts — do not create notes; resolve via alias cleanup, parser fixes, or manual discard

This phase should happen before large LLM fill waves. Otherwise brand products can be hidden in duplicate buckets and garnish noise can pollute the manifest.

Phase 1a — Wave Packet

Before launching any research subagents, build a concrete wave packet. This removes repeated manual manifest triage and prompt assembly.

1. Run PYTHONPATH=. python3.11 flavor_graph/prepare_fill_batches.py
2. Run PYTHONPATH=. python3.11 flavor_graph/build_fill_wave.py --wave high_ref
3. Read _system/current-fill-wave.md
4. Launch one research-free subagent per entry in _system/current-fill-wave.json
5. Write the whole batch, validate it, rerun bootstrap, then build the next wave packet

Recommended default packet sizes:

• generic_parents: 8
• high_ref: 8
• medium_ref: 10
• low_ref: 12

The current wave packet includes:

• exact title
• target path
• reference count
• source notes
• suggested book query
• suggested research focus
• recommended worker tier
• initial research skill + mode
• escalation rule
• ready prompt_stub text for the research subagent

This is the default batching workflow for all fill work.

Phase 1b — Research Cache

Before launching workers for a packet, check _system/current-fill-wave.json.

Each entry now includes:

• cache.status — fresh, stale, or missing
• orchestrator_action — reuse_cached_research or launch_worker
• skill_chain — ordered free → budget → paid fallback path using the skills available in this OpenCode instance

Cache policy:

• If cache.status == fresh, reuse the cached payload and skip web research
• If cache.status == stale, optionally reuse as a draft but prefer a fresh worker pass
• If cache.status == missing, launch the worker specified by research_plan

Persist returned research with:

PYTHONPATH=. python3.11 flavor_graph/research_cache.py put \
  --title "Ingredient Name" \
  --skill research-free \
  --mode quick \
  --worker-tier small \
  --payload-json '{"wiki_link":"...","summary_facts":["..."],"flavor_descriptors":["..."],"components":["..."]}'

The orchestrator should treat the cache as the default reuse layer between rounds.

Model Split

Use the main bootstrap model only for orchestration:

• run deterministic scripts
• build or select the next wave packet
• launch worker subagents in parallel
• write/patch notes after research is returned
• rerun validators and bootstrap
• use the question tool for human tail decisions

Push the note-level nitty gritty down to smaller or cheaper workers.

Default split:

• Large orchestrator model: bootstrap, batching, validation, final synthesis
• Small workers: research-free quick/standard for most generic parents, syrups, bitters, fruit notes, and common product notes
• Medium workers: research-cheap standard for nuanced producer-specific spirits, amaros, vermouths, sherries, and liqueurs
• Premium workers: research-premium only when medium still cannot surface usable sensory differentiation or trustworthy sources

Cost policy for this instance:

• research-free uses Big Pickle and is free
• research-cheap uses DeepSeek Chat and is budget-tier
• research-premium uses Zen models and is not free

So the orchestrator should always prefer:

1. cache reuse
2. research-free
3. research-cheap
4. research-premium

The wave packet now carries this recommendation per entry as research_plan so the orchestrator does not need to reason about model size every time.

What One Round Does

Each round runs these steps in order:

1. Snapshot — Parse the entire vault once into a shared VaultSnapshot. Captures per-note: path, type, aliases, section map, all wikilinks with section context, prose text. Emits _system/vault-snapshot.json.

2. Registry — Build a typed canonical resolver from snapshot data + synonym files. Handles case, punctuation, hyphen, plural/singular normalisation, and expected-type filtering by section context.

3. Link integrity — Classify every link and prose mention: canonical valid / non-canonical (auto-fix) / wrong-type (blocked) / unlinked mention (auto-add) / unresolved (queued) / ambiguous (manual review). Auto-fix scope: prefix cleanup, .md suffix cleanup, case normalisation, alias rewrites, prose-link insertion. Emits _system/link-integrity-report.json.

4. Candidate pipeline — For each unresolved mention, classify as: existing canonical note → link fix only; alias → link rewrite only; duplicate candidate → reconciler; valid variant → keep both; true new note → create-manifest; stoplist/noise → discard; ambiguous → manual review. No empty stub files are created at any point. Emits _system/bootstrap-candidates.json, _system/bootstrap-create-manifest.json, _system/bootstrap-manual-review.json.

5. Duplicate reconciler — Classify duplicate groups, choose canonical deterministically (highest content, deepest folder, populated status preferred), migrate aliases, rewrite all inbound links vault-wide, delete duplicates. Runs before the note compiler so deleted duplicates don't inflate the failure count. Variants kept only when taxonomy + prose clearly separate them; ambiguous pairs go to manual review. Emits _system/duplicate-reconciler-report.json.

6. Note standards compiler — Full-vault structural lint: type/folder correctness, required section presence by type, forbidden structure by type (e.g. flavor notes must have no frontmatter), Wiki link: presence. Auto-fix scope: creates missing frontmatter, repairs wrong type/status/tags fields, inserts missing *Recorded on* datestamp. Does NOT perform link canonicalization — that is B3's exclusive job. Emits _system/note-compiler-report.json.

7. Convergence check — Evaluate all blocking queues. Print round summary. If converged, stop. If not, report remaining counts and surface the create-manifest for operator-driven fill.

Fill is a manual operator step that happens between deterministic rounds. After the round completes, if bootstrap-create-manifest.json is non-empty, the operator reads it and launches fill agents per the Fill Agent Protocol below. After fill, re-run bootstrap_round.py to validate and detect any new violations introduced by the filled notes.

Convergence Criteria

The pipeline has converged when all blocking queues are zero:

Acceptable non-zero: manual_review.count — surfaced to the user, does not block convergence.

Manual Review Queue

_system/bootstrap-manual-review.json accumulates items that the orchestrator cannot resolve deterministically:

• Ambiguous mentions — a name that matches multiple vault notes with no section-context to disambiguate
• Cross-type duplicates — two notes that appear to cover the same subject but have different types
• Variant ambiguity — a candidate that may be a distinct ingredient or an alias of an existing one

To action manual review items:

1. Read _system/bootstrap-manual-review.json
2. For each item, decide: alias (patch frontmatter) / merge (pick canonical, delete other) / keep distinct (add differentiating prose) / discard (add to stoplist)
3. Apply the decision manually, then re-run bootstrap_round.py — the resolved item will no longer appear

Surface all open manual review items to the user after each run.

Human-in-the-loop requirement: When the queue is small enough to review directly, the agent must use the question tool to ask the human what to do with each remaining tail item. Present exactly these choices:

• Alias — rewrite to an existing canonical note
• Create note — keep distinct and add it to the next fill wave
• Stoplist — treat as noise / extraction artifact and discard
• Defer — leave unresolved for a later session

This question-tool round is mandatory before closing a session with remaining tail items.

Fill Agent Protocol

When bootstrap_round.py --fill runs, it reads the create-manifest and launches fill agents. Each agent receives a typed batch of manifest entries and must follow this protocol:

Batch sizes (ceiling per agent):

• Compounds: max 15 per agent
• Ingredients: max 12 per agent
• Flavors: max 20 per agent

For each manifest entry:

1. Book search first (ingredients and compounds — mandatory). Before any web research, check what the reference library says. Use book_search MCP directly:

   • Ingredients: book_search(query="<name> flavor taste aroma", limit=6) — all books
   • Compounds: book_search(query="<name> smells aroma", book_id="nose_dive", limit=4)
   • Rum/tiki ingredients: also book_id="smugglers_cove" and book_id="cocktail_codex"
   • Technique-based ingredients (acids, carbonation): also book_id="liquid_intelligence"
   • If a hit has sensory content, call book_get_page(book_id, page, context_pages=1) for the full passage.
   • Book content takes priority over generic web prose. Include the best passage as a citation ([Book Title, p.N]: ...) in the # Notes section.
   • If no relevant book hits (no sensory content), proceed to web research without a citation.

2. Web research. Start with the research-free skill. Escalate only if it is too thin.

   • Default: research-free quick mode (3 searchers)
   • Spirits and liqueurs with weak free results: retry with research-free standard mode
   • Escalate to research-cheap only when the free pass returns no usable sensory detail or no trustworthy product coverage
   • Escalate to research-premium only for stubborn high-value items (complex amaros, obscure fortified wines, hard-to-source producer notes)
   • Structural ingredients (aloe, saponins, etc.): Wikipedia only
   • Focus: sensory/flavor properties, aroma occurrence, mouthfeel — not history or taxonomy.

   A result is too thin when it fails any of these:

   • fewer than 100 words of ingredient-specific sensory content
   • no parent-relative differentiation for a product note
   • only retailer boilerplate or availability pages
   • no reliable source URL worth using for Wiki link:

3. Write the note. Follow the type-specific fill prompt exactly. Sensory-first prose. Inline wikilinks throughout. Use obsidian_write_note on the path specified in the manifest entry.

4. Validate immediately. After writing each note, run the per-note schema validator:

   PYTHONPATH=. python3.11 run_checks.py --note-standards --paths "Flavors/<relative-path>"
   

   Then manually verify: correct type in frontmatter, *Recorded on YYYY-MM-DD* line present (ingredient/compound only), required sections present, no frontmatter on flavor notes. Do not run the full bootstrap round per-note — --note-standards is a single-note schema check only. Fix any reported issues before moving to the next note.

5. Log. Append one activity log entry to Flavors/_system/llm-activity-log.md covering the full batch. Log any fill failures to Flavors/_system/bootstrap-issues.md.

Type-specific fill invariants:

• Ingredient: Must explain the ingredient's own sensory identity, not just category prose. For product/subtype notes, include at least one parent-relative distinction.
• Compound: Must explain sensory contribution and why it matters in ingredient notes — not just class and occurrence.
• Flavor: Must provide reusable sensory language and interaction behavior, not just a definition.
• HARD STOP — Flavor note format: Flavor notes have no frontmatter, no *Recorded on* line, no anchor sections. Only valid format is ## Flavor description: followed by a paragraph. Read Flavors/Flavors/Minty Flavor.md as the canonical example.

Fill Prioritization

How Candidates Reach the Manifest

The B4 candidate pipeline classifies every unresolved mention before any note is created. Only true new notes reach the create-manifest:

• Bucket A — Alias / duplicate: Resolved automatically by B4 as alias rewrites or link fixes. Do not appear in the manifest.
• Bucket B — Valid variant / child ingredient: Kept as a distinct semantic object when taxonomy and prose clearly separate it from the parent. May appear in the manifest if the child note does not yet exist; requires prose that explicitly differentiates it from the parent.
• Bucket C — Embedding-critical: Directly affects ingredient embeddings or high-traffic recipe interpretation. Requires full research and full fill. Examples: ingredients used across many recipes, compounds explaining major aroma or bitterness, flavor notes reused across many composites, composed ingredients (bitters, syrups, vermouths, amaros, curaçaos).
• Bucket D — Supporting: Contributes to bubble-up but is not a major routing hub. Concise but embedding-useful fill.
• Bucket E — Reference-only / low-impact: Orphan or near-orphan note with no meaningful routing role yet. Lowest priority; may defer to a later round.

Priority Rules

When the manifest contains many entries, fill in this order:

1. Product-specific and variant-specific ingredients that change recipe meaning
2. Composed ingredients with missing tasting prose or missing defining recipe link
3. High-backlink ingredients used in many recipes
4. Category notes that act as routing parents for many child notes
5. Low-impact or reference-only ingredient stubs

Practical default order now:

1. generic_parents
2. high_ref
3. medium_ref
4. low_ref

Signals that increase priority:

• Many recipe backlinks
• Many inbound compound or flavor references
• Used in classic cocktails or frequently reused formulations
• Likely to change substitution behavior materially
• Likely to improve broad families of ingredient composites

Re-Fill Rules

When the quality gate re-queues a note, do not blindly regenerate it.

Instead:

• Read the current note first
• Identify what is missing: sensory density, distinction, inline links, components, composed-ingredient structure, parent-child clarity
• Augment the weak parts only

Typical upgrade moves:

• Replace generic one-paragraph prose with opening / palate / finish structure
• Add explicit contrast with parent category
• Replace generic flavor labels with discriminative descriptors
• Prune low-value component links and add higher-value ones
• Add # Classification
• Add # Clone Recipe / # Composition for composed ingredients (bitters, syrups, liqueurs, tinctures) — this link is the ingredient's embedding source; the pipeline computes the ingredient's vector from the linked recipe by weighted composition, identical to cocktail embedding; tasting notes on the ingredient note are documentation only

Style Reference Notes

Use these as fill quality calibration — do not copy wording from them:

• Flavors/Ingredients/Bitter Ingredients/Angostura bitters.md
• Flavors/Ingredients/Liqueur Ingredients/Pierre Ferrand Dry Curaçao.md
• Flavors/Ingredients/Spirit Ingredients/Plymouth gin.md
• Flavors/Ingredients/Liqueur Ingredients/Bénédictine.md
• Flavors/Ingredients/Amaro.md

Post-Batch Checklist

After each fill batch:

1. Confirm the intended files were populated or enriched.
2. Confirm every newly created or rewritten note passes run_checks.py --note-standards --paths ....
3. Confirm new inline links resolve and use canonical Obsidian targets.
4. Run PYTHONPATH=. python3.11 run_checks.py --link-integrity --fix if the batch introduced or rewrote links broadly.
5. Confirm ## Flavor profile and # Components are not padded with low-value links.
6. Confirm product and variant notes include parent classification where appropriate.
7. Confirm composed ingredients include # Clone Recipe / # Composition linkage when applicable — the linked recipe must have a populated ingredient list with ratios for the embedding to be correct.
8. Update Flavors/_system/stub-index.md.
9. Append one batch entry to Flavors/_system/llm-activity-log.md.
10. If the remaining queue is now small, run the question-tool manual review round before ending the session.

Parallelism Rules

• Subagents within the same phase may run in parallel when writing separate files.
• Different phases should remain sequential when one phase changes prerequisites for the next.
• Ingredient batches may be split by high-level family, but priority tiers must still be respected inside each batch.

Round Summary Output

Print after each round:

=== Flavor Bootstrap — Round N Complete ===

Link Integrity
  Unresolved violations:     A  (blocking)
  Wrong-type violations:     B  (blocking)
  Auto-fixed:                C

Candidate Pipeline
  Unresolved mentions:       D  (blocking)
  Added to create-manifest:  E
  Added to manual review:    F

Note Standards
  Failures:                  G  (blocking)
  Auto-fixed:                H

Duplicate Reconciler
  Auto-resolvable groups:    I  (blocking)
  Deleted duplicates:        J
  Added to manual review:    K

Create Manifest (for next operator fill wave)
  New notes queued:          L  (ingredients: l1, compounds: l2, flavors: l3)

Manual Review Queue
  Open items:                N  (non-blocking — requires human decision)

Converged: YES / NO
Remaining blocking total:    A + B + D + G + I

Next action: [none — converged] | [run fill wave from create-manifest, then re-run] | [action manual review items, then re-run]

Pipeline Observability

Append to Flavors/_system/bootstrap-issues.md whenever you encounter:

Entry format:

## YYYY-MM-DD Round N — <short title>

- **Category:** <category>
- **Subject:** <note name, script, or "general">
- **Observed:** <one or two sentences>
- **Impact:** <notes or links affected>
- **Suggested fix:** <concrete action>
- **Status:** open | fixed | wont-fix

After the final convergence round, scan for open entries with low-effort fixes (synonym row, stoplist entry) and apply them inline before finishing. Surface remaining open entries to the user.

Safety Contract

• Never rename notes — every filename is a link target across 2,000+ notes.
• Never delete stubs manually — the duplicate reconciler handles deletion; agents only add content.
• Never create empty stub files as workflow state — the create-manifest is the only new-note queue.
• Never add content to Navigation/ pages.
• Never create duplicate notes — always check the manifest and registry before writing.
• Alias patches are safe — they only add frontmatter aliases, never rename files.
• Always append to llm-activity-log.md at the end of any round that modifies content.
• Always log issues to bootstrap-issues.md as you encounter them — do not batch at end.
• Surface open manual review items and open issues to the user in the convergence summary.
• Sensory identity outranks taxonomy — never sacrifice prose quality for cleaner structure.

Key Reference Files

Location: This skill lives at Flavors/.opencode/skills/flavor-bootstrap/SKILL.md. To invoke from the main workspace: use_skill("flavor-bootstrap").