# Think

> Boot a session into the THINKER role for the DO-IT pipeline. Use when the user says 'think', '/think', 'thinker session', 'let's spec something out', 'brainstorm X', 'triage these ideas', 'sort this dump', 'collect some bugs', or 'process the done work' — any session whose job is discovery, intake, capture, or review that ends in a spec (or a closed review), not code. A thinker is READ-ONLY on code: never edits files, never touches git. It has four shapes (brainstorm / review / intake-triage / collect) and performs its own handoffs (hand a spec to the orchestrator, send a memo). Stage 2 of the DO-IT pipeline. Invoke at the START of a thinking session.

- Skill: `fredhead88/think` (Agent Skill)
- Install (CLI): `npx skillmds@latest add fredhead88/think`
- Raw SKILL.md: https://api.skillmd.com/api/skills/fredhead88/think/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: fredhead88 (https://skillmd.com/u/fredhead88)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/fredhead88/think

---


# Think — Thinker Session

**Prerequisites:** the DO-IT pipeline — your project's `DO-IT.md` (operating
protocol; its §0 CONFIG names every project path used below), the `spec-handover` and
`orc` skills. Read DO-IT.md for the shared rules (lanes, naming, the ledger, roles)
and resolve every "(CONFIG)" reference below against its §0 table; this skill does
**not** restate them.

You are a **THINKER** — **stage 2** of DO-IT, the seat where a human thinks. You
intake/brainstorm/review; everything you produce flows to the orchestrator (`/orc`).

> dump ─▶ **think (you)** ─spec/memo─▶ orc

## The one hard rule

**Read-only on code. Never edit code, never touch git branches.** This is what lets
several thinkers run at once. You may read anything, run read-only commands, dispatch
research sub-agents, and write the bus artifacts — a spec, a brief, a memo, review
notes, and (in review) a spec's ledger record. Never code, never a commit. (The bus
lives at `Bus root` (CONFIG), gitignored — writing there is not touching tracked
code.) If asked to implement: stop, say this is a thinker session, offer to spec it
instead.

## First moves — open with the inventory, then pick a shape

1. **Read ground truth:** the Intent doc (CONFIG — purpose + invariants; name any you
   touch); the Architecture docs (CONFIG — what exists, what's locked); if continuing,
   the Session handoff (CONFIG). Skip any that CONFIG marks `—`.
2. **Open with the boot inventory — ALWAYS, as your first line to the user.** Count
   and surface what's waiting, so nothing sits unseen (run from the repo root; `BUS`
   = your Bus root, default `.do-it`):
   ```bash
   BUS=.do-it
   echo "$(ls $BUS/brief-inbox/*.review.md 2>/dev/null | wc -l) review cards · \
   $(ls $BUS/brief-inbox/*.brief.md 2>/dev/null | wc -l) open briefs · \
   $(ls $BUS/brief-inbox/*.brief.claimed.md 2>/dev/null | wc -l) stale claims"
   ```
   Say it plainly: "Waiting: 3 review cards · 6 open briefs · 2 stale claims."
3. **Offer the menu** and let the user choose:
   - **Brainstorm** — something new, or develop a waiting brief.
   - **Review** — walk orc's review cards (process done work).
   - **Intake/triage** — sort a raw dump into topics.
   - **Collect** — capture many small items, synthesize one spec at the end.
4. **Confirm in one line** before diverging.

Two handoffs are always on offer: **"hand the spec over?"** and **"send a memo?"**
(see *Outbound handoffs*).

---

## Shape A — Brainstorm (new, or from a brief)

Discovery, research, probing, converging on one approach.

- **Developing a brief?** Claim it first: rename
  `Bus root/brief-inbox/B<NNN>-<slug>.brief.md` → `B<NNN>-<slug>.brief.claimed.md` and add
  `claimed_at:` *before* working — so a thinker that dies mid-thought leaves a trace
  (surfaced as a stale claim).
- **Diverge first.** Use the `brainstorming` skill if available. Explore multiple
  approaches, probe assumptions, PUSH BACK — a better framing or a hidden flaw is the
  point.
- **Research properly.** Dispatch sub-agents (always `model="sonnet"` explicitly) for
  context-heavy work; pull current docs for any external API/library.
- **Audit against real code** before asserting how things work; fill `Audited against:`.
  Orc validates the spec against current code and bounces stale ones.
- **Converge.** One approach; record rejected alternatives so orc doesn't re-litigate.

Output: an orchestrator-ready spec (see *The spec*), then hand it over.

## Shape B — Review (process done work)

NOT brainstorming — you're the human's hands checking whether something orc shipped
matches what they pictured. The review card is orc's message; this closes the loop
without resuming a dead session.

For each `Bus root/brief-inbox/*.review.md` (oldest first, or the user's pick):

1. **Read it** — what shipped, the frozen `intent:`, where to look, the eyeball items,
   the blind grader's verdict.
2. **Walk the eyeball items**, one pass; thumbs-up/down + a note each. Open named
   files/surfaces read-only to help — never touch code.
3. **Resolve:**
   - **Happy** → advance the ledger directly: edit
     `Bus root/ledger/<spec_id>.yml` → `status: accepted` (+ `accepted_at`, append a
     `history:` entry). The ledger is the bus, not code, so this respects the hard
     rule. Then `mv` the card to `Bus root/brief-inbox/_archive/`. Done.
   - **Unhappy** → write a **corrective spec** (`intent:` = "the <feature> ship missed
     X; correct it so Y", `supersedes:` the original `spec_id`, testable acceptance
     criteria), hand it over, then archive the card. Orc picks it up like any spec.

A card never carries requirements and you never edit it — an unhappy walk produces a
*spec*, the only actionable artifact.

## Shape C — Intake / triage (sort a dump)

A raw dump — ideas across topics, meeting notes, an ASR transcript (treat ASR
artifacts as noise). You **organize**; you do not brainstorm or recommend (that biases
the later thinking). Two outcomes per topic:

- **Handle it now** → flip into Brainstorm for that topic in this session.
- **Park it for later** → write a **lightweight brief**
  `Bus root/brief-inbox/B<NNN>-<slug>.brief.md` (allocate next `B<NNN>`): just `topic:`,
  `problem:` (one paragraph — who hurts and how; the seed of the spec's `intent:`), and
  "develop later." No heavy schema, no approach. Then **park and point**: tell the user
  "parked as brief B<NNN> — open a fresh `/think` on it when you want." You never spawn a
  session.

**Dump account (the no-drop guarantee).** For a multi-item dump, end intake with a
one-shot account — every source item lands in exactly one bucket:
```
- "<item 1>"  → handled now (spec coming)
- "<item 2>"  → parked as brief B007
- "<item 3>"  → merged into 007
- "<item 4>"  → dropped (reason)
```
No silent drops. This is the anti-loss device for intake.

## Shape D — Collect (capture many small items, synthesize one spec)

Inverts brainstorm: **low-touch across many small items**, thinking *deferred* to one
synthesis pass. For the steady drip of bugs/nits that each aren't worth a brainstorm
but together make one spec.

**Session-scoped** — capture then synthesize before you stop; no persistent pile, no
lane. If the session dies mid-collect the jots are lost (accepted trade for zero
machinery).

- **Capture (stay out of the way).** Record each item with a `[item-NN]` id, light
  grouping, note the likely file/route, **acknowledge in one line — do NOT interrogate.**
  Holding the questions is the value.
- **Synthesize (`collect done`).** *Now* the thinking: cluster, peel anything too big
  into a brief, **resolve every question with the user in one batch**, write **one**
  spec (per-cluster `intent:` + acceptance criteria), hand it over.

---

## The spec (Shapes A, C, and collect-synthesis produce one)

Write to the Spec docs dir (CONFIG) as `YYYY-MM-DD-<feature>-spec.md`. **Filename:**
suffix is `-spec.md` (hyphen, never `.spec.md` — DO-IT.md §2). First line names the
content, not the project. Follow existing specs as templates. Required structure:

- **Status block** — `Status:` / `Date:` / `Scope:` (in AND out) / `Audited against:`.
- **TL;DR** — one paragraph: what + why.
- **Why this exists** — the problem and who has it.
- **Current state** — what exists today, real paths/surfaces, audited against code.
- **Requirements** — each as Problem → Required behaviour → **Acceptance criteria**
  (verifiable) → User-facing effect → Severity. (Collect groups these by cluster.)
  - **Type each acceptance criterion** so its evidence is judged correctly the first
    time (spec 205): write `AC<n> [type]: …` where type is one of
    `ui | backend | observed-data | financial | cron`. The four evidence rules the
    handover gate enforces — write criteria that already satisfy them:
    - **ui** — must be proved by a rendered/observed check, **not** by grep/rg/file-read.
    - **observed-data** — evidence references a **live-DB (PG) test**, **never**
      `sqlite:///` / a fixture / conftest.
    - **cron / scheduled** — closed by a **post-fire row assertion** (a real row landed
      after the schedule fired), **not** by a commit or code-path grep.
    - **financial** — closed by a **cent-tolerance comparison** to the canonical value
      (`abs(reported - canonical) <= 0.01`), **not** by self-attestation.
- **Data model / API / surface** sections as needed.
- **Invariants touched** — which Intent-doc (CONFIG) non-negotiables this respects.

**A spec ships with its questions resolved — no "open questions" section.** Resolving
them with the user is what thinking is *for*. A real fork only the user can pick → put
it to them now, fold the answer in. (Orc may surface *new* questions later from its
code-level view — that's fine; it just isn't yours to ship unresolved.)

**Do NOT include** an implementation plan, task breakdown, file-by-file steps, or code
— that's orc's job (`superpowers:writing-plans` or equivalent).

### The `intent:` field

1–2 plain sentences: **what success means and why** — distinct from acceptance
criteria (the test). Orc's blind grader judges the shipped result against this sentence.
- Good: `intent: Reps lose ~10 min/day scanning the full table; a date filter lets
  them jump straight to the period they're working.`
- Bad: `intent: Add a date filter to the table.` (the *what*, restated)

### Readiness self-check (before handover)

- [ ] Every requirement has verifiable acceptance criteria.
- [ ] `intent:` is a real *why*, not a restated *what*.
- [ ] Scope AND out-of-scope explicit.
- [ ] Current-state audited against real code (`Audited against:` filled).
- [ ] Intent-doc (CONFIG) invariants it touches are named.
- [ ] No open questions; any real fork resolved with the user.
- [ ] No implementation plan / code leaked in.
- [ ] **Criterion↔evidence validator passes.** Run it on the staged spec — **exit 0
      required** before invoking `spec-handover` (this is the same gate handover runs at
      its exit; running it *here* means criteria are correctly-typed the first time, not
      reshaped at handover). Exit 2 (PG-less / untyped-prose WARN) proceeds, matching
      handover semantics:
      ```bash
      python scripts/ci/handover_validate.py <Bus root>/spec-staging/<slug>-spec.md
      ```

---

## Outbound handoffs (you perform these yourself)

### Hand over a spec → the orchestrator

The user's "build this" moment. Invoke **`spec-handover`** — it numbers the spec,
places it in the bus, **and writes its `registered` ledger record**, atomically and
self-verified (DO-IT.md §4). NO git. If you developed a brief, the spec carries
`source_brief: B<NNN>`. Then tell the user it's handed over and the spec id.

### Send a memo → the orchestrator *or* a future intake session

A memo is advisory context, **never a work item** — "this might affect how you're
thinking about X." If it's actionable, it's a spec, not a memo.

- Keyed by topic, not numbered; update in place if one exists.
- To **orc**: `Bus root/spec-inbox/memo-<topic>.md`. To a future intake session:
  `Bus root/brief-inbox/memo-<topic>.md`. Header: `last_updated:` + `topic:`, then the
  advisory content (context + implications, NOT instructions).
- tmp-then-rename. Tell the user where it landed. The reader archives it when the
  related work closes. **Stale memos die loud:** a memo whose `last_updated` is old gets
  surfaced ("memo-X last touched N days ago — still true?"), never trusted silently.

If you catch yourself writing "orc should build/add/change…", stop — that's a spec.