---
name: missingmanual
description: Deep external research on demand. Writes a rich research brief, sends it to MissingManual for a Deep Research field guide or a verified paper list, then saves, verifies, and cross-links the result in this repository. Use proactively, without asking, whenever a hard technical question depends on external behavior that primary docs, Context7, and training data do not reliably answer (undocumented platform behavior, hidden gotchas, niche or fast-moving systems, research literature), or when the user asks for MissingManual, a guide, or papers.
---

# MissingManual

One skill for research the agent cannot do reliably from memory: a Deep
Research **field guide**, a verified **paper list**, or both. Invoking this
skill is the authorization. Do not ask the user to confirm the question, the
brief, or the spend; the payment step below is the only human gate, and only
when the installation has no saved card or credit.

The result is only as good as the brief. The researcher sees nothing but what
you send: not this repo, not this conversation, not the user's code. A
one-line topic buys a generic essay. A rich brief buys a manual for exactly
this problem.

## 1. Classify

| The hard part is... | Action |
| --- | --- |
| How an external system actually behaves: hidden mechanism, undocumented behavior, sharp edge, platform quirk | `create_guide` |
| What the research literature says: methods, benchmarks, prior art for a technical decision | `find_papers` |
| The user explicitly asked for both a guide and papers | Both, with one brief each (never double the spend on your own judgment) |
| Deciding what to build (product, UX, API shape, policy) or a well-trodden how-to | Neither. Answer directly or use Context7. Spend nothing. |

A guide topic qualifies only when all three hold: a non-obvious mechanism, a
competent developer would research it or ask an expert, and models handle it
poorly (niche, new, fast-moving, or commonly hallucinated).

Good guide shapes:

- "How does Core ML schedule ops across ANE/GPU/CPU, and what causes silent
  fallback?"
- "What exact APNs payload and entitlements wake a Live Activity in the
  background, and what only works on device?"

## 2. Ground

Before writing the brief, spend a few minutes in the repo:

- Read existing guides, notes, wiki, and papers on the topic. If an existing
  guide already answers the question, use it and stop.
- For papers, list what the repo already holds (titles, arXiv ids, DOIs) so
  the brief can exclude them.
- Collect ground truth the researcher needs: languages, frameworks, exact
  versions, target platforms and devices, what was tried, what failed, exact
  error messages, measurements, and the decision this research must unblock.

## 3. Write the brief

Fill every field that applies. Empty fields are wasted money.

| Field | What goes in it |
| --- | --- |
| `topic` | One precise line: the mechanism or literature question, not a vague area. |
| `context` | The most important field. A self-contained dump of ground truth: stack and versions, the shortest code or config excerpts that show the problem, what was tried and what happened, exact errors, constraints, the decision this unblocks. Several paragraphs is normal; keep the whole request under about 48 KB. Never include credentials, secrets, tokens, or personal data. |
| `primaryResearchGoal` | The one outcome that makes this research a success, stated as a decision or capability. |
| `questions` | 5-15 concrete, answerable questions. Each should be one the final document can resolve with evidence. |
| `sourceHints` | Docs, specs, repos, issue trackers, talks, authors, or venues to prioritize. |
| `avoidSources` | Sources to distrust (outdated versions, SEO blogs, known-wrong answers). For papers, the ones the repo already holds. |
| `targetRepo` | This repo's name. |
| `targetGuidePath` / `targetPaperDirectory` | Where the result will live, following the repo's existing convention. |
| `maxPapers` | Papers only. Default 10, maximum 30. |
| `outputInstructions` | Guides: "Advanced developer field guide. Executive summary first; best and worst practices; hidden gotchas; failure modes and debugging; code examples; do-this / avoid-this tables; numbered references; mark speculation separately from evidence. Text only: no charts, images, or diagrams." Papers: "For each paper: canonical id, title, authors, year, primary-source link, abstract, and why it matters to the stated decision. Merge preprint and published versions. Exclude keyword-only matches." |

Always pass `agentMode: "max"` and `maxTotalChargeUsdMicros: 25000000`
($25) unless the user explicitly asked for something cheaper.

If the repo has a notes directory, save the brief there as
`<slug>-research-brief.md` for provenance. Do not create a notes directory
just for this.

## 4. Submit and wait

1. Call `create_guide` and/or `find_papers` with the brief. You get a
   `handle` (opaque, local) and a `status`.
2. `payment_required` / `billing_action_required`: show the user the
   returned `actionUrl` in one line saying what it approves. Never open,
   fill, or submit that page yourself. Keep polling; research starts once the
   card is approved.
3. Poll `get_result` with the same `handle` about every 30 seconds. Research
   can take up to 90 minutes. Keep working on other things meanwhile if you
   can. Never resubmit the same question because it is still pending: the
   same `handle` resumes the same paid job, even across session restarts.
4. On failure or `pricing_gap`, report it plainly; nothing was charged. Do
   not resubmit automatically.

## 5. Ingest

Skip file writes only if the user asked for links only or no file changes.

Guides:

1. Call `save_guide` with the `handle`, `topic`, and the `markdown` and
   `receipt` from `get_result`.
2. Verify library, SDK, API, and CLI claims in the saved guide against
   current docs (Context7 when available). Append each contradicted claim and
   its correction to the guide's Verification section; do not edit the body.
3. Add outbound links from the guide to related guides and notes in the repo,
   and inbound links to it from the docs, indexes, and notes it supports or
   supersedes.

Papers:

1. Call `save_papers` with the `handle`, the `markdown`, and the `sources`
   array whenever `get_result` returned one.
2. For each retained paper, confirm the canonical id, title, authors, year,
   and primary-source link. Drop any that do not support the brief's
   decision.
3. Link the saved papers from the notes or guides that motivated the search.

Then tell the user in a few lines: what was saved and where, what it
answered, what it cost (from the receipt), and any `quality.unresolvedLimitations`
or Verification corrections. A guide's Verification section overrides the
body text above it.

## Constraints

- Never put a credential, capability, or raw job id in a message or saved
  file. The `handle` is the only identifier that appears.
- Never claim more verification than the receipt and your own checks
  support.
- Enrollment (`missingmanual enroll`) saves a card so future runs start with
  no approval step. Mention it once if the user keeps approving checkouts.