@@ -50,6 +50,64 @@ The `-u` flag is **required** in repo mode — it needs something to clone.
| `--no-cleanup` | both | Keep the temp workspace after exit |
| `--verbose` | both | Print tool calls and results to stderr |
+## Crafting queries
+
+Rumilo works best with focused queries. Think about **scope** and **coupling** when deciding what to ask and how many questions to include.
+
+- **Tightly coupled, narrow scope** — multiple simple questions in one call is fine when they're about the same small surface area (a single file, one struct, one API endpoint).
+- **Broad scope or loose coupling** — one question per invocation. If answering requires exploring many files or pages, keep it to a single clear question so the agent can focus.
+- **Write natural questions, not keyword lists.** Rumilo is an LLM, not a search index.
+- **Sequence calls when later questions depend on earlier answers.** Get the overview first, then drill in.
+
+### Bad
+
+Overloaded — five loosely-coupled questions spanning an entire diff, each requiring different context:
+
+```bash
+rumilo web "In this diff, find: 1. What files are modified and created \
+2. What config options each channel exposes 3. How messages are formatted \
+4. The architecture for adding a new channel 5. What UI components exist" \
+ -u "https://example.com/commit/abc123.diff"
+```
+
+### Good
+
+Sequenced calls, each with a clear scope. Later calls include non-obvious context from earlier results — file paths, symbol names, patterns — so rumilo can go straight to the answer instead of searching.
+
+```bash
+# 1. Lay of the land — broad overview first
+rumilo web "What files were modified or created, and what's the broad shape of the change?" \
+ -u "https://example.com/commit/abc123.diff"
+
+# 2a and 2b can run in parallel — neither depends on the other,
+# but both benefit from context learned in step 1.
+
+# 2a. Architecture deep-dive, pointing to the key file discovered in step 1
+rumilo web "How is the notification system in pkg/notify/ architected? \
+ Each channel seems to implement a Sender interface — what's the process \
+ for adding a new one?" \
+ -u "https://example.com/commit/abc123.diff"
+
+# 2b. Config drill-down, referencing the settings struct found in step 1
+rumilo web "What configuration options does each channel expose in \
+ ChannelSettings? Can message content be customised?" \
+ -u "https://example.com/commit/abc123.diff"
+
+# 3. UI specifics, narrowed by what steps 1–2 revealed about the component tree
+rumilo web "The channel config UI lives in web/src/components/settings/channels/. \
+ Do the per-channel forms follow a shared pattern or component?" \
+ -u "https://example.com/commit/abc123.diff"
+```
+
+Don't include context that's obvious or redundant — telling rumilo to "search for notif" when asking about notifications wastes tokens. Focus on non-obvious anchors: exact file paths, struct names, interface signatures.
+
+Tightly coupled questions in a single call are fine when the scope is small:
+
+```bash
+rumilo repo -u "https://github.com/owner/repo" \
+ "What fields does the Config struct have and which are optional?"
+```
+
## Choosing a mode
- Need to find or learn about a library? **Web** to locate it, then **repo** to explore its source.