---
name: professional-brain
description: "Maintain a durable, local markdown memory ('brain') of your product context, decisions, hypotheses, and stakeholders that other skills read from and write back to. Use when asked to set up a brain, ingest notes/artifacts into memory, recall what's known about a topic, log a decision with provenance, or run a weekly brain review. Produces a structured brain/ folder (knowledge, decisions, hypotheses, stakeholders, entities, source) with provenance-tagged facts, plus ingest/recall/record/review operations with approval-gated, append-only write-back."
---

# 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 decisions "Prioritise mobile" --tag data --body "…" --source "Q3 analytics" --commit
```

## The contract for other skills

A brain-aware skill adds a short **"Reads from / Writes to the Brain"** section:

- **Reads:** before producing, pull the relevant files (e.g. `prd-template` reads `context.md`,
  `knowledge/strategy.md`, and any related `hypotheses/` + `entities/`).
- **Writes:** after producing, append durable outcomes (e.g. `meeting-notes` writes each
  decision to `decisions/`, new asks to the relevant `stakeholders/` file), each provenance-tagged.

## Output Format

For **ingest**, confirm what was captured:

### Ingested: [artifact]
- **Source saved:** `source/[file]`
- **Knowledge updated:** `knowledge/[file]` — [facts added, each tagged]
- **Decisions logged:** `decisions/[id]` — [if any]
- **Hypotheses touched:** [statement → status]
- **Open follow-ups:** [anything needing a human]

For **recall**, answer then show your grounding:

### Recall: [query]
[Synthesised answer.]

**Grounded in:**
- `decisions/0003-...md` — "..." `[data]`
- `stakeholders/sarah.md` — "..." `[verbal]`

## Quality Checks

- [ ] Every extracted claim carries a provenance tag
- [ ] The verbatim original is saved in `source/` before synthesis
- [ ] Recall answers cite the file + tag for each fact, and flag thin memory instead of inventing
- [ ] Decisions record the rejected alternatives and a `reopen-when` condition
- [ ] `[hunch]`/`[verbal]` facts are never presented with the confidence of `[data]`/`[interview]`

## Anti-Patterns

- [ ] Do not paraphrase a source into the durable layer without keeping the original in `source/` — the audit trail is the point
- [ ] Do not drop provenance tags when reusing a fact — an untagged claim is an unfalsifiable one
- [ ] Do not answer a recall from general knowledge and present it as something the brain "knows" — say when memory is empty
- [ ] Do not overwrite a decision when it changes — append a new dated entry so the history survives
- [ ] Do not build a vector database or hide memory behind embeddings — the brain stays plain, grep-able markdown a human can read and correct