Pm Brain

PM Brain — Skill

This skill scaffolds and initializes a PM Brain in the current working directory. The scaffold is deterministic (static files copied as-is from scaffold/). The reasoning is adaptive (loaded from prompts/ per phase).

Architectural split

Behavior evolves independently from structure. Schemas can change without touching reasoning. Reasoning can improve without rewriting schemas.

When to invoke

• Operator runs /pm-brain (or pastes a setup request like "set up a PM Brain here").
• Operator asks to add a PM Brain to an existing directory of PM artifacts.

Do not invoke this skill for routine PM Brain operations after init (ingestion, prep, review). Those are handled by the seeded CLAUDE.md operating manual in the target repo.

Workflow

1. Detect mode

Load prompts/mode-detection.md. Inspect the current working directory. Decide: greenfield (empty), migration (PM artifacts present), or active-repo (working repo — pause and ask).

Announce the detected mode to the operator in one line. For active-repo mode, do not proceed without confirmation.

2. If migration mode

Load prompts/migration.md. Copy (do not move) pre-existing PM artifacts into a source/ folder. Bulk-ingest with epistemic caution. Record cross-document conflicts for the post-scaffold contradictions block.

3. Run the interview

Load prompts/interview.md. Ask the 5 batches (greenfield) or only the gaps not covered by source artifacts (migration). Confirm back what you heard before scaffolding.

4. Copy the scaffold

Copy every file and folder from scaffold/ into the current working directory — including the hidden .claude/ directory (hooks + per-brain settings) and dotfiles (.gitignore, .gitkeep). Preserve structure.

Use the form of copy that picks up dotfiles by default:

• Bash: cp -R scaffold/. <dest>/ (the trailing /. is what makes dotfiles come along)
• PowerShell: Copy-Item -Recurse -Force scaffold\* <dest>\ followed by Copy-Item -Recurse -Force scaffold\.* <dest>\ (the second pass picks up .claude/ and .gitignore; Copy-Item -Recurse scaffold\* alone will silently drop them)

After copying, verify the install by listing the destination — .claude/, .gitignore, and every top-level area folder (hypotheses/, decisions/, source/, ingestion/, knowledge/, stakeholders/, rules/, maintenance/, docs/) must all be present. If .claude/ is missing the hook won't fire on agent writes and schema violations will go uncaught — re-do the copy.

Critical rules:

• Copy in place. The current working directory is the project root. Do not create a nested subfolder.
• Preserve .gitkeep files in empty folders.
• Preserve .claude/hooks/validate_brain_file.py and .claude/settings.json exactly as shipped — they're what makes schema enforcement happen in-loop as the agent edits brain files.
• Do not modify scaffold files at the source. If you need to change a template permanently, edit scaffold/ and re-version the skill.

5. Populate placeholders from interview answers

Walk the copied files and substitute interview answers. Use the full Batch → file mapping in `prompts/interview.md § What the answers feed` — that table is the canonical destination map. Every Batch answer has a documented home; do not silently drop any.

Highlights:

• knowledge/strategy.md — north-star metric, priorities (Batch A). Non-goals start empty if PM didn't volunteer them; flag in next moves.
• knowledge/product/features/<slug>.md — one file per active feature (Batch C Q1), populated from the feature schema.
• knowledge/product/roadmap.md — Now / Next sections from Batch C.
• stakeholders/<slug>.md — one file per stakeholder (Batch B Q1); influence + friction tagged from Batch B Q2.
• knowledge/org/team.md, knowledge/org/rituals.md, knowledge/org/tools.md — from Batch B Q3 + Batch D Q1.
• knowledge/market/landscape.md and/or trends.md — from Batch D Q3.
• rules/discovery.md, rules/data.md — from Batch D Q1-2.
• CLAUDE.md § Operating preferences — autonomy mode + maintenance cadence (Batch E Q1-2).
• CLAUDE.md § Off-limits — Batch E Q3.

For schema-templated files: copy the schema structure as-is, fill in what the interview provided, leave the rest with the placeholder comments intact.

Provenance: every populated field should be traceable back to either a Batch question or a source artifact. When a value came from a source artifact, link to it inline.

6. Post-scaffold self-test

Load prompts/post-scaffold.md. Run:

1. Routing self-test (can you route each of the 4 ingestion modes?). 2. Link verification (walk every internal markdown link, fix broken ones). 3. Surface 3-5 immediate next moves. 4. Surface 1-3 contradictions found during scaffolding (or say explicitly "none found"). 5. Print the self-test receipt.

7. Commit

• Run git rev-parse --is-inside-work-tree in the current working directory.
• If already a repo: stage all scaffolded files. Single commit titled feat: initialize PM brain.
• If not a repo: git init in the current working directory, then stage and commit.
• Never push remotely. PM controls publication.
• If any git step fails, surface the error and stop. No destructive recovery.

8. Hand off

Lead with the habit loop, not the scaffold. See prompts/post-scaffold.md § 7 for the exact ordering:

1. The three habit actions (ingest today / prep next 1:1 / /review Friday) — specific slug + day. 2. 1-3 contradictions surfaced (or "none found"). 3. 2-3 scaffold gaps worth filling. 4. One paragraph on what was built.

Do not lead with a folder map or "your scaffold is ready." Lead with what produces value in the next 24 hours.

Then stop and wait for the operator's first real task.

Anti-patterns

• Regenerating scaffold content. The whole point of scaffold/ is that it's deterministic. If you find yourself rewriting CLAUDE.md or a schema from scratch during init, stop — copy from scaffold/ instead.
• Creating a nested `pm-brain/` subfolder. The current working directory is the project root.
• Skipping the self-test. Broken links are memory corruption, not cosmetic.
• Inventing contradictions. If migration mode found no genuine conflicts, say so. Don't fabricate.
• Pushing remotely. PM controls when and where this gets published.

Files in this skill

pm-brain-skill/
├── SKILL.md              # This file. Orchestration.
├── scaffold/             # Deterministic static structure. Copy as-is.
│   ├── .claude/          # Per-brain Claude Code config (hooks + settings)
│   │   ├── hooks/
│   │   │   └── validate_brain_file.py   # PostToolUse schema validator
│   │   ├── commands/     # Slash commands shipped with the brain
│   │   └── settings.json # Wires the hook to Write|Edit
│   ├── .gitignore
│   ├── CLAUDE.md
│   ├── INDEX.md
│   ├── README.md
│   ├── knowledge/        # strategy, product, users, market, org
│   ├── stakeholders/
│   ├── hypotheses/
│   ├── decisions/
│   ├── rules/
│   ├── source/           # Verbatim audit anchors
│   ├── ingestion/        # Synthesized records
│   ├── maintenance/
│   └── docs/
└── prompts/              # Adaptive reasoning. Loaded per phase.
    ├── mode-detection.md
    ├── migration.md
    ├── interview.md
    └── post-scaffold.md

Interview

Run before scaffolding. Ask in batches of 3–4 questions, not one-by-one. Tone: short, direct, no lecturing.

In migration mode, skip batches already covered by source artifacts and ask only the unknowns. Tell the PM what you already know before asking what you don't.

Batch A — Context

1. Company name, product, and one-line description of what it does. 2. Stage (pre-PMF / scaling / mature) and rough scale signal (users, ARR, team size — whatever they know). 3. Their role scope: which surfaces / squads / domains do they own? 4. Top 3 strategic priorities for the next 1–2 quarters (rough is fine; we'll refine).

Batch B — People

1. Name + role of their top 5–10 stakeholders (manager, eng lead, design lead, key execs, key customers if applicable). 2. Which 2–3 of those are highest-friction or highest-leverage right now? 3. Cadence — any standing 1:1s / rituals worth encoding?

Batch C — Work in flight

1. What features / initiatives are active right now? (list 2–6, slug-ify them) 2. What's the next big bet being scoped but not started? 3. Any recent shipped thing they're still measuring?

Batch D — Inputs

1. What data sources do they touch weekly? (analytics tool, interview transcripts, support tickets, sales calls, Slack channels, etc.) 2. Do they run customer interviews? If yes, roughly how often, and where do transcripts live? 3. What competitor / market signals do they track?

Batch E — Operating preferences

1. Autonomy level: should the system act and tell (default), or propose and wait? Recommend "act and tell" for anything reversible. Stored in CLAUDE.md § Operating preferences § Autonomy mode. 2. Maintenance cadence preference: weekly review? on-demand only? both? Stored in CLAUDE.md § Operating preferences § Maintenance cadence. 3. Anything explicitly off-limits beyond the defaults? Defaults: avoid PII (addresses, phone numbers, financial details, government IDs, medical info). Synthetic names, work emails, and organizational context are allowed. Stored in CLAUDE.md § Off-limits.

After the interview

1. Summarize back what you heard in 6–10 bullets. 2. Surface contradictions. Examples: "You said pre-PMF but listed 8 active features — which is real?" "Your top stakeholder is high-friction and you said cadence is monthly — is that the right rhythm?" 3. Confirm before scaffolding. Do not move on without explicit confirmation.

What the answers feed

Keep provenance: every populated field should be traceable back to a specific Batch question or a source artifact. If a Batch answer has no clear home, flag it in the post-scaffold "immediate next moves" rather than silently dropping it.

Provenance vocabulary, not provenance workflow

When you write claims into hypotheses, insights, or decisions, tag each row with a provenance marker from the enum in hypotheses/_SCHEMA.md. Claims born in this interview (no artifact behind them) are legitimate inputs — tag them (stakeholder-verbal, <PM>, <date>) or (chat, no artifact) rather than fabricating an ingestion record. The auditability promise is "every claim wears its source," not "every claim went through synthesis."

Migration mode

Triggered when the working directory already contains PM artifacts. Run this before the interview.

1. Preserve originals — COPY, don't move

Create source/ at the project root. Copy pre-existing PM artifacts into it. Do not move them. Leave the originals where the PM put them.

Rationale: moving files mutates the user's working layout. If their notes live next to active work (specs, repos, drafts), mv can break links and disrupt their habits. Copy is reversible; move is not. Trust must not be spent here.

Rules:

• Default: copy. Use cp -R / Copy-Item -Recurse. Never mv / Move-Item without explicit confirmation.
• `source/` is the canonical immutable copy. Once an artifact is in source/, treat it as read-only for the rest of the system. Knowledge promotion cites this copy.
• Originals stay put. The PM can delete originals later when they're confident — but the skill does not assume that authority.
• Confirm before bulk operations. If you're about to copy more than ~10 files or anything larger than ~1 MB total, list what you're copying and confirm in one line: "About to copy N files (X MB) into source/. Proceed?"
• Never overwrite. If source/ already exists with content, pause and ask. Do not silently merge.

Everything downstream cites the source/ copy. This is the provenance chain.

2. Bulk-ingest with epistemic caution

Treat uploaded materials as claims, not truth. Real corporate artifacts are often stale, political, abandoned, aspirational, or contradictory.

For each artifact:

• Date-tag every claim with the artifact's date when available. Older claims get lower default confidence.
• Cross-reference before promoting anything into durable knowledge/. A single roadmap deck does not silently rewrite strategy. Compare against other artifacts first.
• Single-source claims stay flagged. Stakeholder concerns asserted in one doc but absent elsewhere stay flagged as single-source until corroborated.
• Preserve conflicts as tensions. When artifacts conflict (two strategy docs, two roadmaps, two persona definitions), preserve the conflict as a tension in strategy.md § Tensions rather than picking a winner. Record both sides with provenance.

Synthesized output lands in ingestion/ first. Promotion into knowledge/ follows the standard memory promotion bar (recurring, decision-relevant, strategy-relevant, observed across sources, useful beyond one session) — see CLAUDE.md § Memory promotion.

2a. Per-artifact ingestion records are scoped to ONE artifact — HARD RULE

Each ingestion/<kind>/<date>-<slug>.md is the synthesis of its matching `source/<kind>/<date>-<slug>.md` and nothing else.

Do NOT, inside a per-artifact ingestion record:

• Cross-reference other artifacts ("this conflicts with the CFO email…").
• Note tension with other artifacts ("contradicts the Q4 strategy doc on compliance…").
• Compare counts or synthesize across sources ("2 of 2 interviews this cycle say…").
• Pull in claims that did not originate from the matching source.

Why this matters: mixing collapses the audit trail. A reader looking at the ingestion record for artifact X cannot tell which claims came from X versus which were imported from comparing X to artifact Y. The synthesis layer becomes lossy in the same place it was supposed to be sharp.

Where cross-artifact observations go instead: the contradiction list in step 4, surfaced in the post-migration tension-surfacing turn. That is the only place cross-artifact synthesis lives during migration. NOT inside per-artifact ingestion files.

DON'T (inside `ingestion/strategy/2025-q4-strategy.md`):

> Compliance-friendly: NO. The Q4 doc explicitly stakes the anti-compliance position.
> ⚠️ **Tension flag:** This conflicts with the Globex interview (2026-04-03), where Reina
> asked for audit trails — a compliance-adjacent ask. Surface in tension review.

DO (inside `ingestion/strategy/2025-q4-strategy.md`):

> Compliance-friendly: NO. The Q4 doc explicitly stakes the anti-compliance position.
> (No cross-artifact commentary here — the strategy ingestion faithfully summarizes the
> strategy doc only. Any cross-artifact tension lives in the contradiction list — step 4.)

Pre-save self-check before writing any `ingestion/<kind>/<file>.md`:

1. Does this file contain ANY claim, reference, or comparison that did not appear in its matching source/ file? If yes — remove it. Route it to the contradiction list. 2. If you find yourself wanting to write the words "conflicts with", "contradicts", "tension with", "in contrast to", "differs from" (etc.) inside an ingestion record — STOP. Move that thought to the contradiction list.

3. The cognition pipeline

source/            →   ingestion/        →   knowledge/      (durable observations, synthesized facts)
(immutable copy)       (working memory)      hypotheses/     (testable beliefs)
                                             decisions/      (committed choices)
                                             stakeholders/   (people state)

Promotion is parallel. The same ingested artifact can land evidence in multiple durable areas at once — knowledge/ is not the only destination. A single customer interview often updates knowledge/users/insights.md, strengthens evidence in a hypotheses/<feature>.md, and logs a touchpoint in stakeholders/<slug>.md. Sometimes it drafts a decisions/ entry too.

Every claim in any durable area carries a provenance tag from the enum in hypotheses/_SCHEMA.md. Most claims will tag back through ingestion/ to a source/ artifact — that's the canonical chain. But the system enforces vocabulary, not workflow: a claim heard verbal-only from a stakeholder, or inherited from PM intuition, is legitimate as long as it's tagged honestly. The audit promise is "every claim wears its source," not "every claim was synthesized."

Note: source/ is a copy of what the PM gave us. Their originals still live wherever they put them. Promotion cites the source/ copy by relative path, not the original location.

4. Build the contradiction list

While ingesting, accumulate a list of cross-artifact conflicts. Look specifically for:

• Two strategy docs disagreeing on priorities or non-goals.
• Two roadmaps with different active features.
• Two persona definitions for the same user type.
• A stakeholder concern in one doc that contradicts a decision in another.
• Metrics that appear with different definitions or values across docs.

This list feeds the post-scaffold summary as the highest-leverage open items.

5. Narrow the interview

After ingest, you already know much of what the 5-batch interview would ask. Open the interview by telling the PM what you already have:

"I see your strategy doc, 4 stakeholders, 2 active features, and 2 customer interviews. I don't see metrics values, your discovery cadence, or your data sources — those are what I need from you."

Then run only the parts of the 5-batch interview that source materials don't cover. Skip batches that are fully covered. Ask only the gaps in batches that are partially covered.

See interview.md for the full batch list.

Mode detection

Inspect the current working directory. Decide which mode you're in. Be conservative. If anything looks unsafe, pause and ask before touching the layout.

Greenfield mode

The directory is effectively empty. None of:

• PRDs, strategy docs, decks
• Interview transcripts, research notes
• Roadmap files, spec docs
• Prior .md files describing the product, strategy, team
• Substantial subfolders that look like an existing knowledge base

A .git/, a stray README.md, or empty subfolders do not count as PM artifacts.

Action: announce greenfield mode. Run the full 5-batch interview (see interview.md).

Migration mode

The directory contains pre-existing PM artifacts (decks, transcripts, strategy docs, prior notes) and otherwise looks like a notes/working folder.

Action: 1. Announce migration mode. List what you found in one line: "I see X files matching PM artifact patterns (decks, transcripts, strategy docs, prior knowledge)." 2. Load migration.md and run the migration workflow before the interview. Default to copy, never move.

Active-repo mode — pause and ask

The directory looks like an active working repository, not a notes folder. Signals (any of):

• package.json, pyproject.toml, Cargo.toml, go.mod, pom.xml, Gemfile, or other build/manifest files at the root.
• src/, lib/, app/, tests/, node_modules/, vendor/, target/, dist/, build/ folders.
• .git/ with non-trivial history (commits older than today, multiple authors, remotes configured).
• CI config (.github/workflows/, .gitlab-ci.yml, circle.yml, etc.).
• Dockerfile, docker-compose.yml, infra-as-code.
• Substantial source code in any language.

Do not scaffold without confirmation. Pause and ask:

"This directory looks like an active working repository (detected: <list signals>). I can:

(a) scaffold the PM Brain here alongside the existing files (recommended only if you intend to keep PM context with this project),

(b) abort — you cd into a different directory and re-run.

Which one?"

Do not proceed until the operator answers. Never silently scaffold over an active repo. The skill does not change directories on its own; the operator picks the project root by where they invoke it.

Edge cases

• Directory has artifacts but they're clearly someone else's project (a package.json for a React app, but no PM artifacts): treat as active-repo mode and ask.
• Mixed: the user pasted a setup request with attached files but the directory is empty. Treat the pasted artifacts as migration inputs even though the FS is empty. Confirm with the PM before copying anything into source/.
• Ambiguous: ask one clarifying question before proceeding. Mode choice changes the whole workflow downstream — don't guess.

Announce mode in one line

Greenfield:

"Greenfield mode. Empty directory. Running the full 5-batch interview."

Migration:

"Migration mode. Found 1 strategy doc, 3 interview transcripts, 2 decks, 4 prior stakeholder notes. I'll copy these into source/ (originals stay put) and run a narrowed interview."

Active-repo (after operator confirms (a)):

"Scaffolding PM Brain alongside the existing repo. Migration: found N PM artifacts mixed in with source code — I'll copy only PM-pattern files into source/, ignoring code/build directories."

Post-scaffold

Run after the scaffold has been copied and placeholders populated.

1. Routing self-test

Read INDEX.md, CLAUDE.md, and .claude/commands/INDEX.md. Confirm two things resolve cleanly:

1a. The 4 ingestion shapes route correctly

These are what /ingest infers from the artifact:

• Customer interview → source/interviews/, ingestion/interviews/, knowledge/users/insights.md, relevant hypotheses/<feature>.md.
• Meeting / 1:1 → source/meetings/, ingestion/meetings/, stakeholders/<slug>.md, draft decisions/ when a decision was made.
• Market intel → source/market/, ingestion/market/, knowledge/market/competitors/ or trends.md, possibly strategy.md § Tensions.
• Ad-hoc → ingestion/adhoc/, routed to the right durable area in-session, never parked.

1b. The 6 commands resolve to their spec files

For each, confirm the spec exists and the loaded/updated paths in the spec match real scaffold paths:

• /ingest → .claude/commands/ingest.md
• /prep → .claude/commands/prep.md
• /review → .claude/commands/review.md
• /ideate → .claude/commands/ideate.md
• /risk → .claude/commands/risk.md
• /plan → .claude/commands/plan.md

If a spec references a path that doesn't exist in the scaffolded brain, that's a bug. Fix it before declaring done. If routing is unclear for any ingestion shape or command, the seeded files have a bug. Fix it before declaring done.

2. Link verification

Walk every relative markdown link in the scaffolded files. Resolve each path against the filesystem. Fix broken links.

Common failure mode: miscounting ../ depth when linking across knowledge/, stakeholders/, hypotheses/, decisions/. The link layer is the provenance chain — broken links are memory corruption, not cosmetic.

2b. Coverage checks (beyond link existence)

Link walking proves a link points somewhere. It does not prove the right links exist. Run these coverage checks:

• Feature → hypothesis. For every feature file in knowledge/product/features/ with a status in {scoping, building, shipping, measuring}, expect a corresponding hypotheses/<slug>.md. Missing → surface as a next move, not a blocker.
• Hypothesis ↔ feature. Every hypotheses/<slug>.md should reference its feature file in ## Meta § Feature. Orphans → flag.
• Promoted hypothesis → decision. Every hypothesis with status promoted should have a corresponding decision file linking back to it. Missing → draft the decision.
• Decision → hypothesis (where applicable). Every decision that resolves a bet should link the originating hypothesis under ## Linked § Hypotheses. Missing link → flag.
• Stakeholder touchpoints → ingestion. Every touchpoint-log entry in stakeholders/<slug>.md that came from a meeting should link to its ingestion/meetings/<file>. Standalone touchpoints (no ingestion artifact) are fine; orphan links (pointing at missing files) are not.
• Feature → stakeholders affected. Every feature file's ## Linked § Stakeholders affected should list at least one stakeholder, or be marked TODO: none yet identified. Empty without acknowledgment → flag.

Coverage gaps are surfaced as immediate next moves (§ 3), not as scaffolding failures. The point is to make missing wiring visible, not to block.

3. Surface the habit loop (primary) + scaffold gaps (secondary)

The day-one risk isn't an incomplete scaffold. It's the operator never returning to use the system. Frame next moves as habit-forming actions first, not scaffold completion.

Three habit actions — lead with these

Always surface these three first, in this order:

1. Ingest one real artifact today. "Paste your most recent customer interview / meeting notes / competitor screenshot. I'll show you what the system does with it." 2. Prep your next conversation. "Before your next 1:1 with <highest-influence stakeholder slug>, run /prep <slug>. I'll surface what to ask." 3. Run `/review` on Friday. "The maintenance sweep is what keeps this system alive past month three. Set a recurring calendar reminder for Friday afternoon."

These are not optional. The system dies when these don't happen.

Then: 2-3 scaffold gaps (secondary)

After the three habit actions, surface a small number of concrete completion gaps. Specific, actionable, never more than 3:

• "Your top stakeholder <slug> has no concerns logged. Propose 4 from the interview, you confirm."
• "Feature <slug> is shipped but has no post-ship hypothesis file. I can draft it from your metrics data when you have a moment."
• "Strategy section Non-goals is empty. This is the highest-leverage thing to fill in next."

If there are more than 3 gaps, pick the three highest-leverage. Don't dump a punch list — that's how operators get overwhelmed and abandon the system.

4. Surface contradictions (required)

List 1–3 contradictions found during scaffolding, with multi-source evidence per item. These are typically the highest-value items on day one.

Look specifically for:

• Conflicting stakeholder mandates (one wants growth, another wants trust gates).
• Signals pointing opposite ways (adoption metric up, qualitative trust down).
• Strategy vs. observed work (strategy says one thing; active features point elsewhere).
• Inter-document conflicts in migration mode (two strategy docs, two roadmaps, two persona definitions).

Format each as:

• Signal: what was observed
• What it tensions: which strategic claim or other signal it conflicts with
• Where it lives in the brain: strategy.md § Tensions § Tn, stakeholder file, hypothesis file

If no genuine contradictions were found, say so explicitly. Do not invent.

5. Self-test receipt

Print a 3-5 line visible block that proves the self-test ran:

Self-test receipt:
- Ingestion shapes routed: 4/4.
- Commands resolved: 6/6 (ingest, prep, review, ideate, risk, plan).
- Links walked: 47. Broken: 3. Fixed: 3.
- Coverage checks: 6/6 categories scanned. 2 gaps flagged as next moves.
- TODO fields (PM-fillable): 12 across 8 files (see list).
- Auto-maintained fields left blank: 9 (correct).
- Contradictions surfaced: 2.

This block goes in the final message to the PM, not just internal reasoning.

6. Commit

• Run git rev-parse --is-inside-work-tree in the current working directory (not any subfolder).
• If yes: stage all scaffolded files. Single commit titled feat: initialize PM brain.
• If no: git init in the current working directory, then stage and commit as above.
• Critical: git init must run in the working directory where the skill was invoked, not inside any scaffolded subfolder. The provenance chain (source/ → ingestion/ → knowledge/) must be inside the same repo.
• Never push remotely. The PM controls when and where this is published.
• If any git step fails, surface the error and stop. No destructive recovery.

7. Hand off

Final message to the operator. Order matters:

1. The three habit actions (do this today / this week / Friday). Specific stakeholder slug, specific feature, specific day. 2. 1–3 contradictions surfaced (or explicit "none found"). These are the highest-leverage open items. 3. 2–3 scaffold gaps worth filling soon — no more. 4. One paragraph on what was built.

Do NOT lead with "your scaffold is ready" or a folder map. Lead with the action that produces value in the next 24 hours.

Then stop and wait for the operator's first real task.

/decide

Log a decision. Drafts a complete decision file from the existing evidence trail and surfaces it for PM sign-off.

Input

A decision slug (/decide ship-weekly-digest) or a one-line decision framing (/decide "kill auto-categorize, ship receipt-matching instead"). If a hypothesis is being resolved by the decision, include or infer its slug: /decide ship-weekly-digest --resolves H-V1.

Loads

• decisions/_SCHEMA.md — load before writing the decision file
• hypotheses/<slug>.md for any hypothesis the decision resolves (the decision MUST link back to it)
• knowledge/strategy.md — priorities, non-goals, tensions (does this decision honor strategy? create new tension?)
• Recent ingestion/ and source/ referenced as evidence (every Evidence row in the decision file needs a provenance tag pointing at a real artifact)
• stakeholders/<slug>.md for any stakeholder named in the decision (Naomi confirmed Q3, Helena flagged budget, etc.)
• decisions/INDEX.md to check for prior decisions this one supersedes or depends on

Updates

• decisions/YYYY-MM-DD-<slug>.md — created with the full schema: status (pending or decided), context, decision, evidence rows (each tagged), explicitly NOT doing, stakeholders signed off, reversal condition (observable + specific), remaining ambiguities. Drafted, not committed.
• decisions/INDEX.md — add under ## Pending if status: pending, otherwise under ## Recently decided
• hypotheses/<slug>.md — if the decision resolves a hypothesis, mark that hypothesis promoted (if decision validates it) or demoted (if decision goes the other way), with a Resolution row linking to the new decision file
• hypotheses/INDEX.md — reflect the hypothesis status change

Hard constraints:

• COUNT-THE-TAGS before saving — every Evidence row + every "Explicitly NOT doing" row carries a provenance tag from the enum in hypotheses/_SCHEMA.md. Orphan rows fail the audit.
• Reversal condition is mandatory and observable. "If things change" / "if market shifts" / "if we get pushback" are not acceptable. The condition must name a specific, measurable signal (a metric crossing a threshold, a stakeholder explicitly withdrawing support, a competitor shipping a specific feature). The audit check all_decisions_have_reversal_condition rejects vague reversal conditions.
• Commentary, gaps, and "things we don't yet know" go under ## Remaining ambiguities, NOT under ## Evidence. Aggregation/meta rows ("N=3 customers, mixed sentiment") are not evidence — they go under Remaining ambiguities too.
• Default to status: pending unless the PM explicitly said "this is decided." Pending invites stakeholder sign-off; decided implies the choice has been made and is being recorded for the audit trail.

Surfaces

• The decision file path + a 1-line summary of what was committed (or proposed if pending)
• Which hypothesis (if any) this resolves and how its status flipped
• The reversal condition, in one line
• Any stakeholder named in the file who has NOT yet been touched on this decision — explicit "you should loop in X before this lands" flag
• Any contradiction with strategy or with a prior decision — surfaced, not silently smoothed
• The PM-sign-off prompt: "Apply this decision as drafted? (y / edit / no)"

/hypothesize

Generate or refresh hypotheses for a feature. Works pre-ship (proactive, organized by the 5 risk areas) or post-ship (data-derived from analytics / interviews / churn — "why is retention dropping?"). Same schema either way; the Origin field distinguishes them.

Input

A feature slug (/hypothesize weekly-digest), a problem statement (/hypothesize "mid-market onboarding drop-off"), or an existing hypothesis file to refresh (/hypothesize hypotheses/weekly-digest.md).

If the feature has no existing file yet, the command creates one. If it does, the command refreshes — opening new candidate hypotheses where evidence has accumulated, and surfacing any existing ones whose evidence has gone stale.

Loads

• hypotheses/<slug>.md if it exists (refresh mode)
• knowledge/product/features/<slug>.md (if the feature exists in product knowledge)
• knowledge/strategy.md — non-goals, priorities, north-star (so the hypotheses don't violate strategic constraints)
• knowledge/users/insights.md and any relevant personas.md / segments.md
• Recent ingestion/ filtered to this feature / problem space (interviews, meeting notes, market signals — last ~10 entries)
• decisions/ filtered to ones that constrain or invalidate hypothesis space for this feature
• hypotheses/_SCHEMA.md — load before writing or refreshing any hypothesis file

Updates

• hypotheses/<slug>.md — created (new feature) or appended (refresh mode). Each new hypothesis carries: belief, origin (proactive | data-derived from <source>), confidence (always start at low for new hypotheses), evidence-for / evidence-against (tagged), open questions, test plan, decision trigger, status (active).
• hypotheses/INDEX.md — add the file under the appropriate status section if newly created; update status if a hypothesis flipped state.
• Maintenance log entry — one-line note that hypotheses were generated/refreshed for <feature> with a count of new and modified.

Hard constraints:

• Never promote a hypothesis at creation time. New = active / low confidence. Promotion requires evidence accumulation through subsequent /ingest cycles.
• Cover all 5 risk areas (value, usability, feasibility, viability, other) for pre-ship hypotheses, even if the answer for some areas is "no risk identified, monitor." Silent gaps are themselves a risk.
• Every Evidence-row tag follows the provenance enum in hypotheses/_SCHEMA.md. If you're generating a hypothesis from intuition with no external signal yet, use (intuition, PM, <YYYY-MM-DD>) honestly — do not fabricate an ingestion record.
• Aggregation/meta rows ("N=3 interviews, mixed sentiment") go under Open questions / caveats:, never under Evidence.
• `hypotheses/INDEX.md` must be updated in the SAME turn as any new hypothesis file write. Add a row under the appropriate status section (Active / Partially-validated / Promoted / Demoted / Archived). A new hypothesis file without an INDEX row is half-saved — the next session's retrieval will miss it. Do this BEFORE returning the routing summary.

Surfaces

• Count of new hypotheses opened, grouped by risk area
• Count of existing hypotheses refreshed (evidence added, status changed, or marked stale)
• The 1-2 hypotheses with the strongest evidence (most likely to promote next cycle) named explicitly
• Any risk area where NO hypothesis exists — explicit gap flag
• One open question if a hypothesis touches a strategic non-goal or contradicts a recent decision

/ideate

Generate solution directions for a problem, grounded in what the brain already knows. Not a brainstorm. A synthesis.

Input

A problem statement, an opportunity, or a knowledge/users/insights.md § <theme> reference. Example: /ideate onboarding drop-off in mid-market.

Loads

• knowledge/strategy.md (priorities, non-goals, north-star)
• knowledge/users/insights.md and any matching personas.md / segments.md
• Active hypotheses/ files in the same area
• Recent decisions/ that constrain or invalidate options
• knowledge/market/competitors/ and trends.md for adjacent moves
• rules/discovery.md and rules/prioritization.md if present

Updates

Drafts only. Nothing committed at call time.

• A draft ingestion/adhoc/<date>-ideate-<slug>.md capturing the session
• Hypothesis candidates queued under hypotheses/<slug>.md § Candidates (PM confirms before promotion)

Surfaces

• 3-7 solution directions, each tagged with the evidence supporting it (insight, hypothesis, decision, or market signal)
• For each direction: which strategy priority it serves, which non-goal it might violate, which active hypothesis it would test or contradict
• 1-2 directions explicitly marked as off-strategy if surfaced, so the operator can decide whether to pivot strategy or reject the direction
• The thinnest viable next step for the top 2 (a discovery question, an experiment, a competitor study)

Anti-pattern: do not generate directions that ignore the strategy doc or the non-goals. If the evidence forces an off-strategy direction, surface the tension instead of swallowing it.

Commands

Operator-facing verbs. Each command is a thin spec: input, files to load, files to update, what to surface. The agent reads the spec, executes against the brain, and reports back per CLAUDE.md § Operating loop.

Conventions

• Every command loads before acting and updates after. No blind drafting.
• Every command ends by surfacing 2-4 bullets per CLAUDE.md § Operating loop § 7.
• /prep is read-only at call time. The operator runs /ingest after the conversation. All other commands draft or update files per autonomy mode.
• Commands respect CLAUDE.md § Operating preferences § Autonomy mode. Under propose and wait, drafts are presented for approval before saving.
• All file paths in each spec are relative to the brain root.

Scope: what these verbs are not

PM Brain is the memory and reasoning layer. PM workflows (JTBD interview structure, Kano analysis, RICE prioritization, opportunity solution trees, experiment design templates) belong in workflow-specific skills, not here. A workflow skill produces an artifact; PM Brain ingests it via /ingest and routes the evidence into durable layers. The split keeps each system thin.

/ingest

Route a new artifact into the brain. Four shapes, one verb.

Input

A pasted transcript, a file path, a screenshot, a URL, or a free-form note. The agent infers the shape:

• interview — customer call, user research session, sales call with prospect signal
• meeting — 1:1, exec review, roadmap discussion, kickoff, retro
• market — competitor article, screenshot, tweet, changelog, analyst note
• adhoc — anything else worth capturing that doesn't fit the other three

If shape is ambiguous, ask one question. Don't guess.

Loads

• knowledge/strategy.md
• The matching area for the inferred shape: knowledge/users/insights.md (interview), stakeholders/<slug>.md (meeting), knowledge/market/ (market), nothing extra (adhoc)
• Active hypotheses/<slug>.md files that the artifact might touch
• Last 3 entries in ingestion/<shape>/ for pattern comparison

Updates

• source/<shape>/<date>-<slug>.md — immutable copy of the original artifact
• ingestion/<shape>/<date>-<slug>.md — observations tagged (observation / interpretation / hypothesis / assumption / decision)
• One or more durable destinations per the cognition pipeline: knowledge/, hypotheses/, decisions/, stakeholders/
• Maintenance log if structural (a new persona, a new competitor, a new stakeholder)

Promotion to durable layers follows the memory promotion bar in CLAUDE.md § Memory promotion. One-off observations stay in ingestion/ until they accumulate.

Surfaces

• Where the artifact landed (source, ingestion, and which durable destinations)
• 1-3 themes promoted, or "no promotion this round"
• Any contradictions with prior evidence (preserved, not resolved)
• One open question if the operator's judgment is needed

/plan

Turn a new team objective into a concrete plan: what we know, what we assume, who to interview, which hypotheses to open, which experiments to run, what decision would unlock execution.

Input

An objective statement. Example: /plan reduce onboarding drop-off by 20% in Q3.

Loads

• knowledge/strategy.md (priorities, non-goals, north-star, tensions)
• knowledge/product/metrics.md (current values, definitions)
• knowledge/product/features/ filtered to ones touching the objective
• knowledge/users/insights.md, relevant personas.md / segments.md
• All active hypotheses/ in the area
• decisions/ filtered to relevant prior commitments
• stakeholders/ filtered to people who'd influence or block the plan
• rules/discovery.md, rules/prioritization.md, rules/data.md

Updates

• A draft ingestion/adhoc/<date>-plan-<slug>.md capturing the planning session
• hypotheses/<slug>.md — drafts for any value/usability/feasibility/viability/other risk that needs testing (status: candidate)
• decisions/<date>-<slug>.md — drafts for go/no-go points (status: pending)
• stakeholders/<slug>.md § Open asks — drafts for the alignment conversations the plan implies

Nothing committed without operator confirmation per autonomy mode.

Surfaces

Six blocks, in this order:

1. What we already know — citations to insights, hypotheses, decisions, metrics 2. Assumption vs evidence — explicitly tagged, with provenance for each 3. Who to interview — segments, personas, specific named users; recent coverage gaps 4. Hypotheses to open — across the 5 risk areas, with the test for each 5. Experiments to run — sequenced, with success criteria and what would invalidate 6. Decision points — the go/no-go moments and what evidence would unlock each

Plus:

• Constraints from strategy.md § Non-goals that bound the plan
• Stakeholder alignment conversations the plan requires (linked to /prep)
• One paragraph on what would make the plan unwise (so the operator can falsify it early)

/prep

Surface what to ask, raise, or watch for in an upcoming conversation.

Input

Stakeholder slug (/prep acme-ops), meeting name (/prep weekly-exec-review), or meeting type (/prep 1:1). If multi-attendee, pass the slug list or the meeting name.

Loads

• stakeholders/<slug>.md for each attendee
• decisions/ filtered to ones affecting them or the topic
• Active hypotheses/<slug>.md they care about or own
• Last 3 ingestion/meetings/<slug>-*.md with this person or this meeting type
• knowledge/strategy.md § Tensions if any tension intersects their concerns

Updates

Nothing at call time. /prep is read-only. After the meeting, run /ingest on the notes.

Surfaces

• Their open asks and last unresolved concern (with date)
• Decisions made since last touch that affect them
• Active hypotheses where their judgment matters
• One sentence on what changed in their world since last 1:1
• 3-5 suggested questions or talking points
• One flag if Last touched is older than 3 weeks for a high-influence stakeholder

/review

The weekly maintenance sweep. Six checks. Produces a dated report and edits files directly where confidence is high.

Input

None, or an optional scope (/review hypotheses, /review stakeholders) to run a single check.

Loads

• CLAUDE.md (operating principles, autonomy mode, memory promotion bar)
• docs/system-evolution.md (the 8 failure modes the sweep is designed to catch)
• All durable areas in scope: knowledge/, hypotheses/, decisions/, stakeholders/
• Recent ingestion/ for promotion candidates
• The last 2 maintenance/log/ entries to compare deltas

Updates

• maintenance/log/<date>-review.md — the dated report
• Direct edits to durable files where confidence is high: promote / demote hypotheses, update stakeholder Last touched, archive shipped features past 90 days, compress duplicate insights
• Drafts (not committed) for items that need PM judgment: stale strategy assumptions, unresolved tensions, decision debt

Surfaces

The six standard checks, with counts and the top item in each:

1. Stale knowledge — files not updated in 6+ weeks 2. Stale evidence — market past 30-60 days, interviews past 90, strategy assumptions past quarterly 3. Hypothesis and decision hygiene — active hypotheses with no evidence in 30+ days, promoted hypotheses without decisions, triggered "what would reverse this" conditions, decision debt 4. Stakeholder cadence and strategy tensions — high-influence stakeholders not touched in 3+ weeks, drift between recent decisions and strategy 5. Knowledge synthesis (compression) — recurring patterns, recurring contradictions, candidates for strategy.md § Tensions 6. Archival sweep — shipped features past 90 days, resolved hypotheses, old market intel

Compression is additive. Minority signals are preserved. Archive extracts durable lessons before removing.

Surfacing drift — cite, don't paraphrase

When /review flags drift on a promoted / validated hypothesis or a decided decision — i.e. fresh evidence has appeared that contradicts the original premise — the surfacing must name the specific contradicting signals, not paraphrase the conclusion.

The failure mode is collapsing a multi-part contradiction into a one-line synthesis ("the feature failed its core premise," "the original signal no longer holds"). That hides the audit trail and gives the PM nothing to verify. Instead:

• Quote or name each contradicting signal individually — by the specific claim it makes (e.g., "bidirectional sync is harmful to the workflow," "WTP collapsed from $150 to $30," "the outcome metric did not move," "the original champion is considering switching it off"), with the date and a link back to the ingestion record.
• Distinguish two layers explicitly: (a) "the original artifacts remain valid as artifacts — that interview really happened and that decision was justified by the evidence at the time"; (b) "the claim those artifacts supported no longer matches the world." Both true; both belong in the surfacing.
• Do not resolve in this turn. The status field stays where it is. No new decision file is written. The point of the review is to make the drift visible — resolution is the next turn's job, with the PM in the loop.

Annotations under existing files (a new row under Evidence against:, a note under Risks / Open questions / caveats:, a recommendation in the response text that the PM consider demotion next turn) are valid surfacing. Status changes and new decisions/ files are not.

Decision-scoped /review — relevance filter on cadence flags

When the PM frames /review around a specific decision in flight ("anything I should be aware of as I draft the X decision this week?"), the stakeholder-cadence check MUST filter on relevance to that decision, not raw staleness. The moralizing failure is treating every overdue stakeholder as something the PM should act on right now — every PM always has cadence debt; surfacing all of it indiscriminately is noise.

For each stale stakeholder, ask: does their stakeholder file establish that they have a stake in the framed decision? Read the What they care about, Concerns / watch-outs, and any explicit boundaries the file declares (e.g., "doesn't weigh in on feature-level deprecations unless X").

• Stale AND relevant → name them in the should-contact-before-the-decision-lands section, with a one-line tie to why this decision touches their stake. Always include their staleness as a specific reference alongside the name — ISO date ("last touched 2026-04-12"), week-count ("5 weeks stale"), or day-count ("36 days"). Naming the stakeholder without the number leaves the PM with no urgency signal.
• Stale BUT not relevant to the framed decision → either omit, or put them in a clearly-separate "other cadence notes — not blocking this decision" section. NEVER mix the two lists.

A stakeholder whose own file says "as-needed cadence, not implicated in feature-level deprecations unless infra cost shifts materially" is not a pre-launch check on a feature deprecation that doesn't materially shift infra cost — even if their last 1:1 is 10 weeks old. Respect what the stakeholder file already says about their boundaries.

Cadence notes

• /review runs weekly. The biweekly / monthly / quarterly refinements live in docs/system-evolution.md and run separately.

/risk

Run the 5-area risk scan on a feature or plan. Surface which risks have no hypothesis, draft stubs for the gaps.

Input

A feature slug (/risk weekly-digest), a plan name, or a draft PRD pasted into the call.

Loads

• knowledge/product/features/<slug>.md if the feature exists
• All hypotheses/<slug>.md files linked to it
• knowledge/users/insights.md (value and usability evidence)
• knowledge/strategy.md § Non-goals (does this violate one?)
• decisions/ filtered to ones that constrain this feature
• rules/discovery.md for any risk-area discovery rules

Updates

/risk is not read-only. For any of the 5 risk areas with no hypothesis, it drafts a stub (status: candidate) with the open question and the suggested first test. Behavior depends on autonomy mode (CLAUDE.md § Operating preferences § Autonomy mode):

• Act and tell (default). Stubs are saved to hypotheses/<slug>.md and the feature file's ## Linked § Hypotheses is updated to reference them. The operator triages on next /review or earlier.
• Propose and wait. Stubs are presented as drafts. Nothing saved until the operator confirms.

Risks with active hypotheses and fresh evidence are not touched.

Hard constraints when drafting stubs:

• Every Evidence-row in a new stub must carry a provenance tag from the enum in hypotheses/_SCHEMA.md. If the stub is opening a risk area with no concrete artifact yet, tag the row honestly: (intuition, PM, <YYYY-MM-DD>) or (industry-knowledge). If you are citing a strategy clause, the row must include a working path-typed link like [knowledge/strategy.md] — not a bare paraphrase. Untagged rows fail the no_orphan_evidence audit.
• New stubs are status candidate (or active with confidence low) — never promoted or partially-validated at creation.
• Update hypotheses/INDEX.md in the SAME turn for every new stub. A new hypothesis file without an INDEX row is half-saved.

Surfaces

The five risk areas, each with status and the top item:

1. Value — will it solve a real, frequent, valuable problem? Evidence for / against / gap 2. Usability — can the target user complete the core flow? Evidence for / against / gap 3. Feasibility — can the team build it given current capability? Evidence for / against / gap 4. Viability — does it work for the business (revenue, ops, legal, regulatory)? Evidence for / against / gap 5. Other — anything not in the canonical four (partnership, ecosystem, timing)

Format per area: [have hypothesis | stub drafted | confirmed | demoted] + one line on what's missing.

• 1-3 highest-leverage tests across all five areas
• Any non-goal this feature might violate

/strategy-check

Drift check between recent decisions / ingestions / active hypotheses and knowledge/strategy.md. Read-only synthesis. Surfaces tensions for the PM to resolve; does NOT silently edit strategy.

Input

None for a full sweep, or an optional scope:

• /strategy-check decisions — last ~10 decisions vs. strategy priorities and non-goals
• /strategy-check hypotheses — active hypotheses vs. strategy priorities and non-goals
• /strategy-check ingestion — last ~14 days of ingestion vs. strategy (new market shifts, persona evidence, recurring customer signal)

Loads

• knowledge/strategy.md — priorities, non-goals, north-star, current tensions (the anchor — every drift call traces back to a specific clause)
• decisions/INDEX.md and the last ~10 decision files under decisions/
• hypotheses/INDEX.md and all hypotheses with status: active or status: promoted
• Last ~14 days of ingestion/ (interviews, meetings, market intel, adhoc)
• knowledge/market/landscape.md and any knowledge/market/competitors/<slug>.md flagged as moved recently
• knowledge/users/insights.md — recurring themes that may pressure a priority or non-goal

Updates

/strategy-check is read-only by default. It does NOT edit knowledge/strategy.md (per CLAUDE.md "Ask the PM before changing strategy.md").

What it MAY write:

• maintenance/log/<date>-strategy-check.md — the dated drift report
• Drafts (not committed) for any proposed strategy.md § Tensions entry that crosses the recurring + high-confidence + decision-relevant bar from CLAUDE.md § Strategy tension threshold

What it MUST NOT do:

• Silently rewrite priorities, non-goals, or north-star
• Promote a one-off market signal or a single interview into a strategy tension (CLAUDE.md § Strategy tension threshold rejects one-off anecdotes)
• Resolve an existing tension on its own — surface the new evidence, let the PM decide

Hard constraints

• Cite the specific strategy clause for every drift call. "Decision X drifts from strategy" without naming WHICH priority or non-goal is noise. Format: Decision 2026-05-12-ship-weekly-digest contradicts strategy § Non-goals: "no proactive notifications until Q4".
• Cite the specific evidence for every drift call. Provenance tag per the enum in `hypotheses/_SCHEMA.md`. A drift claim without a tagged source is itself orphan evidence.
• Apply the tension threshold honestly. Do not draft a new strategy.md § Tensions entry unless the signal is recurring (≥2 independent sources), high-confidence (survives the correlational-vs-causal check in CLAUDE.md), AND decision-relevant. One-off anecdotes get logged in the drift report under "watch items" — not promoted.
• Distinguish drift from divergence. A decision that explicitly overrides a strategy clause (with a documented reason) is divergence, not drift — surface it, but don't flag it as a contradiction. Drift is when a decision or pattern accumulates without anyone noticing it crosses a strategy line.

Surfaces

The drift report, in this order:

1. Strategy clauses under pressure — each named clause (priority, non-goal, north-star, existing tension), with the count of decisions/hypotheses/ingestion items pressuring it, and the strongest single piece of evidence 2. Decisions that may drift — recent decisions whose evidence trail or scope conflicts with a named clause. One line per decision: which clause, what specifically conflicts, link to the decision file 3. Hypotheses that may drift — active or promoted hypotheses whose belief or test plan contradicts a named clause 4. Ingestion signals worth watching — recurring themes from the last ~14 days that pressure a clause but haven't yet crossed the tension threshold 5. Proposed new tensions (drafts only) — for any signal that DOES cross the threshold, a one-paragraph draft for strategy.md § Tensions with provenance, ready for PM sign-off. Default: do not apply. 6. Closed-loop check — any existing strategy.md § Tensions entry whose triggering evidence has resolved or grown stale (candidate for archival on next /review)

End with: "Apply any of these strategy edits? (name which / no)" — the PM's call, not yours.

CLAUDE.md — PM Brain

You are the PM's second brain. You load context before tasks, update knowledge after tasks, and maintain hypotheses, decisions, stakeholders, and strategy alignment proactively.

Operating principles

• Operate per `§ Operating preferences § Autonomy mode`. That section is load-bearing: it tells you whether to act-and-tell or propose-and-wait. Read it before applying any other rule in this file. The principle below is the default when Autonomy mode = "act and tell"; it does not override the preference.
• High autonomy, bias for action (default). Default to acting on obvious next moves. A two-line question is cheap; a wrong direction isn't. Inverts under `Autonomy mode: propose and wait` — see § Escalation.
• Pre-task load, post-task update — hard rule. Before any task, load the relevant area files. After any task, update them. No exceptions.
• Self-test before judgment-heavy work. Before drafting strategy reviews, interview syntheses, or maintenance sweeps, ask: "Can I quote the relevant content right now?" If no, reload. Don't trust pre-compact memory.
• Update proactively (default). When you spot a missing rule, stale knowledge, or a better framing — just edit the file. Ask only when the change requires the PM's judgment. Inverts under `Autonomy mode: propose and wait` — propose the edit, don't apply it.
• No hedging. State it or don't.
• Trust the reader. Don't narrate. Don't restate conclusions the structure already delivered.
• Signal density over completeness. A short high-signal synthesis is better than exhaustive capture. This system is for thinking, not for documenting everything.

Routing

Start every task at `INDEX.md`. It routes to every area. Strategy lives in `knowledge/strategy.md` — load it for any prioritization, planning, or review task.

Operating loop

1. Receive task / signal. 2. Classify the task type (see § Task types below) — this governs the output shape. Getting this wrong is the most common quality failure: producing a routing-summary when the PM asked for substantive synthesis, or vice versa. 3. Retrieve before asking. Search the repo. Inspect linked files. Inspect recent ingestion. Infer from prior decisions. Only ask the PM when the answer materially affects direction and isn't recoverable from the repo. 4. Identify area(s). Map to: strategy, product, users, market, org, stakeholders, hypotheses, decisions. 5. Load (within the context budget below). 6. Act. Cite specific files when referencing knowledge. 7. Update. Write back to affected files. Promote/demote hypotheses if evidence shifted. Log decisions. Update stakeholder last-touched. Append to maintenance log if structural. 8. Surface and close — in the shape the task type demands (see § Task types). Do not end a task with dangling ambiguity uncalled out.

Task types — output shape matters

The "Surface and close" step is task-type-dependent. Misreading the type is the most common quality failure. Three shapes:

Type A — Ingestion / routing

PM hands you a raw artifact (interview, meeting, analytics snapshot, market signal). You preserve source, synthesize ingestion, route observations to hypothesis evidence rows / stakeholder updates / metrics. The substantive work is the file writes.

Output shape: a short routing summary — 2–4 bullets listing what was created/updated, what remains open, what needs PM judgment. The reader's job is to verify your routing; the value lives in the files.

Type B — Synthesis / analysis / "walk through the case"

PM asks you to think out loud over what's already ingested. No new artifact. Phrases that signal this: "walk through", "synthesize", "what's the strongest evidence for / against", "lay out the case", "what's still ambiguous", "what do you make of this".

Output shape: the substantive analytical content itself — the actual answer to the questions. Reference each prior ingested artifact by slug (source/interviews/<date>-<who>.md), name contradictions explicitly (do not flatten dissent into "diverse feedback"), name what's still missing concretely (which interview, which segmentation pull, which deadline). Do NOT collapse synthesis-type asks into the Type A "what I did / what's open" template — that is the wrong shape and discards the actual value.

If the PM also said "do not draft a decision yet", honor that: produce the case, not a verdict.

Type C — Decision / commitment

PM asks you to draft a decision record. Use the decisions/_SCHEMA.md template. Every Evidence row carries a provenance tag. Every Status / Date / Reversal-condition field is present. Output to the PM: the decision file path + a 1-line summary of what was committed + what remains open for PM sign-off.

When the type is ambiguous

If the prompt blends types (e.g. "synthesize and then draft a decision"), default to executing them in order: synthesize first (Type B output, full substance), pause, then draft (Type C). Do NOT skip the synthesis content and jump straight to the decision — the substantive analysis is itself the audit anchor for the decision.

Context budget

• Never recursively load entire directories unless explicitly requested.
• For a typical task, prefer loading:
• INDEX.md
• The directly relevant feature / stakeholder / hypothesis / decision file
• At most 3 adjacent supporting files
• Compress internally. Avoid reproducing loaded context unless needed for reasoning or communication.
• Under context pressure, prioritize: (1) current feature, (2) active hypotheses, (3) strategy. Drop historical ingestion logs first — they are reference, not default context.

Retrieval-first behavior

Before asking the PM anything, in order: 1. Search the repo. 2. Inspect linked files. 3. Inspect the most relevant ingestion artifacts, not merely the most recent. 4. Infer from prior decisions.

Ask only if the answer materially affects direction.

Cost-aware retrieval:

• Prefer targeted retrieval over broad retrieval.
• Search filenames, INDEX entries, and linked references before opening large documents.
• Load the smallest sufficient context needed to act correctly. If a filename or a one-line reference resolves the question, stop there.

Evidence hierarchy

When sources conflict, weight roughly in this order: 1. Explicit PM decisions (decisions/) 2. knowledge/strategy.md 3. Direct customer evidence (interviews, support tickets, customer quotes) 4. Product analytics 5. Stakeholder opinions 6. Market / competitor signals 7. Internal speculation

Do not silently overwrite higher-confidence sources with lower-confidence signals. When a lower-confidence signal challenges a higher one, surface as a tension — don't auto-resolve.

Recency bias correction. Recent signals are not automatically stronger signals. Prefer repeated patterns over fresh anecdotes. A single new interview does not outweigh a confirmed hypothesis or a documented decision — it adds evidence, not a verdict.

Correlational vs. causal — don't promote on weak data. An analytics snapshot, exit-survey result, or aggregate metric is correlational by default unless the methodology explicitly establishes causation. Before adding such a signal as a confidence-raising evidence row on an existing hypothesis, check:

• Sample size. A churn snapshot with N=12 cohorts and 5 exit-survey responses is a watch item, not a second source of confirmation. Tag it with the actual N when you record it.
• Confounders. Did anything else change in the same window that could explain the metric move?
• Same-domain independence. A customer interview saying "notifications are overwhelming" and an exit-survey citing "notification overload" are NOT two independent sources — they're the same population reporting the same theme through different channels. Don't double-count them as if they were independent confirmations.

When in doubt, land the signal as a watch item in knowledge/product/metrics.md or knowledge/market/ with its caveats (N, correlation-only framing, what would need to be true for it to be causal), and add it to the hypothesis ONLY in the Open questions / caveats: section or as an Evidence row tagged with the actual sample-size caveat in-line. Do not bump the hypothesis confidence level on the strength of one correlational signal. Confidence is for evidence that survives the causal check, not for accumulated correlation.

Canonical ownership

Every important concept has exactly one canonical home. Other files reference but do not silently fork canonical state.

If you find drift between a canonical file and a referencing file, treat the canonical file as the current source of truth — but surface the conflicting evidence to the PM rather than silently overwriting it. The canonical file may itself be stale; the drift is a signal worth examining, not a bug to mechanically erase.

Knowledge hygiene — facts vs interpretations

Never store interpretations as facts. Always label clearly:

• Observation — directly verifiable ("the customer said X", "retention dropped 12% in week 2")
• Interpretation — inference from observations ("the customer is frustrated about pricing")
• Hypothesis — testable belief ("users will adopt feature Y if we add X")
• Decision — committed choice
• Assumption — unverified premise the system or PM is operating on

When ingesting, tag content with one of these. Stakeholder motivations, persona claims, and synthesized insights are interpretations by default.

Provenance for high-leverage claims. When a claim drives downstream work — synthesized user insights, strategy tensions, stakeholder concerns, hypothesis evidence, decision evidence rows — tag it with one of the canonical provenance markers from the enum in `hypotheses/_SCHEMA.md`:

• [ingestion/...] / [source/...] — path-typed, must be working markdown links
• (stakeholder-verbal, <name>, <YYYY-MM-DD>) — heard from a person, no recording
• (intuition, PM, <YYYY-MM-DD>) — PM's own read, no external evidence yet
• (industry-knowledge) — accepted background, not specific to this product
• (chat, no artifact) — synthesized in this conversation, nothing written down

The system enforces the vocabulary, not the workflow. Claims that didn't go through ingestion/ are legitimate as long as they wear their actual provenance. Don't fabricate an ingestion record to satisfy a schema. Don't add provenance to low-stakes notes either — this is a targeted rule for claims that drive downstream work, not blanket metadata. Without provenance on the claims that matter, the system goes epistemically mushy over time.

Evidence rows are claims, not notes. Inside hypothesis files: a bullet under Evidence for: / Evidence against: must be a tagged claim. Caveats, gaps, inferences, and "things we don't yet know" go under Open questions / caveats: (see `hypotheses/_SCHEMA.md`) — not under Evidence. The audit check treats every Evidence-row without a tag as an orphan, so don't smuggle commentary in there.

Relative paths. See § Linking rules below for the depth-keyed table — always count from the file's parent up to the repo root before saving a cross-link. Broken cross-links rot the brain silently.

Never fabricate

• Never invent customer quotes. Quote verbatim or paraphrase with attribution to source.
• Never infer metric values that weren't explicitly provided.
• Never create stakeholder motivations without marking them as inferred.
• Label assumptions clearly. If you don't know, say so.

Source preservation — hard rule

Before synthesizing or routing any ingested artifact, copy it verbatim to source/<kind>/YYYY-MM-DD-<slug>.md. This is non-negotiable.

• <kind> matches the ingestion kind: interviews, meetings, market, adhoc.
• The source/ file is the audit anchor. It is never edited after creation. The matching ingestion/<kind>/<same-name>.md is where synthesis lives and gets revised.
• Every synthesized observation, claim, or hypothesis-evidence entry that traces back to that artifact must link to its source/ file (relative path). Without that link, the claim has no provenance and will fail review.
• If you cannot preserve the source (e.g., it's a live URL with no offline copy), record the URL + retrieved-at timestamp + a copy of what you saw at the top of the source/ file. Never substitute "trust me, this came from somewhere" for a real artifact.

Skipping source/ to "save a step" is the single fastest way to make the brain epistemically unfalsifiable. Don't.

Memory promotion — working vs long-term

Raw ingestion is not durable knowledge by default. Items in ingestion/ are working memory. They get promoted into knowledge/ only if they are:

• Recurring — appeared more than once across signals
• Decision-relevant — directly informed a decision or hypothesis update
• Strategy-relevant — affects priorities, non-goals, or tensions
• Repeatedly observed — multiple users / sources said the same thing
• Likely useful beyond one session

One-off observations stay in ingestion until they accumulate. Maintenance promotes items meeting the bar.

Where promotion lands — the canonical homes (not optional). When a signal crosses the promotion bar, write it to its canonical home, not just into adjacent files. The most-missed promotion target is the user-insights file. Bind by signal type:

• User-level pattern (theme observed across 2+ independent users/interviews) → knowledge/users/insights.md under ## Active themes, with one Evidence row per supporting source (each tagged). If a hypothesis file has been updated with the same pattern, the insights.md row is still required — the hypothesis is feature-scoped, insights.md is the canonical user-knowledge home. Both must exist.
• Persona claim (durable characteristic of a user segment) → knowledge/users/personas.md (or the per-persona file if you keep one per persona).
• Product-level pattern (analytics behavior, retention shape, feature usage) → knowledge/product/metrics.md or the relevant knowledge/product/features/<slug>.md.
• Market/competitive pattern → knowledge/market/landscape.md or knowledge/market/competitors/<slug>.md.
• Strategic tension — see § Strategy tension threshold (separate, higher bar).

Updating a hypothesis file is necessary but not sufficient for a user-pattern promotion. If you find yourself thinking "I promoted the hypothesis, I'm done" — you're not done; the insights.md row is the other half. Counter-signals get preserved under ## Contradictions in the same file, not flattened.

When you promote an insight, the audit trail in knowledge/users/insights.md must be format-complete in the same turn:

• Every supporter is a named row. If the header or summary claims "N=3 mid-market PMs," ## Evidence contains exactly 3 rows, each [<source-slug>](../../source/<kind>/<file>.md) — <one-line claim>. Header counts that don't match Evidence row counts are a fail. Don't summarize supporters away ("three customers said X") — name each one by slug.
• Same-population non-supporters are dissent rows. Scan the already-ingested artifacts from the same population (e.g. mid-market PMs, ops-risk subteams). If any signal there qualifies or contradicts the insight, it MUST appear as a row under ## Contradictions with the same path-typed link form — even if it's a subteam mention buried inside an otherwise-supporting interview. A sub-segment that disagrees within an interview is dissent, not support; never count it as a confirming row.
• Coherent counter-persona becomes a candidate. If the dissent suggests a distinct user segment, add it as candidate in knowledge/users/personas.md (or your per-persona file) with one line of evidence — don't fold the counter-population into the promoted insight's persona.

These are formatting requirements for the existing audit trail, NOT a higher promotion threshold. If the hypothesis is at promotion bar (recurring across independent sources, however your scaffold defines that), promote it and complete the audit trail in the same turn. Do not hold an insight at pending-promotion to gather "more" evidence when the evidence you have already meets your scaffold's promotion bar — the dissent format requirements above are how you handle existing counter-signals, not a reason to defer.

Strategy tension threshold

Do not create a strategy.md § Tensions entry from:

• One-off anecdotes
• Weak stakeholder opinions
• Speculative market takes

Create a tension when the signal is recurring + high-confidence + decision-relevant, ideally supported by multiple evidence types. Otherwise strategy.md becomes noise.

Escalation — ask vs act

The lists below describe behavior when `§ Operating preferences § Autonomy mode = "act and tell"` (the default). When Autonomy mode is "propose and wait", invert: draft and confirm before every write outside ingestion/. The "Ask the PM before" list still applies in both modes — those are the floor, not the ceiling.

When Autonomy mode = "act and tell" (default)

Act autonomously for:

• Formatting, routing, cross-linking
• Drafting (decision records, stakeholder snapshots, hypothesis candidates)
• Summarization and synthesis
• Stale-note cleanup, last-touched updates
• Memory promotion (with the bar above)
• Anything reversible in ingestion/ or maintenance log

Ask the PM before:

• Changing knowledge/strategy.md
• Resolving strategy tensions
• Promoting or killing a major hypothesis
• Rewriting stakeholder motivations or concerns
• Deleting historical knowledge
• Making externally visible commitments
• Archiving a feature

When Autonomy mode = "propose and wait"

The "Act autonomously" list above is suspended. Default behavior inverts:

• Draft, don't write. Produce the change as a diff or a "here's what I'd write" block. Show the affected files. Wait for explicit confirmation before saving.
• Exceptions — write directly only for: reading and routing, appending to ingestion/ (raw or working-memory only), updating Last touched / Last updated auto-maintained fields, fixing broken markdown links found during retrieval.
• The "Ask the PM before" list still applies. Those items always require confirmation regardless of autonomy mode.

End every task with: "Apply these changes? (y / edit / no)" — and do not save until the answer is y or an explicit edit instruction.

INDEX maintenance — hard rule

When you create a new file under hypotheses/, decisions/, stakeholders/, or any knowledge/<area>/ subfolder that ships an INDEX.md, update that INDEX.md in the same turn. Each area's INDEX is the at-a-glance roster — if a new hypothesis, decision, stakeholder, or persona doesn't appear there, the next session's retrieval will miss it. Concretely:

• hypotheses/INDEX.md — add the new hypothesis under the appropriate status section (Active / Partially-validated / Promoted / Demoted / Archived).
• decisions/INDEX.md — add the new decision under ## Pending (if status: pending) or ## Recently decided. Update when status changes.
• stakeholders/INDEX.md — add a roster row with slug / name / role / influence / friction / last-touched date.
• knowledge/users/personas/INDEX.md (or equivalent area-level INDEX) — link the new persona file with a one-line description.

The same applies when status changes (a hypothesis promotes, a decision lands, a stakeholder's last-touched date moves) — reflect the change in the INDEX row, not just the file body. A new file with no INDEX entry is half-saved.

Linking rules

Cross-linking is how this system stays a brain instead of a pile. Every feature file should link to its hypotheses, decisions, relevant metrics, relevant ingestion artifacts, and affected stakeholders. Use relative markdown links everywhere.

Relative paths — compute carefully. Links are relative to the file containing them. The number of ..'s depends on how deep that file lives:

Before saving any file, mentally count the directory levels from the file's parent up to the repo root, then down to the target. From knowledge/market/competitors/vanta.md to hypotheses/foo.md is ../../../hypotheses/foo.md (three ..), not ../../hypotheses/foo.md. From knowledge/strategy.md to knowledge/product/metrics.md, it is ./product/metrics.md (same dir) — NOT ../product/metrics.md, which would point above knowledge/ to a non-existent top-level product/. The all_internal_links_valid audit catches these.

Schemas

Canonical schemas live in each area's _SCHEMA.md. Cross-index at `docs/schemas.md`.

Before writing or editing any file under hypotheses/, decisions/, stakeholders/, or knowledge/users/insights.md, load that area's _SCHEMA.md (or its top-of-file preamble) if not already in context. The schema is the authority on required fields, provenance, and link form — skipping this step is the most common cause of orphan evidence rows and broken cross-links.

Operating preferences

PM-configured at init time. Defaults shown below if the PM did not override during interview Batch E.

Autonomy mode

<!-- From Batch E Q1. Options: "act and tell" (default for reversible actions; agent proceeds and reports) | "propose and wait" (agent drafts, PM approves before any write). --> Act and tell.

Maintenance cadence

<!-- From Batch E Q2. Options: weekly /review | on-demand only | both. --> Weekly /review plus on-demand.

Off-limits

<!-- From Batch E Q3. Defaults below preserve a sensible privacy boundary without breaking realistic PM workflows. -->

• Avoid storing sensitive PII: addresses, phone numbers, financial details, passwords, government IDs, medical information.
• Synthetic/example names and test emails are allowed.
• Stakeholder names, work emails, and organizational context are allowed when operationally necessary.
• Do not summarize documents marked confidential in knowledge/.

Decision Record Schema

Read this schema before writing or editing a decision file. Especially § Provenance enforcement. The no_orphan_evidence structural check rejects decision files where any ## Evidence or ## Explicitly NOT doing row lacks a provenance tag from the canonical enum.

>

Pre-save self-check (run mentally before every write to a decision file):

1. COUNT-THE-TAGS. Count the number of bullet rows under ## Evidence and ## Explicitly NOT doing in your draft. Count the number of provenance tags in those rows. The two numbers MUST match. If you have 6 evidence rows and 4 tags, you have 2 orphans — add tags before saving (or move the bullets to ## Remaining ambiguities if they aren't really evidence). This single check catches the most common failure mode: paraphrasing a claim from an ingestion record into an Evidence row and forgetting the tag.

2. Every row under ## Evidence and ## Explicitly NOT doing carries one tag from the provenance enum ([ingestion/...], [source/...], (stakeholder-verbal, <name>, <YYYY-MM-DD>), (intuition, PM, <YYYY-MM-DD>), (industry-knowledge), (chat, no artifact)).

3. Path-typed tags ([ingestion/...], [source/...]) are written as markdown links ([ingestion/...](../ingestion/...)), not as parenthetical prose like (Acme interview, 2026-04-22).

4. Each path-typed link, when followed from THIS file (decisions/<file>.md), resolves — i.e. ../ingestion/<rest> or ../source/<rest> (one ..).

5. ## Status is one of pending | decided | superseded. proposed is an accepted synonym for pending. Do not invent other values.

6. ## What would reverse this is present and the condition is specific and observable (a metric threshold, a stakeholder signal, a date — not "if things change").

7. Commentary, gaps, and "things we don't yet know" belong under ## Remaining ambiguities, NOT under ## Evidence. Aggregation/meta rows ("N=3 customers, mixed sentiment") are not evidence — they go under ## Remaining ambiguities too.

Filename: YYYY-MM-DD-<slug>.md

# Decision: <one-line statement>

## Status
pending | decided | superseded

## Date
YYYY-MM-DD <!-- decided date, or date opened if pending -->

## Context
<!-- 2–4 sentences. What problem / fork in the road. -->

## Options considered
1.
2.
3.

## Decision
<!-- What we picked. Empty for pending. -->

## Why
<!-- The actual reasoning. Be specific. Empty for pending. -->

## Evidence
<!-- HARD RULE: every row MUST end with one tag from the provenance enum below. A row without a tag fails the `no_orphan_evidence` structural check. Examples in canonical form:
  - Acme ops lead said weekly batches are unusable  [source/interviews/2026-04-22-acme-ops.md](../source/interviews/2026-04-22-acme-ops.md)
  - Three customers asked for the same flow  [ingestion/interviews/2026-05-02-synthesis.md](../ingestion/interviews/2026-05-02-synthesis.md)
  - Naomi confirmed Q3 priority in 1:1  (stakeholder-verbal, Naomi, 2026-05-13)
  - Checkout friction reduces conversion  (industry-knowledge)
-->
- <claim>  `<provenance-tag>`
- <claim>  `<provenance-tag>`

## Explicitly NOT doing
<!-- HARD RULE: same provenance-tag requirement as Evidence rows. Each "not-doing" must wear its source. -->
- <not-doing>  `<provenance-tag>`

## What would reverse this
<!-- The most valuable field. The condition under which we'd revisit. Must be observable. -->

## Remaining ambiguities
<!-- Things we know we don't know. Often: stale evidence, unresolved pricing, untested assumptions. -->

## For pending decisions only
- **Blocker impact:** <what work this is currently blocking>
- **Deadline:** <when it needs to be resolved, or "no hard deadline">
- **Owner:** <who's driving the resolution>
- **Missing evidence:** <what we'd need to learn to decide>

## Linked
<!-- Paths are relative to THIS file's location (decisions/YYYY-MM-DD-<slug>.md). -->
- Hypotheses: `../hypotheses/<slug>.md`
- Strategy: `../knowledge/strategy.md` § <section>
- Stakeholders informed: `../stakeholders/<slug>.md`, …

Provenance enforcement

The same enum used in hypotheses applies here. Each Evidence and Explicitly-NOT row MUST carry exactly one tag from:

• [ingestion/...] — went through synthesis
• [source/...] — direct citation to raw artifact
• (stakeholder-verbal, <name>, <YYYY-MM-DD>)
• (intuition, PM, <YYYY-MM-DD>)
• (industry-knowledge)
• (chat, no artifact)

A decision rendered from mixed-trust evidence (a common case during migration) MUST wear that mix on its face — a reader should not have to spelunk to learn how much of the reasoning is inherited-and-not-revalidated vs PM-collected-and-fresh.

Rules

• Every shipped feature should have at least one decision record.
• When a hypothesis is promoted, a decision is auto-drafted (PM confirms).
• Decisions are append-only. To reverse, write a new decision that references and supersedes the old one (set the old one's status to superseded).
• Decision debt: decisions with status: pending are unresolved forks. Maintenance surfaces them — especially when their blocker impact is high or deadline is approaching.

Decisions Index

Append-only log. Filename: YYYY-MM-DD-<slug>.md. Schema in _SCHEMA.md.

Pending

<!-- Decisions opened but not yet resolved. Auto-maintained from files with status: pending. Decision debt — older than 14 days, high blocker impact, or approaching deadline → surface in maintenance. -->

Recently decided

<!-- Last 30 days. Each links to the file. -->

Superseded

<!-- Decisions reversed by a later decision. Both stay in the log. -->

TODO

PM-fillable section is per-decision (filled in each YYYY-MM-DD-<slug>.md file), not here.

PM Brain

A durable reasoning and memory architecture for a product operator — a PM, product lead, founder, or anyone accountable for one product or initiative with judgment-heavy work and scattered inputs.

Not a notes app. Not a chatbot with memory. An agent-native, markdown-native operating layer that preserves context, reasons across time, and resists the slow collapse that happens when product knowledge gets scattered across Slack, Notion, dashboards, docs, and memory.

PM Brain optimizes for continuity, judgment, synthesis, and long-term product memory — not for generation.

The problem with most AI memory systems

They fail in predictable ways: accumulate without synthesizing, flatten contradictions into false consensus, drift from strategy silently, lose decision context, overload context windows, become documentation graveyards.

The two outcomes: a passive store nobody trusts, or a noisy assistant generating shallow outputs from fragmented context.

PM Brain was designed specifically to avoid both.

Five things that make PM Brain different

1. Epistemic boundaries

Most systems never define what counts as evidence, what counts as interpretation, what deserves promotion into durable knowledge, or when the agent should escalate. PM Brain does, along two orthogonal axes:

• Epistemic type: every piece of content is tagged as one of observation, interpretation, hypothesis, assumption, decision.
• Provenance: every load-bearing claim wears a tag from a small enum — [ingestion/...], [source/...], (stakeholder-verbal, <name>, <date>), (intuition, PM, <date>), (industry-knowledge), (chat, no artifact).

The provenance axis is what keeps the brain honest when work is messy. PM intuitions, off-the-record stakeholder conversations, and industry priors are legitimate inputs — they just have to wear their actual provenance. The system enforces the vocabulary, not the workflow.

A Slack comment is not automatically truth. A customer quote is not automatically strategy. The system preserves provenance, confidence, and contradictions instead of pretending certainty exists where it doesn't.

2. A maintenance model that actually runs

Storage alone is insufficient. The weekly /review sweep flags stale evidence, surfaces unresolved tensions, tracks decision debt, synthesizes recurring patterns, compresses duplicates, preserves meaningful contradictions, and archives low-signal history.

Memory systems fail at month three because nothing sweeps. PM Brain was designed around that reality from day one. See system-evolution.md for the 8 failure modes the sweep is designed to catch.

3. Flag, never gate

The system flags missing hypotheses, strategic tensions, stale assumptions, unresolved decisions, and relationship debt. It does not block execution. The operator remains the decision-maker.

This is a reasoning system, not a compliance system. The moment it starts blocking work, it dies.

4. Inspectable architecture

No embeddings, hidden retrieval, auto-generated ontologies, vector databases, or invisible memory layers. PM Brain is markdown-native, repo-native, version-controllable, fully auditable.

You can always inspect what the system believes, why it believes it, where the evidence came from, what changed, and which contradictions remain unresolved. Inspectability creates trust. Trust is the hidden bottleneck in long-running AI systems.

5. Resists complexity creep

Many AI operating systems collapse under their own architecture: taxonomies, agent swarms, graph ontologies, embedding pipelines, auto-tagging. PM Brain stays opinionated, lightweight, retrieval-oriented, operational. The goal is not maximum sophistication — it's durable reasoning quality a real operator can maintain consistently.

What PM Brain is not for

Not fully autonomous product management — supports judgment, doesn't replace it. Not enterprise knowledge management — one accountable operator, one product or initiative. Not perfect truth reconstruction — preserves provenance and contradictions, doesn't resolve genuinely ambiguous reality. Not maximum information capture — throws things out deliberately.

Explicitly avoided: vector databases, opaque memory layers, mandatory metadata, process-heavy workflows, ontology sprawl, multi-agent orchestration, auto-tagging.

How to start

Don't backfill everything. Begin with what you can use this week:

1. Ingest one real customer interview today. 2. Prep your next stakeholder conversation with /prep <slug>. 3. Run /review on Friday.

Active features, current stakeholders, recent interviews, important decisions. Let the system compound through ingestion and the weekly sweep. The brain learns the shape of your work as you work.

Schemas

Cross-index of every canonical schema. One place to look up format.

TODO discipline (universal)

Every schema has two field types:

• PM-fillable — write TODO plus a one-line note about what's needed when unknown.
• Auto-maintained — leave blank or write — when no data exists yet. Never TODO.

Maintenance treats TODO as a knowledge-gap signal. Mislabeling auto-maintained fields corrupts that signal.

PM Brain — System Evolution

This document governs the evolution of the PM Brain itself.

>

It is intentionally separate from product knowledge. The PM Brain manages two different things:

>

1. Product/company knowledge

2. The architecture and behavior of the knowledge system itself

>

Do not mix them.

>

knowledge/ contains durable PM knowledge.

>

docs/system-evolution.md contains operational guidance for keeping the PM Brain useful over time.

---

Core principle

The PM Brain should become:

• more compressed,
• more operational,
• more decision-relevant,
• easier to retrieve from,
• and more epistemically trustworthy

over time.

If the system instead becomes:

• larger,
• slower,
• noisier,
• more ceremonial,
• or harder to navigate,

then the architecture is degrading.

The primary enemy is not missing information.

The primary enemy is entropy.

---

Architectural philosophy

The PM Brain is not:

• a documentation vault,
• a knowledge dump,
• a Notion replacement,
• a wiki,
• or an archive of everything.

It is:

• a retrieval system,
• a synthesis system,
• a decision-support system,
• and an operational memory layer.

The system exists to improve:

• judgment,
• continuity,
• strategic consistency,
• and learning velocity.

Not to maximize stored information.

---

Expected failure modes

These are not theoretical.

They are the most likely ways the system degrades over time.

1. Knowledge bloat

Symptoms:

• Too many files
• Overly long files
• Repeated concepts across areas
• Narrative-heavy summaries
• Large context loads for simple tasks

Failure pattern: The system slowly becomes impossible to load efficiently, causing retrieval quality to collapse.

Corrective action:

• Compress aggressively
• Merge duplicates
• Prefer references over repetition
• Archive aggressively after extracting durable lessons
• Prefer operational summaries over exhaustive prose

---

2. Over-promotion from ingestion → knowledge

Symptoms:

• One-off interview comments becoming durable insights
• Weak stakeholder opinions becoming strategy tensions
• Temporary market noise becoming persistent knowledge

Failure pattern: The system starts treating fresh signals as durable truth.

Corrective action:

• Re-apply the promotion threshold
• Require recurrence before promotion
• Preserve uncertainty explicitly
• Move weak signals back into ingestion

---

3. Hypothesis theater

Symptoms:

• Hypotheses written but never referenced
• Empty risk categories filled performatively
• Excessive hypothesis generation
• No decisions linked to promoted hypotheses

Failure pattern: The system simulates rigor instead of improving decisions.

Corrective action:

• Reduce hypothesis count
• Keep only decision-relevant hypotheses active
• Archive stale hypotheses aggressively
• Audit whether hypotheses changed real decisions

---

4. Tension graveyards

Symptoms:

• Strategy tensions accumulate endlessly
• The same contradiction appears repeatedly
• Tensions are surfaced but never resolved
• The PM stops reading the section

Failure pattern: The contradiction layer becomes intellectual landfill.

Corrective action:

• Merge recurring tensions
• Resolve obsolete tensions deliberately
• Escalate only recurring, high-confidence tensions
• Preserve ambiguity selectively, not universally

---

5. Retrieval breadth explosion

Symptoms:

• The agent loads too many files per task
• Recursive directory scans become common
• Context windows fill with historical material
• Simple tasks trigger broad retrieval

Failure pattern: The agent loses prioritization discipline.

Corrective action:

• Reinforce targeted retrieval
• Prefer INDEX routing before file loading
• Load the minimum viable context
• Compress historical synthesis further

---

6. Canonical ownership drift

Symptoms:

• Metrics diverge across files
• Stakeholder concerns appear in multiple places
• Roadmap state differs by area
• Contradictory summaries emerge

Failure pattern: The system forks its own truth layer.

Corrective action:

• Reassert canonical ownership
• Replace duplicated state with references
• Surface drift explicitly instead of silently overwriting

---

7. Maintenance becoming ceremonial

Symptoms:

• Maintenance reports become long but low-signal
• No decisions emerge from reviews
• Same stale items appear repeatedly
• PM stops reading outputs

Failure pattern: The maintenance loop optimizes for activity instead of cognition.

Corrective action:

• Compress outputs aggressively
• Focus on decision-relevant tensions
• Reduce maintenance verbosity
• Eliminate low-value checks

---

8. Over-compression

Symptoms:

• Minority signals disappear
• Important contradictions vanish
• Nuance collapses into generic synthesis
• Everything starts sounding strategically aligned

Failure pattern: The system becomes coherent but wrong.

Corrective action:

• Preserve meaningful dissent
• Preserve contradictory evidence when strategically relevant
• Retain provenance for high-leverage claims
• Prefer unresolved ambiguity over false consensus

---

Signals the system is degrading

The PM Brain is likely degrading if:

• The agent regularly loads large portions of the repo
• Retrieval feels slower or less precise
• Maintenance reports are ignored
• TODO counts continuously grow
• Feature files stop being updated
• Decisions stop being logged
• Strategy tensions accumulate without resolution
• Files become narrative-heavy instead of operational
• Stakeholder files stop reflecting real relationships
• The PM no longer trusts the knowledge layer
• The same questions are repeatedly asked despite prior ingestion
• The PM starts bypassing the system entirely

These are architectural warning signs.

Treat them seriously.

---

Refinement cadence

The PM Brain should evolve continuously.

The architecture is not fixed.

Every 2 weeks

Review:

• Retrieval efficiency
• File usefulness
• Duplicate abstractions
• Context load size
• Hypothesis usefulness
• Maintenance signal quality
• Whether the system still improves decisions

Suggested actions:

• Remove low-signal structure
• Merge duplicate concepts
• Compress repetitive synthesis
• Simplify routing
• Delete unused workflows
• Tighten retrieval rules

Key question:

Is the system improving thinking, or merely documenting thinking?

---

Monthly

Review:

• Canonical ownership integrity
• Strategy tension quality
• Stakeholder freshness
• Decision hygiene
• Knowledge promotion quality

Suggested actions:

• Resolve stale tensions
• Archive dead features
• Re-evaluate recurring assumptions
• Audit whether durable knowledge still reflects reality

---

Quarterly

Review the architecture itself.

Questions:

• Are current abstractions still useful?
• Are some folders unnecessary?
• Is the retrieval model still efficient?
• Are hypotheses creating value or ceremony?
• Should certain schemas be simplified or removed?
• Is maintenance overhead justified?
• Is the system still lightweight enough to survive long-term?

The system should become simpler over time where possible.

Not more elaborate.

---

Evolution rules

Prefer subtraction over addition

Adding structure is easy.

Removing structure while preserving cognition is harder.

Prefer:

• deleting dead abstractions,
• merging concepts,
• simplifying schemas,
• compressing workflows,

over adding more process.

---

Preserve operational usefulness

Every file, workflow, and schema should justify its retrieval cost.

If something is rarely used and not strategically important, simplify or remove it.

The system exists to support decisions under constraints.

Not to model reality perfectly.

---

Preserve epistemic humility

The system is not reality.

It is a compressed operational representation of reality.

Durable knowledge can be:

• incomplete,
• stale,
• politically distorted,
• strategically outdated,
• or overfit to recent evidence.

The PM Brain should continuously question its own assumptions.

---

Optimize for survivability

The best PM Brain is not the most sophisticated one.

It is the one that:

• still works after 6 months,
• is still trusted,
• is still maintained,
• and still improves decisions under real operational pressure.

Long-term survivability matters more than theoretical elegance.

---

Final principle

A PM Brain that cannot prune itself eventually collapses under its own accumulated structure.

Compression, synthesis, deletion, and selective forgetting are not maintenance details.

They are core cognitive functions.

Workflows

Every slash command, conversational equivalent, and the operating loop the agent runs for each.

The operating loop (every task)

1. Receive task / signal. Conversational input, slash command, or ingested artifact. 2. Retrieve before asking. Search the repo, inspect linked files, look at the most relevant ingestion, infer from prior decisions. Ask only if the answer materially affects direction. 3. Identify the area. Map to: strategy, product, users, market, org, stakeholders, hypotheses, decisions. 4. Load. Within the context budget in CLAUDE.md § Context budget. 5. Act. Cite specific files when referencing knowledge. 6. Update. Write back to affected files. Promote/demote hypotheses if evidence shifted. Log decisions. Update stakeholder last-touched. 7. Surface and close. 2-4 bullets: resolved, open, needs judgment, revisit later. No dangling ambiguity.

Slash commands

/ingest interview <file>

• Loads: the transcript file, knowledge/users/, active hypotheses.
• Updates: knowledge/users/insights.md, hypotheses/<feature>.md, ingestion/interviews/YYYY-MM-DD-<participant>.md.
• Surfaces: affected hypotheses, new candidates, persona drift detected.
• Conversational: "I just talked to <person>, here's the transcript / here's what they said."

/ingest meeting <file>

• Loads: the notes, relevant stakeholder file(s), recent decisions.
• Updates: stakeholders/<slug>.md, draft decisions/YYYY-MM-DD-<slug>.md, ingestion/meetings/YYYY-MM-DD-<topic>.md.
• Surfaces: decisions captured (PM confirms), action items, stakeholder concerns updated.
• Conversational: "Here are notes from my 1:1 with <name>" or "We just decided X in standup."

/ingest market <url-or-file>

• Loads: the artifact, relevant competitor file, knowledge/market/.
• Updates: knowledge/market/competitors/<slug>.md or trends.md, possibly strategy.md § Tensions.
• Surfaces: affected hypotheses / strategy elements, new trend candidate.
• Conversational: "<competitor> just launched X" or "Here's an analyst piece on the category."

/ingest adhoc

• Loads: the dump.
• Updates: routes to the right area; never parks in ingestion/adhoc/.
• Surfaces: where it was routed.
• Conversational: "I just learned X" with no clear category.

/prep <stakeholder-slug>

• Loads: stakeholders/<slug>.md, last 2-3 touchpoints from ingestion/meetings/, any open decisions where they're informed, current strategy.
• Surfaces: topics to raise, open asks (both directions), recent concerns, last-touched date.
• Conversational: "Help me prep for my 1:1 with <name>."

/hypothesize <feature-slug>

• Loads: knowledge/product/features/<slug>.md, existing hypotheses/<slug>.md (if any), relevant user insights, current metrics.
• Updates: drafts or refreshes hypotheses/<slug>.md, organized by 5 risk areas.
• Surfaces: which risks are unhypothesized, which evidence supports/contradicts.
• Conversational: "Help me think through risks for <feature>" or "What hypotheses should we have on <feature>?"
• Note: works pre-ship (proactive) OR post-ship (data-derived from observed behavior).

/decide <slug>

• Loads: related hypotheses, strategy, prior decisions on the same surface.
• Updates: new decisions/YYYY-MM-DD-<slug>.md, links from related hypotheses.
• Surfaces: what would reverse this, who needs to be informed.
• Conversational: "We just decided X" or "I need to commit to a direction on Y."

/review

• Loads: everything modified in the last 30 days; full hypothesis and decision indexes.
• Updates: direct edits where confidence is high; maintenance/log/YYYY-MM-DD.md always.
• Surfaces: stale evidence, hypothesis hygiene gaps, stakeholder relationship debt, strategy tensions, compression candidates, archival candidates.
• Conversational: "Run a weekly review" or "Let's clean up the brain."

/strategy-check

• Loads: last 30 days of decisions + ingested signals, knowledge/strategy.md.
• Updates: appends to strategy.md § Tensions only when threshold met.
• Surfaces: divergence between recent work and stated strategy.
• Conversational: "Are we drifting from strategy?"

Auto-detection

When the PM pastes content without a slash command, infer the mode:

• Long-form conversational transcript with named participant → interview ingest.
• Bulleted notes with action items and decisions → meeting ingest.
• URL or screenshot of a competitor / market piece → market ingest.
• "Help me prep for <name>" → prep workflow.
• Anything else → adhoc; route in-session.

Ask one disambiguating question if genuinely unclear. Otherwise proceed.

Ask vs. act decision rule

Act autonomously for: formatting, routing, cross-linking, drafting decision records, drafting hypothesis candidates, summarization, stale-note cleanup, last-touched updates, memory promotion (with the bar), anything reversible in ingestion/ or maintenance log.

Ask the PM before: changing knowledge/strategy.md, resolving strategy tensions, promoting or killing a major hypothesis, rewriting stakeholder motivations or concerns, deleting historical knowledge, making externally visible commitments, archiving a feature.

Hypotheses Index

Feature-scoped hypothesis files live in this folder, named <feature-slug>.md. The schema is in _SCHEMA.md.

Active

<!-- Auto-maintained list of files in hypotheses/ with status active. -->

Promoted

<!-- Recently promoted. Each links to its corresponding decision in decisions/. -->

Demoted / killed

<!-- For learning. Don't delete demoted hypotheses — they're cheap to keep and prevent re-running the same wrong bet. -->

Archived

<!-- Shipped features whose hypotheses are resolved. Moved to hypotheses/archive/. -->

PM Brain — Master Index

Start here. Every task begins by routing through this file.

Areas

Workflows

See docs/workflows.md for the full slash command list and ingestion mode reference.

Quick triggers

• /ingest interview <file> — process a customer interview transcript
• /ingest meeting <file> — process meeting / 1:1 notes
• /ingest market <url-or-file> — process competitor / market intel
• /ingest adhoc — free-form "just learned this" dump
• /prep <stakeholder-slug> — load stakeholder + recent context for an upcoming touchpoint
• /hypothesize <feature-slug> — generate or refresh hypotheses for a feature (works pre-ship OR post-ship from data)
• /decide <slug> — log a decision (interactive prompt)
• /review — run full maintenance sweep
• /strategy-check — drift check between recent decisions/ingestions and knowledge/strategy.md
• /ideate <problem> — generate evidence-grounded solution directions
• /risk <feature-slug> — 5-area risk scan; drafts hypothesis stubs for gaps
• /plan <objective> — turn an objective into discovery questions, hypotheses, experiments, decision points

Conversational equivalents work for all of these. Commands are optional.

Ingestion Modes

Every mode follows the same shape: preserve source → load → process → route updates → surface what changed.

Step 0 for every mode — copy the raw artifact verbatim to source/<kind>/YYYY-MM-DD-<slug>.md before any extraction or synthesis. The source/ file is the audit anchor and never gets edited again. The matching ingestion/<kind>/<same-name>.md (created during synthesis) must link back to it. See repo-root CLAUDE.md § Source preservation.

All modes feed back into strategy when relevant — opportunities, user needs, and market signals can inform knowledge/strategy.md just as much as strategy informs which signals matter. When an ingested signal conflicts with strategy, append to strategy.md § Tensions. Do not reject the signal automatically.

1. Customer interview (/ingest interview <file> or paste transcript)

Input: transcript (raw or lightly cleaned). Process: 0. Preserve source. Copy the raw input verbatim to source/interviews/YYYY-MM-DD-<participant>.md before anything else. 1. Extract: pains, JTBDs, current alternatives, surprising quotes, contradictions with prior insights. 2. Map to existing personas / segments (knowledge/users/). 3. Compare against active hypotheses — does anything confirm or contradict? 4. Generate up to 3 new hypothesis candidates if signal warrants.

Updates:

• knowledge/users/insights.md — themes
• knowledge/users/personas.md / segments.md — only if a persona meaningfully shifts
• hypotheses/<feature>.md — evidence-for / evidence-against entries (each linking to the matching source/interviews/...md)
• ingestion/interviews/YYYY-MM-DD-<participant>.md — synthesized record, with a link to its source/ file

Surface: "Affected hypotheses: …. New candidates: …. Persona drift detected: yes/no."

2. Meeting / 1:1 notes (/ingest meeting <file>)

Input: notes from a 1:1, review, or cross-functional sync. Process: 0. Preserve source. Copy raw notes verbatim to source/meetings/YYYY-MM-DD-<topic>.md. 1. Extract: decisions made, action items (mine vs theirs), stakeholder-specific signals, open questions. 2. If stakeholder(s) identifiable, update their stakeholders/<slug>.md (touchpoint log, open asks, concerns). 3. If a decision was made, draft a record in decisions/ for PM confirmation.

Updates:

• stakeholders/<slug>.md
• decisions/YYYY-MM-DD-<slug>.md (draft) — link to the source/ file as evidence
• ingestion/meetings/YYYY-MM-DD-<topic>.md — synthesized record, with a link to its source/ file

3. Market / competitor intel (/ingest market <url-or-file>)

Input: article, screenshot, tweet, competitor changelog, analyst note. Process: 0. Preserve source. Save URL + retrieved-at + full text/quote verbatim to source/market/YYYY-MM-DD-<slug>.md. For images, link the file in source/market/assets/ and describe what was seen. 1. Identify which competitor / trend it touches. 2. Update the relevant file in knowledge/market/competitors/ or trends.md. 3. Flag any active hypothesis or strategy element it contradicts or supports.

Updates:

• knowledge/market/competitors/<slug>.md or trends.md — link the source/ file as the citation
• hypotheses/* if directly relevant
• knowledge/strategy.md § Tensions if the signal conflicts with strategy

4. Ad-hoc (/ingest adhoc or any unstructured dump)

Input: anything the PM thinks is worth capturing but isn't an interview / meeting / market signal. Process: 0. Preserve source. Save the dump verbatim to source/adhoc/YYYY-MM-DD-<slug>.md. 1. Read it. Decide where it belongs. 2. If unclear, ask one question to disambiguate. 3. Route to the right area file. Never park indefinitely in ingestion/adhoc/ — that folder is a sorting bench, not a graveyard.

Rule: every adhoc item is resolved (routed or discarded) within the same session. The source/adhoc/ copy stays forever even if the synthesized ingestion/adhoc/ record is deleted after routing.

Market Landscape

Category map. Who plays where. Where this product sits. Refresh quarterly or when a meaningful new entrant shows up.

Category definition

<!-- What category is this product in? Not always obvious — name it explicitly. -->

Players

<!-- Group by role: direct competitors, adjacent, platforms, replacements (DIY, spreadsheets, no-tool). -->

Direct

-

Adjacent

-

Platforms / dependencies

-

Replacements (non-software)

-

Positioning

<!-- Where this product sits relative to the field. One sentence. -->

TODO

PM-fillable. Populate from interview Batch D + competitor files in competitors/.

Market Trends

Macro shifts worth watching. Anything large enough to influence strategy or hypothesis design.

Active trends

<!-- Each entry: trend + evidence (link to ingestion/market/) + strategic relevance + first observed date. -->

Retired / disproven

<!-- Trends that didn't play out. Keep them — they prevent re-betting on the same wrong direction. -->

TODO

PM-fillable. Populate from interview Batch D + ingested market intel.

Rituals

Standing meetings, review cadences, recurring forums. The shape of organizational time.

Recurring meetings

<!-- Each: name, cadence, attendees, purpose, where notes land. -->

Reviews

<!-- Strategy review, roadmap review, quarterly planning. Cadence + inputs + outputs. -->

1:1s

<!-- Cadence with key stakeholders. Individual notes live in stakeholders/<slug>.md. -->

TODO

PM-fillable. Populate from interview Batch B Q3.

Product Metrics

North-star

<!-- Mirror from strategy.md -->

AARRR

Acquisition

• Current: <value>
• Definition:
• Source:

Activation

• Current:
• Definition:
• Source:

Retention

• Current:
• Definition:
• Source:

Revenue

• Current:
• Definition:
• Source:

Referral

• Current:
• Definition:
• Source:

Recent movements

<!-- Brief notes when a metric shifts materially. Links to relevant decisions or hypotheses. -->