Create Guide

Create Guide

Purpose

Automate the first half of field-guide creation for this Core ML TTS repo:

1. Assemble a strong Deep Research brief (not a one-liner).
2. Launch create_guide_v1 in llm-workflows (Deep Research Max by default).
3. Poll or resume until raw markdown lands locally.
4. Hand the raw draft to repo-specific ingestion (guide-ingest when available).

A guide is a synthetic library entry: what competent practitioners would find if they spent an afternoon searching docs, issues, WWDC notes, papers, and forums. It exists so the next agent can reuse that research instead of guessing or re-Googling.

Raw Deep Research output is draft material only. Never place it in README/Guides/ until guide-ingest has normalized it, checked library/API claims, annotated firsthand contradictions, and cross-linked the corpus.

Guide/notes boundary: README/Guides/ is for externally researched reference manuals after raw-report.md exists and has been ingested. A pending checkpoint, prompt, local summary, or agent-written synthesis is not a guide. Do not create or update README/Guides/ unless you can point to the external raw source path, usually llm-workflows/outputs/create-guide/**/raw-report.md. Local briefs, prompts, repo analysis, verification notes, experiment logs, and implementation decisions belong in README/Notes/, not README/Guides/.

What A Guide Is For (Read This First)

A guide synthesizes external knowledge about a domain — mechanisms, gotchas, failure modes, recipes people report, known limitations. It is the artifact of research, not a recommendation engine for this repo’s next move.

A topic qualifies only when all three hold:

1. Non-obvious external domain. Hidden platform behavior, sharp library edges, undocumented scheduling, signing/entitlement traps, or similar — not something you invent from first principles.
2. A human would Google it. A developer stuck or unfamiliar would spend real time in docs, issue trackers, WWDC notes, or SME conversations.
3. Poorly represented in LLM training data. Niche, new, fast-moving, or the kind of thing models confidently hallucinate.

Good guide topics for this repo (shape: what does the world know about X?):

• "How does Core ML actually schedule ops across ANE/GPU/CPU, and what causes silent fallback?"
• "What ISTFTNet / vocoder conversion traps appear when targeting ANE fixed shapes?"
• "How do practitioners split TTS pipelines so sequential BERT/LSTM stays off ANE while dense decoder/vocoder stays on it?"
• "What Swift Core ML prediction patterns keep multi-model pipelines warm without thrashing the Neural Engine?"

Not A Guide (Dial-A-Friend / Advice)

create-guide is not “ask a smarter model what we should do.” That is second-opinion. Do not use create-guide when the ask is advice, judgment, or a campaign decision dressed up as research.

Reject or rewrite briefs that ask:

• "Should we put the decoder on ANE for this bakeoff?"
• "Is this Core ML bucket split the right next arm given our RTF?"
• "What should we do about these silent ANE fallbacks?"
• Product/scope choices, UX/copy, API shape, timeout/policy judgment
• General how-tos already covered well by training data or Context7

Litmus tests:

If the hard part is deciding what to build next, it is not a guide. If the hard part is stocking external domain knowledge an agent would otherwise Google, it might be.

Context in the brief may ground the researcher (pinned versions, hardware, what you already tried) so the synthesis stays relevant. Context must not turn the run into "advise our campaign." Prefer questions like "what ratios and failure modes appear in the literature?" over "are we justified to launch?"

Prerequisites

• llm-workflows checked out at /Users/mm/Documents/GitHub/llm-workflows
• GEMINI_API_KEY in llm-workflows/.env (or exported) for the default Deep Research Max streaming path
• WORKFLOW_RUNTIME_TOKEN in llm-workflows/.env (or exported) only when using --workflow-runtime, --no-wait, --resume, --run-id, or --result-url
• Optional: WORKFLOW_RUNTIME_BASE_URL (defaults to staging for workflow mode)

Use When

• User invokes create-guide
• The topic clears the three-part test — external domain knowledge a human would research when stuck or unfamiliar
• User wants to replace manual Gemini UI research with the automated workflow

Do Not Use When

• The ask is advice, go/no-go, or "what should we do next" (see Not A Guide)
• The topic is a well-trodden how-to already covered by training data or Context7 → answer directly or use Context7
• Raw export already exists → use guide-ingest
• Only fixing markdown in an existing guide → use markdown
• The local learning belongs in the repo, not external research → use write-notes
• Lighter in-session research without Deep Research → use write-notes

Workflow

1. Gather the brief

Collect from the user (ask if missing):

Default agentMode to max. Confirm before launching unless the user explicitly asked for fast/cheap (default).

If the user’s ask is advice-shaped, stop and reframe with them into a domain synthesis topic, or route away from create-guide. Do not launch Deep Research on a dial-a-friend prompt.

2. Assemble the research prompt

Follow the scratchpad pattern (see Scratchpad/scratchpad.md in active repo when present):

• Advanced developer field guide: synthesize public knowledge
• Best practices, worst practices, common bugs, hidden gotchas, known limitations
• Go light on theory, heavy on practical detail with code
• For complex topics: add Context, Primary research goal, Questions to answer, Output format
• Mark speculative / community / "worth trying" ideas separately from well-documented behavior — keep both; do not demand universal proof
• Explicitly tell the researcher not to produce a go/no-go for a specific product campaign; produce a reusable reference manual
• For text-only field guides: explicitly request no charts, images, diagrams, or generated visualizations. The runtime should also send agent_config.visualization: "off" for create_guide_v1.

Write a local brief file when helpful, then pass it via --context-file or --prompt-file. If the active repo has README/Notes/, put the brief there with a clear prompt/provenance name. Do not place briefs, local analysis, or unverified drafts in README/Guides/.

3. Launch the research run

From llm-workflows, run Max to completion with the local direct Gemini Interactions streaming transport:

cd /Users/mm/Documents/GitHub/llm-workflows

pnpm run research:create-guide \
  --topic "Core ML vs MLX scheduling for ISTFTNet vocoders" \
  --context-file /path/to/brief.md \
  --target-repo kokoro-coreml \
  --target-guide-path README/Guides/apple-silicon/coreml-ane-scheduling-guide.md \
  --agent-mode max

For Max, do not use --no-wait: the local streaming process is the reliable completion path and must stay alive to write raw-report.md. Use --workflow-runtime only when explicitly testing the Cloudflare Workflow transport.

For a non-Max or workflow-mode run:

pnpm run research:create-guide \
  --topic "Core ML vs MLX scheduling for ISTFTNet vocoders" \
  --context-file /path/to/brief.md \
  --target-repo kokoro-coreml \
  --target-guide-path README/Guides/apple-silicon/coreml-ane-scheduling-guide.md \
  --agent-mode default \
  --workflow-runtime

Artifacts land under:

outputs/create-guide/<slug>/<timestamp>/

• input.json — workflow input
• prompt.md — human-readable brief preview
• checkpoint.json — resume pointer
• run.json — polling status
• raw-report.md — final draft (when complete)
• result.json, metadata.json
• events.ndjson, thought-summaries.md, interaction-id.txt — direct Max streaming diagnostics

4. Resume if interrupted

pnpm run research:create-guide \
  --resume \
  --checkpoint outputs/create-guide/<slug>/<timestamp>/checkpoint.json

If only the remote run is known, resume with --run-id <id> or --result-url <url>. Do not restart a Max run if a checkpoint or run id exists. Resume first.

Direct local Max streaming runs cannot currently be resumed after the local process exits. If interrupted, inspect events.ndjson, interaction-id.txt, and raw-report.md before starting another run.

4.1. Triage provider failures

If the run fails before raw-report.md exists:

1. Inspect run.json, checkpoint.json, and any saved internal attempt artifacts before relaunching.
2. If the provider response body is redacted, recover details from the Interactions stream when possible: GET /v1beta/interactions/<id>?stream=true with the same Gemini key and API revision.
3. Do not default to "prompt too large" as the diagnosis. For provider_invalid_response / invalid_request after thought summaries such as "Considering Visual Elements", check the request artifact for agentConfig.visualization. It must be "off" for markdown-only guide runs.
4. If the request enabled or omitted visualization, rerun only after the runtime or prompt has been fixed to keep the guide text-only.
5. If the request is already text-only and the recovered stream is only interaction.created / status_update / invalid_request or provider api_error with no usable report text, do not launch another Max duplicate. Treat the Max guide as blocked, not complete. A default-agent rerun is a separate, explicitly downgraded deliverable and requires user authorization; it must never satisfy a request for Deep Research Max.

Current known failure signature, confirmed 2026-06-18 with raw REST streaming, the official collaborative-planning flow, a no-agent_config stream, @google/genai@2.8.0, and a no-explicit-tools direct stream matching the documented default Deep Research tool set: Deep Research Max accepts the interaction, often emits thought summaries through draft/polish/final editing, then returns stream event {"code":"api_error","message":"There was a problem processing your request. You will not be charged."} or resume returns 400 invalid_request, or polling remains stale at the original user_input timestamp before any final text. That is provider-side Max failure unless a later run produces non-empty raw-report.md.

5. Hand off to ingestion

When raw-report.md exists:

Ingestion owns: provenance, cleanup, Context7/API corrections, firsthand contradiction notes, bidirectional links. create-guide does not rewrite the draft into a campaign verdict.

Leave Related Documentation empty during Deep Research; ingestion adds repo cross-links.

Prompt Writing Guidelines

The prompt must be 100% self-contained. The research agent has no other context than the context that you share with it. It cannot look at your code unless you share your code. It can only search the web (and hit any MCP you wire up).

The more and richer context you give it, the more relevant the guide will be. Richer context ≠ asking it to decide your roadmap.

Prompt template (minimal)

Create an advanced developer field guide on: [TOPIC]

Synthesize what public docs, papers, issues, and practitioner reports say.
Best practices? Worst practices? Common bugs and issues? Hidden gotchas?
Idiosyncratic design quirks? Known limitations? Recipes people report as
worth trying?

Be extensive. Be comprehensive. Create a reference manual for implementation and debugging.
Go light on theory, heavy on practical detail with code examples.
Do not produce a go/no-go or roadmap for a specific product campaign.
Mark speculation and community heuristics separately from well-documented behavior;
keep both — do not omit "worth trying" material solely because it is unproven.

Context (environment pins only — not a request for advice):
[GROUND TRUTH]

Primary research goal:
[What external knowledge to synthesize]

Questions to answer:
- [Factual / practice Q1]
- [Factual / practice Q2]

Output format:
- Executive summary first
- Do-this / avoid-this tables
- Failure modes and debugging section
- Concrete profiling commands/tools when relevant
- Numbered references
- Mark speculation separately from documented recommendations

Handoff rules

References

• Runner: /Users/mm/Documents/GitHub/llm-workflows/scripts/run-create-guide-research.mjs
• Workflow: create_guide_v1 in /Users/mm/Documents/GitHub/llm-workflows
• Deep Research guide: /Users/mm/Documents/GitHub/llm-workflows/README/guides/gemini/Gemini-Deep-Research-agents-guide.md
• Ingest skill: guide-ingest
• Advice skill: second-opinion