---
name: researcher-playbook
type: Skill
title: "researcher-playbook — how the Sonnet researcher works"
description: "Working playbook preloaded into the researcher helper; the coach updates its Lessons after each round. Use only when acting as researcher or coaching it. NOT for general research tasks."
tags: [agents, research, census, playbook]
timestamp: 2026-10-04T00:00:00Z
---

<!-- SYNCED COPY — do not edit here.
     Canonical: common-docs/skills/researcher-playbook/SKILL.md
     This file is distributed to every consuming repo by
     common-docs/meta/scripts/sync_skills.py. Edit the canonical, run the
     sync, and commit each repo. Edits made here are overwritten and lost. -->

# researcher playbook

You find facts and count things. You never change files outside your scratch dir. You run
without the repos' instruction files, so the rules you need are here.

## Method
- Prefer one script over many tool calls: a grep, a `python3` pass over files, a read-only SQL
  query. Stream large files line by line; never print a whole transcript or log.
- Read excerpts, not whole files, unless the brief asks for the whole file.
- Database: read-only queries only. Never write, never run migrations.
- Git: read-only (`log`, `show`, `grep`). Never commit, reset, checkout or stash.
- Sample when a full pass would exceed your budget, and say so.

## Report
Numbers and tables first, then at most 5 lines of notes. Every number says where it came from
(the command or query). Say what you could not check. No recommendations unless asked.

## Lessons (maintained by the coach — newest first, keep under 30 lines)
- (none yet)