professional-brain

# Professional Brain Skill

> 🚀 **New to this? Start with the [5-minute Quickstart](../../BRAIN_QUICKSTART.md)** — a folder + one file, with a worked example. This file is the full reference.

Most skills start cold — you paste the same context every time, and decisions made six weeks
ago lose the *why*. This skill gives the library a **memory**: a plain-markdown `brain/` folder
on disk that skills read before they answer and write to after. No vector DB, no cloud — just
grep-able files you (and Claude) can audit and edit.

This is the **state layer** of an AI teammate. Pair it with the action layer (skills that file
tickets / open PRs) and you get a loop: *recall → do the work → record the decision → review.*

## What This Skill Produces

- A scaffolded **`brain/` folder** with a fixed schema (see below).
- **Provenance-tagged** knowledge — every claim says where it came from and how strong it is.
- Four operations you can invoke: **init**, **ingest**, **recall**, **review**.
- A standing contract other skills follow: *read the relevant brain files first; write durable
  outcomes (decisions, new facts, stakeholder asks) back.*

## Required Inputs

Ask for these only if they aren't already on disk or in the request:

- **Which operation** — `init`, `ingest`, `recall`, or `review` (default: infer from the ask).
- For **ingest**: the artifact (a pasted note, a file path, a transcript) and what it's about.
- For **recall**: the topic or question to answer from memory.
- The **brain location** — default `./brain/` at the project root.

## The Brain Schema

```
brain/
  context.md      # who/what: product, ICP, metrics definitions, voice (supersedes pm-context.md)
  knowledge/      # durable facts — strategy.md, market.md, users.md, org.md
  decisions/      # one file per decision: what, why, alternatives rejected, reopen-when
  hypotheses/     # assumptions: statement, evidence, status (open/validated/invalidated)
  stakeholders/   # one file per person: asks, concerns, comms history
  entities/       # typed objects: features, accounts, experiments — the artifact graph
  source/         # immutable originals (audit trail) — never edited after capture
```

It is Obsidian-vault compatible: open `brain/` as a vault and the links become a graph.

## Provenance Tags (the trust mechanism)

Every fact carries a tag in square brackets so its strength is explicit. Skills must keep the
tag when they reuse a fact, and **downgrade confidence for weak tags**.

| Tag | Means | Strength |
|---|---|---|
| `[data]` | from analytics / a metric / a measured result | strong |
| `[interview]` | from a documented user or customer interview | strong |
| `[external]` | from third-party / market research | medium |
| `[verbal]` | said in a meeting, not independently documented | weak |
| `[hunch]` | informed intuition, no evidence yet | weakest |

Example: `Mobile drives 65% of DAU [data]. Enterprise wants SSO before renewing [verbal].`

## Operations

**init** — Create the folder schema. Migrate an existing `pm-context.md` into `context.md`.
Offer to ingest any artifacts the user already has (Notion export, Jira CSV, notes).

**ingest `<thing>`** — Store the original verbatim in `source/`, then synthesise it into the
right durable file(s) (`knowledge/`, `decisions/`, `hypotheses/`, `stakeholders/`), tagging each
extracted claim with its provenance. Never discard the source.

**recall `<query>`** — Answer from memory. Use the helper script to find matching facts across
the brain, then synthesise an answer that **cites each fact's file and tag**. If memory is thin,
say so rather than inventing.

**record** — The write-back half of the loop (Phase 1). After a skill produces an artifact (or on
demand), extract the **durable outcomes** worth remembering — decisions made, new facts learned,
assumptions surfaced, stakeholder asks — and propose them as a numbered list, each with its
**target section** and **provenance tag**. This is the action surface, so it is **approval-gated
and dry-run by default**:

1. **Propose** — show the records you'd write (section · tag · text). Preview with
   `brain_write.py …` (no `--commit`), which prints exactly what would be appended.
2. **Approve** — the user confirms, edits, or drops items. Never write without a yes.
3. **Append** — write the approved records with `--commit`. Append-only: decisions become a new
   numbered file; everything else appends to its named file. Nothing is overwritten.

Downgrade weak evidence honestly — a conclusion from one call is `[interview]`, a gut call is
`[hunch]`; don't launder it into `[data]`.

**review** — Weekly sweep. Flag: stale hypotheses (open too long with no new evidence),
decisions whose `reopen-when` condition now holds, contradictions between files, and facts that
are only `[hunch]`/`[verbal]` but are being treated as settled. Draft the updates; don't apply
silently.

## Programmatic Helper

`scripts/brain_query.py` (stdlib only) does deterministic recall — it greps the brain for a
query and returns matches with their file and detected provenance tag, so retrieval is
transparent (no embeddings, no guessing).

```bash
# Find what the brain knows about "activation", newest-first, as text
python3 scripts/brain_query.py ./brain "activation"

# JSON for chaining into another step
python3 scripts/brain_query.py ./brain "enterprise SSO" --json
```

Use its output as the grounded evidence set, then synthesise the answer on top — never answer a
recall from outside the brain without saying so.

`scripts/brain_write.py` is the write-back counterpart — it **appends** a provenance-tagged record
(append-only, never overwrites) and is **dry-run by default** so you can preview before committing:

```bash
# Preview what would be written (changes nothing):
python3 scripts/brain_write.py ./brain decisions "Prioritise mobile" --tag data --body "68% of churn is mobile" --source "Q3 analytics"

# Write it after approval:
python3 scripts/brain_write.py ./brain