mqlisted

# mq Skill: Structure-Aware Context Query `mq` doesn't compute answers — it externalizes a file's structure into your context so you extract only what you need instead of dumping the whole file. Probe, then extract. ``` File or dir → mq query → structure/section enters your context → you reason → answer ``` ## When to use mq — and when NOT mq's benefit is a smaller context footprint; its cost is per-call round-trips. Net win only when the saving beats the overhead. This is a real tradeoff, measured — not "always mq". | Situation | Do this | |---|---| | You **know** the function/section you want | **One call:** `mq <file> '.section("Name") \| .text'` or `mq <file> '.search("term")'`. Beats reading the whole file (~18% cheaper + faster, measured). | | You'll read the **same big file repeatedly** | `.tree` once, then many cheap `.section` extracts. Map amortizes. | | **Unfamiliar directory** / search across files | `mq dir/ '.tree \| depth(1)'`, `mq dir/ '.search("x")'` — one call replaces many grep+cat. | | Large file (200+ lines), you need a **slice** | Extract the slice; don't slurp the file. | | **Small file (<~100 lines)** | Just `Read` it — mq's round-trip costs more than the file. | | **One-shot** read, you need **most/all** of the file | Just `Read` it (targeted with offset/limit if you know the slice). | **The #1 pitfall — the `.tree`→`.section` dance for a target you already named.** If the task names the thing, do NOT run `.tree` first. That two-call dance was m