offline-questions

Offline Questions

The user is in the middle of something and has thought of a question they care about but don't want to derail the current session for. Your job is to capture the question with rich context, hand it to a background subagent for research, and let the user keep working. The subagent appends a structured Q&A entry to ~/Desktop/Offline_Questions_and_Answers.md and fires a desktop notification when done.

Your job (the main agent)

You do four things, in order:

1. Echo the parked question (one line)

Before spawning anything, surface what you're about to send off so the user can catch a wrong-question disaster:

Parking: "" — researching in background (mode: standard | deep).

That's it. No further prose, no summary of what you're about to do.

2. Build the curated briefing

This is the most important step. The subagent has zero session context — what makes this skill better than the user opening a new Claude tab is you filtering the conversation down to the relevant signal. Write the briefing as if you were handing a smart colleague who just walked into the room a focused note.

Structure (these section headers go in the briefing prompt verbatim):

# Offline question

## The question
<verbatim what the user asked, no rewording>

## Session context
<3-6 sentences. What were we working on? What had we already established?
What had the user already ruled out? What made this question come up *now*?
Be specific — name the file, the bug, the metric, the PR. Don't write
"we were debugging an issue", write "we were tracing why the worker
process stalls under high queue depth, after seeing the worker parked
on a mutex acquire in the latest profiler output">

## Pointers (read these if useful)
<bullet list of concrete things the subagent can Read/WebFetch/grep:
- File paths with line numbers when known: `src/<module>/<file>.<ext>:88-110`
- URLs already discussed in the session
- PR / issue / ticket IDs
- Recent commit SHAs that touched the area
- Doc paths inside the repo
Skip pointers that aren't actually relevant. Quality > quantity.>

## What good looks like
<1-2 sentences on what kind of answer the user is after — "explain the
mechanism", "tell me whether X is true", "find me the right place in the
code", "summarise the tradeoffs". This shapes the answer's depth.>

## Mode
standard | deep

Curation discipline: include only what's relevant to this question. If we spent the session on three different topics and the question is about one, drop the other two. If the user already verified something, say so — don't make the subagent re-verify.

3. Spawn the background subagent

Use the Agent tool with these exact settings:

• subagent_type: general-purpose
• run_in_background: true
• description: "Offline Q: <short title — 4-6 words>"
• prompt: see the full subagent prompt template below — it bundles your briefing with the doc-writing instructions.

4. Confirm and stop

Tell the user, in one line:

Backgrounded. You'll get a desktop notification + in-session relay when it lands in ~/Desktop/Offline_Questions_and_Answers.md.

Then stop. Do not poll, do not keep talking. Resume whatever the user was doing before. When the background agent completes, you'll be notified automatically — at that point relay a one-line summary of the result to the user.

Subagent prompt template

Paste this into the prompt field of the Agent call, with <<BRIEFING>> replaced by the briefing you wrote in step 2:

You are an offline research subagent. The user parked a question mid-session because they care about the answer but didn't want to derail their current work. Your job: research it thoroughly, then append a single well-structured entry to ~/Desktop/Offline_Questions_and_Answers.md.

<<BRIEFING>>

## What to do

### 1. Research the question

Use the pointers as starting points. Don't trust the briefing's framing blindly — verify against the code/web/sources. Cite everything:

- For code claims: `path/to/file.rs:LINE` (with line numbers, not just paths).
- For web claims: full URL.
- For tool output: name the skill/tool used.

Mode = `standard`: you may use Read, Grep, Glob, Bash (read-only), WebSearch, WebFetch. Do **not** mutate the repo, do **not** invoke analytical skills.

Mode = `deep`: in addition to standard, you may invoke analytical or external-data skills the user has installed via the Skill tool (e.g. database query, monitoring/observability dashboards, third-party API explorers, deployment-status checks). Still no mutations.

If you hit a blocker (need a tool you don't have, paywalled doc, ambiguous question, conflicting evidence), **don't fail silently** — record what blocked you in the entry and set Status to `needs follow-up`.

### 2. Compose the entry

Use this exact template. Replace bracketed placeholders. Keep the answer tight: aim for ~200-400 words; if longer is truly needed, link to sources rather than inline-dumping. The user will re-read this later — long walls of text defeat the purpose.

```markdown
## YYYY-MM-DD HH:MM — [short question-as-title, ~10 words max]

**Status:** answered | needs follow-up
**Mode:** standard | deep
**Tags:** #tag1 #tag2 #tag3

### Context (from session)
[2-4 sentences from the briefing — what the user was doing when this came up,
why the question matters now. Trim, don't paste.]

### Question
[verbatim from the briefing]

### Answer
[the actual research result. Code refs as `file:LINE`. Be direct — lead with
the answer, then explain. If the answer is "it depends", say what it
depends on.]

### Visual
[Optional ASCII diagram. Include ONLY when it adds something prose can't:
sequence/timing diagrams, data flow, formulas, state transitions, before/after.
Skip for prose-shaped answers. If unsure, omit.]

### Sources
- `path/to/file.rs:LINE-LINE` — what this shows
- https://… — what this shows
- (if deep mode) skill:<analytical-skill> — what was queried

### Why blocked (only if Status = needs follow-up)
[what you couldn't resolve and what would unblock it — e.g. "needs deep mode
to access an analytical skill", "two sources contradict, need user judgement"]

---
```

### 3. ASCII art guidance

Include a `### Visual` section ONLY if the diagram would help future-you understand the answer faster than the prose alone. Good cases:

- A formula: `score = α · feature_a + β · feature_b`
- Sequence: who-calls-whom-with-what
- Data flow: A → B → C with annotations
- State diagram: states + transitions
- Before/after: side-by-side

Bad cases (omit Visual entirely):

- The answer is a definition or short explanation
- The diagram would just restate the prose
- You're tempted to draw a generic box-and-arrow that adds no information

When in doubt, leave it out. A skipped `### Visual` is better than a noisy one.

### 4. Append safely with a file lock

The doc is shared across concurrent runs. Use `flock` (or a `mkdir`-based fallback) to serialise writes. The lock file lives next to the doc as a hidden sibling.

Workflow:

1. Build the new entry text in a variable / temp file.
2. Acquire `~/Desktop/.Offline_Questions_and_Answers.md.lock` (block, don't fail).
3. If `~/Desktop/Offline_Questions_and_Answers.md` doesn't exist, seed it with a header and empty TOC (see template below).
4. Read the existing file, parse out the TOC + body.
5. Prepend new entry to the body (newest-on-top), prepend new TOC line to the TOC.
6. Atomically rewrite the file (`mv tmp final`).
7. Release the lock.

The seed template for a new file:

```markdown
# Offline Questions & Answers

Background-researched answers to questions parked mid-session. Newest at top.

## Index

<!-- TOC: one line per entry, newest first -->

---

```

A new TOC line looks like: `- [YYYY-MM-DD HH:MM — short title](#YYYY-MM-DD-HHMM--short-title-slug)` (slugified to match the heading anchor). Insert it as the first line under the `<!-- TOC: ... -->` comment.

Concrete bash skeleton (adapt as needed):

```bash
DOC="$HOME/Desktop/Offline_Questions_and_Answers.md"
LOCK="$HOME/Desktop/.Offline_Questions_and_Answers.md.lock"

if command -v flock >/dev/null 2>&1; then
  exec 9>"$LOCK"
  flock 9
  # ... read DOC, splice in new entry + TOC line, write atomically ...
  flock -u 9
else
  # mkdir-based fallback (atomic on POSIX)
  while ! mkdir "$LOCK.d" 2>/dev/null; do sleep 0.2; done
  trap 'rmdir "$LOCK.d"' EXIT
  # ... same splice ...
fi
```

If `flock` isn't installed on macOS, the user can `brew install flock`; the `mkdir` fallback works regardless.

### 5. Notify on completion

After the file is written and the lock released, fire a macOS desktop notification:

```bash
osascript -e 'display notification "<short title>" with title "Offline Q&A" subtitle "answered | needs follow-up" sound name "Glass"'
```

Then return to the calling agent a single-line summary like:

> Done — appended *"<title>"* (N sources, mode=standard). Status: answered.

## Examples of good vs bad context briefings

### Good

```
## Session context
We're chasing intermittent test failures in CI that don't reproduce
locally. Today we narrowed it down to a particular suite that runs
last in CI and first locally. The user wonders whether the test
runner's parallel scheduling could be reordering setup hooks in a
way that leaks state between files, vs the user's prior assumption
that each test file gets a fresh fixture.

## Pointers
- `tests/setup.ts` — global fixture setup
- `package.json` — runner config (look at the `test` script)
- `.github/workflows/ci.yml` — CI invocation, note the `--parallel` flag
```

### Bad

```
## Session context
We were debugging something and the user had a question about how the
test runner works. They wanted to know more about scheduling.

## Pointers
- the codebase
- the docs
```

The bad version forces the subagent to rediscover everything. The good version lets it start working in the right place within seconds.

## Non-features (don't add these)

- **No confirmation prompt before firing.** The one-line echo is enough; confirmation defeats "park and move on".
- **No edit / delete / list slash commands.** The doc is a markdown file; the user edits it by hand.
- **No tag taxonomy.** Tags are subagent-picked, free-form, grep-able.
- **No archiving / pagination.** Append forever; user archives manually if it ever matters.