Professional Brain

Professional Brain Skill

🚀 New to this? Start with the 5-minute Quickstart — 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.
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.