professional-brain
GitHub维护本地Markdown记忆库，持久化产品上下文、决策与假设。提供初始化、信息摄入、知识召回及定期审查功能，支持溯源标签确保事实可信度，为其他技能提供可审计的状态层。
触发场景
安装
npx skills add mohitagw15856/pm-claude-skills --skill professional-brain -g -y
SKILL.md
Frontmatter
{
"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 — 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, orreview(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:
- Propose — show the records you'd write (section · tag · text). Preview with
brain_write.py …(no--commit), which prints exactly what would be appended. - Approve — the user confirms, edits, or drops items. Never write without a yes.
- 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-templatereadscontext.md,knowledge/strategy.md, and any relatedhypotheses/+entities/). - Writes: after producing, append durable outcomes (e.g.
meeting-noteswrites each decision todecisions/, new asks to the relevantstakeholders/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-whencondition -
[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
版本历史
- a38bc30 当前 2026-07-05 11:41
