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.

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.

1. Approve — the user confirms, edits, or drops items. Never write without a yes.
2. 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).

# 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:

# 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