ask-internal

# Ask Internal

Answer team-internal questions by reading `.internal-docs/` and the codebase, synthesizing a direct answer with file:line citations, and optionally running surfaced commands with confirmation.

**Announce at start:** "I'm using the ask-internal skill to answer this from internal-docs and the codebase."

## When to use

- "How do I reset my dogfood profile?"
- "What's the deal with the OpenClaw VM startup?"
- "Where do we configure release signing?"
- Any question whose answer lives in setup runbooks, feature notes, architecture docs, or the code that produced them.

## Hard rules — never do these

- NEVER execute a state-mutating command without per-command `y` confirmation from the user.
- NEVER edit BrowserOS code or docs in response to an ask-internal question. The skill answers; it does not write files.
- NEVER guess. If grep finds nothing useful in docs or code, say so plainly.
- NEVER run this skill if `.internal-docs/` is missing. Stop with the init command.
- NEVER cite a file or line number you have not actually read.

## Voice rules

Apply these voice rules to the synthesized answer:

- Lead with the point.
- Concrete nouns. Name files, functions, commands.
- Short sentences. Active voice. No em dashes.
- Banned words: delve, crucial, robust, comprehensive, nuanced, multifaceted, furthermore, moreover, additionally, pivotal, landscape, tapestry, underscore, foster, showcase, intricate, vibrant, fundamental, significant, leverage, utilize.
- No filler intros.

## Workflow

### Step 0: Pre-flight

```bash
if git submodule status .internal-docs 2>/dev/null | grep -q '^-'; then
  echo "internal-docs submodule not initialized. Run: git submodule update --init .internal-docs"
  exit 0
fi
[ -d .internal-docs ] && [ -n "$(ls -A .internal-docs 2>/dev/null)" ] || {
  echo ".internal-docs/ missing or empty. Submodule not configured?"
  exit 0
}
```

### Step 1: Parse the question

Pull the keywords from the user's question. Drop stop words. Identify intent:

- **Setup-question** ("how do I", "how to", "where do I configure"): bias the search toward `setup/`.
- **Feature-question** ("what is X", "why does X work this way"): bias toward `features/` and `architecture/`.
- **Free-form** ("anything about Y"): search all categories.

### Step 2: Multi-source search

Run grep in parallel across two sources.

**Internal docs:**

```bash
grep -rni --include='*.md' '<keyword>' .internal-docs/
```

Search each keyword separately. Collect top hits by relevance (more keyword matches = higher).

**Codebase (skip vendored Chromium and `node_modules`):**

```bash
grep -rni --include='*.ts' --include='*.tsx' --include='*.js' --include='*.json' --include='*.sh' \
     --exclude-dir=node_modules --exclude-dir=chromium --exclude-dir=.grove \
     '<keyword>' packages/ scripts/ .config/ .github/
```

Read the top 3-5 doc hits and top 3-5 code hits. Do not skim — read the relevant section fully so citations are accurate.

### Step 3: Synthesize answer

Structure the response:

1. **Direct answer.** First sentence answers the question. No preamble.
2. **Steps if applicable.** Numbered list with exact commands.
3. **Citations.** Every factual claim references `path/to/file.md:42` or `path/to/code.ts:117`. Run the voice self-check before printing.

If multiple docs cover the topic at different layers (e.g., a setup runbook and a feature note both mention dogfood profiles), reconcile them in the answer rather than dumping both.

### Step 4: Offer execution (only if commands surfaced)

If Step 3 produced executable commands the user could run, ask:

> Run these for you? (y / n / dry-run)

- **y:** Execute one at a time. For any command that mutates state (writes a file, modifies config, kills a process, deletes anything), ask "run this? <command>" before each. Read-only commands (`ls`, `cat`, `git status`) run without per-command confirmation but still print before running.
- **n:** Skip. Done.
- **dry-run:** Print the full sequence as a `bash` block. Do not execute.

### Step 5: Doc-not-found path

If Step 2 returned nothing useful (no doc hits AND no clear code answer):

1. Tell the user: "No doc covers this. Tangentially relevant files: <list>."
2. Ask: "Draft a short internal-doc outline in this chat?"
3. On yes: write the outline in the response only, using the code-grep findings as context. Do not create files or invoke another skill.

### Step 6: Completion status

Report one of:

- **DONE** — answer delivered, citations verified.
- **DONE_WITH_CONCERNS** — answered, but flag uncertainty (e.g., docs and code disagreed; user should reconcile).
- **BLOCKED** — submodule missing or other pre-flight failure.
- **NEEDS_CONTEXT** — question too vague to search effectively. Ask one clarifying question.

## Citation discipline

Every "X is at Y" claim in the answer must point to a file:line that the skill actually read. Do not approximate. If you didn't read it, don't cite it.

If a doc says one thing and the code says another, surface the conflict explicitly:

> The setup runbook (`setup/dogfood-profile.md:23`) says to delete `~/.cache/browseros/dogfood`, but the actual code path in `packages/cli/src/cleanup.ts:47` removes `~/.local/share/browseros/dogfood`. The doc looks stale. Recommend updating it.

## Common Mistakes

**Skimming and then citing**
- **Problem:** Citation points to a line that doesn't actually contain the claim.
- **Fix:** Read the section fully before citing. If you didn't read line 117, don't cite line 117.

**Executing without per-command confirmation for mutations**
- **Problem:** User says "y" to "run all", skill blasts through `rm -rf`-style commands.
- **Fix:** "y" means "run this sequence with per-mutation confirmations". Per-command y is required for writes.

**Searching only docs, not code**
- **Problem:** Doc says X but code does Y; answer is wrong.
- **Fix:** Always grep both sources in Step 2.

## Red Flags

**Never:**
- Cite a file:line you haven't read.
- Run mutat