// Module T04 · Team Brain

Role Slices

not everyone needs the whole brain

The mistake teams make at this stage: they try to make the team brain useful for everyone, so they cram everything into one folder. The BA gets a folder full of schema docs they don't need; the DBA wades through customer-discovery transcripts to find the runbook; the PM has to skip past API contracts to read the roadmap. The brain becomes a haystack with the team's name on it.

The fix isn't separate brains — that's how you end up with five contradictory customer-context.md files. The fix is role overlays: a thin per-role file that says "load these subset of the shared base for me, plus these role-specific extras." One source of truth. Five role-tuned views of it.

This module is T04 of the Team Brain track. The shared base (T01) is the prerequisite; this is what makes the base scale past five people.

// 01 · The role-overlay pattern

The shared base from T01 is four files: team-identity.md, project-shared.md, state-shared.md, decisions.md. Once your team grows past 5–6 people across different functions, those four aren't enough — but the answer isn't to add 20 more files to one folder and tell everyone to "just load what's relevant." Humans don't, and neither do their AIs.

The answer is a role overlay: a single short file per role that says "for this role, here's the subset of the base to load, here's what to skip, and here are the extras layered on top." The base stays canonical — one source of truth. The overlay is just a view.

Every overlay file follows the same 3-block structure:

// role-{slug}.md template

# Role — {Role Name}

## loads
— from the shared base, read these files in full:
- team-identity.md
- <additional base files for this role>

## skips
— don't load these even if a wrapper points at them:
- <base files that aren't load-bearing for this role>

## extends
— role-specific extras, layered on top of the base:
- <extras-1>.md
- <extras-2>.md
- <extras-3>.md

## prompts (top 3, copy-paste)
1. ...
2. ...
3. ...

Three things matter about the structure:

Anti-pattern: forking the base into role-specific copies. You'll see this when a teammate says "the BA wants their own version of customer-context.md because the technical jargon confuses them," and someone helpfully creates customer-context-ba.md next to the original. Six weeks later the two files have drifted — the PM updates one, the BA updates the other, the architect reads both and notices the contradiction in a meeting. The team brain is now actively worse than no team brain, because it's confidently wrong. The fix isn't a fork; it's a view — a thin layer on top of the canonical file that filters or annotates. We'll come back to this in section 4.

// 02 · Two worked examples

The shape is clearer with two roles than with five. Below: a BA overlay and a DBA overlay walked through in full — chosen because they're maximally different (the BA loads customer context but skips the stack; the DBA inverts it). Same three blocks, opposite contents. Once you see that contrast, the pattern applies to any role your team has — PM, Support, Architect, Security, On-call — not from a canonical PickBits list, but from your team's actual roster.

// BA · Business Analyst

Loads team-identity (always) + customer-context + recent-decisions. Skips stack-map — the BA doesn't need to know the database migration order to do their job, and giving them that file just buries the requirements signal. Extends with the BA's working artifacts: a requirements-rubric, customer-interview templates, jobs-to-be-done framing.

// role-ba.md

# Role — Business Analyst

## loads
- team-identity.md
- customer-context.md
- recent-decisions.md  (last 10 entries from decisions.md)

## skips
- stack-map.md        (engineering-only; not load-bearing for requirements work)
- incident-runbooks.md

## extends
- requirements-rubric.md           (acceptance-criteria checklist + INVEST test)
- customer-interview-templates.md  (5 templates: discovery, validation, pain, JTBD, churn)
- jobs-to-be-done.md               (current JTBD map for this product)

## prompts (top 3)
1. Draft acceptance criteria for {feature}
2. Convert this customer quote into a Job To Be Done
3. Review this PRD against requirements-rubric.md

The two prompts a BA's AI runs every week:

// BA prompt 1 · draft acceptance criteria

You have role-ba.md loaded.

Draft acceptance criteria for: {feature name}.

Constraints:
- One Given/When/Then per criterion. No compound conditions.
- Each criterion must be testable by someone who has not read the PRD.
- Cite the customer-context.md section that motivates each criterion.
- Run the INVEST test from requirements-rubric.md after drafting; surface any
  criterion that fails Independent, Negotiable, or Testable.
- If a criterion would require info that isn't in customer-context.md or
  recent-decisions.md, mark [NEEDS INPUT] instead of guessing.

// BA prompt 2 · PRD review against rubric

You have role-ba.md loaded.

Review this PRD against requirements-rubric.md.

For each rubric item:
- Pass / fail / partial. One line of evidence (quote from the PRD).
- If fail or partial: the one change that would fix it.

Then cross-check:
- Does the PRD contradict anything in recent-decisions.md? Quote both.
- Does it miss a stakeholder named in customer-context.md? Name them.
- Is there a jobs-to-be-done entry this PRD addresses? Name the job; if there
  isn't one, flag that the PRD lacks a clear JTBD anchor.

Output as a single review block I can paste back into the PRD's comments.

// DBA · Database Administrator

Loads team-identity + stack-map (deep — the DBA needs every detail of it) + recent-decisions. Skips customer-context — not because customers don't matter, but because customer-discovery transcripts and persona docs are noise when the question is "is this migration safe to run at 2am Sunday?" Extends with schema-history, incident-runbooks, migration-checklist.

// role-dba.md

# Role — Database Administrator

## loads
- team-identity.md
- stack-map.md         (full — every service, every dependency, every owner)
- recent-decisions.md  (last 20 entries; longer window than BA because schema
                        decisions ripple for years)

## skips
- customer-context.md  (not load-bearing for schema / migration / incident work)
- jobs-to-be-done.md

## extends
- schema-history.md    (every migration in order: date, table, change, why)
- incident-runbooks.md (one runbook per known incident class: lock contention,
                        replica lag, disk pressure, runaway query, bad index)
- migration-checklist.md (pre-flight + post-flight gates for any schema change)

## prompts (top 3)
1. Pre-flight this migration: {migration plan}
2. Triage this incident from the symptoms: {symptoms}
3. Why did we pick {choice} for {schema decision}? — cite schema-history.md

// DBA prompt 1 · migration pre-flight

You have role-dba.md loaded.

Pre-flight this migration plan: {paste plan}.

Walk through migration-checklist.md gate by gate. For each gate:
- Pass / fail / unclear. One-line evidence.
- For fail / unclear: the question I need to answer before running.

Then cross-check against schema-history.md:
- Has this table been touched in the last 90 days? By what migration?
- Are there known indices or constraints that this migration assumes?
- Is there a prior migration that established a pattern (locking, batching,
  online vs offline) we should match here for consistency?

End with one sentence: "Ship as-is" / "Ship with these N changes" / "Don't ship
yet — here's what to resolve first."

// DBA prompt 2 · incident triage from symptoms

You have role-dba.md loaded.

Symptoms reported: {symptoms}. Time window: {when}. Affected service(s): {svc}.

Match these symptoms to incident-runbooks.md:
- Most likely class. Second-most. Third.
- For each: the 3 fastest checks (commands or dashboard queries) that confirm
  or rule it out.

Cross-reference stack-map.md:
- Which downstream services depend on the affected one? Who owns each?
- Are there known cascade patterns from prior similar incidents (cite
  schema-history.md or recent-decisions.md if relevant)?

Output the runbook entry to follow next. If no runbook matches, draft a new
runbook stub I can fill in after the incident is resolved.

// the same pattern, other roles

The shape is identical. Three blocks, swapped contents. Pick the role; ask what context they need to load, what they can safely skip, and what role-specific artifacts they extend the brain with. A few your team probably has:

  • PM — loads customer-context + recent-decisions + who-is-who; skips deep stack-map; extends with roadmap.md, customer-interview-archive.md, prioritization-rubric.md.
  • Support — loads customer-context + who-is-who; skips deep stack-map and prioritization rubrics; extends with ticket-playbooks.md, escalation-tree.md, common-customer-blockers.md.
  • Architect — loads the whole base (the only role that does); extends with design-history.md, trade-off-rubrics.md, future-state-roadmap.md.
  • Security / On-call / Marketing / Sales — same drill. Start from the role closest in shape (Security ≈ DBA; Marketing ≈ PM; Sales ≈ Support), copy that overlay, walk the three blocks, ship.

Section 5 walks through spinning up a new overlay end-to-end with a Security Engineer worked example. The lesson is the method, not a 5-role canon.

// 03 · The composition prompt

None of this works without the composition prompt — the short instruction the AI runs at session start that tells it how to combine the role overlay with the base. It's a two-step: read the overlay, then read what the overlay says to read.

// composition prompt · paste at session start (or wrap in CLAUDE.md / AGENTS.md)

Load my Team Brain for this session.

Step 1: Read role-{slug}.md. Parse its three blocks: loads, skips, extends.
Step 2: For every file listed in "loads" and "extends", read it into your
        working context. Skip every file listed in "skips" — do not load it
        even if another wrapper points at it.
Step 3: Confirm with one line summarizing what's loaded: role name, count of
        loaded files, count of extends files, anything in skips that you
        would normally have loaded by default.

If a file referenced by the overlay is missing or empty, flag it; don't
substitute a guess. If two loaded files contradict each other, surface the
contradiction with a quote from each — do not silently pick one.

After confirm, wait for my first task.

Why the two-step matters: the role overlay is the only file the AI has to parse to know what role you're working as. Everything else cascades from the three blocks — loads, skips, extends. If you decide tomorrow that the BA should also load the stack-map, you change one line in one file and every BA session picks it up. No re-training, no re-prompting, no team-wide Slack message.

Variants — task overlays. Role overlays answer "who are you?" Task overlays answer "what are you doing right now?" Both compose:

The composition prompt for a task overlay just gets one more step: "Then read task-{slug}.md and apply its loads/skips/extends on top of the role overlay. Task skips win over role loads — if the task says skip something the role loads, skip it." Roles are stable; tasks are situational.

// 04 · How NOT to fork

The whole pattern depends on one rule:

// the rule

  • No fact lives in more than one file. Overlays are views of the base. If a fact appears twice, one of the copies is already drifting.

This rule sounds easy until the BA says "can I have a version of customer-context.md with the technical jargon stripped, because I keep losing the thread?" The wrong move is to fork the file. The right move is to add a view: views/customer-context-plain.md that says "this is the customer-context, with the ‹technical-detail› spans collapsed and the jargon replaced via the glossary in team-identity.md." The plain-English view doesn't store facts — it stores a transformation. Update the base; the view stays correct.

The 3-question test before forking anything:

  1. Is this NEW information, or a different VIEW of existing information? If view: don't fork; add a view layer. If new info: it belongs in the base or in an overlay's extends, not as a fork of an existing file.
  2. If the underlying fact changes, do both copies need updating? If yes: it's a fork waiting to drift. Refuse.
  3. Is there a teammate who needs both views? If yes (the architect always needs both views): the views must be derived from the same base, not maintained independently.

Anti-pattern catalog — what forks look like in the wild:

// 05 · Adding a new role

A security engineer joins the team. You don't have a role-security.md. The pattern is designed so spinning one up takes 15 minutes — before the new hire's first day. Here's the drill.

// 15-minute new-role drill

  • Step 1 · 2 min · name it. Lowercase, hyphenated, one word per concept. role-security.md. Not role-secops-engineer.md, not role-cyber.md. The slug becomes the filename, the breadcrumb, the prompt argument — pick one form and stick with it.
  • Step 2 · 3 min · copy the closest template. Security looks more like DBA (deep technical, incident-flavored) than like BA (requirements-flavored). Copy role-dba.md to role-security.md. Change the heading, then walk the loads/skips/extends:
    • loads: keep team-identity, stack-map, recent-decisions. Maybe add who-is-who (security needs every owner).
    • skips: customer-context? probably yes. jobs-to-be-done? definitely.
    • extends: replace DBA's extras with security's. (Step 3.)
  • Step 3 · 5 min · name the 1–3 role-specific extras and stub them. For security: compliance-frameworks.md (which frameworks the team is on the hook for — SOC2, ISO, HIPAA, etc.), threat-models.md (the current threat model for each major surface), incident-runbooks-security.md (security-flavored runbooks: data exposure, credential leak, supply-chain). Don't try to fill them in this 15-minute drill — just create the files with a one-line TBD header. The new hire will fill them as part of week one onboarding (T03's "first 30 days" arc).
  • Step 4 · 3 min · write the 3 most likely Day-1 prompts. Cross-reference T03's onboarding format. For security, those are probably: (1) "Walk me through the current threat model for {surface} citing threat-models.md", (2) "Which compliance framework controls does {decision} affect? cite compliance-frameworks.md", (3) "Pre-flight this change for security risk — quote any related decision from recent-decisions.md".
  • Step 5 · 2 min · commit, announce, link. Commit the new overlay and the three stubbed extras in one PR. Drop a one-liner in the team channel: "Spun up role-security.md ahead of {new hire} starting Monday. Stubs to flesh out: compliance-frameworks, threat-models, incident-runbooks-security. {new hire} will fill these in week 1." Add the new role to the table in who-is-who.md (so the architect's overlay surfaces them).

The "is this its own role?" decision tree. Not every new hire needs a new overlay. The cheap test: would the new hire's daily AI session load a meaningfully different set of files from any existing role's? If yes — new overlay. If no — extend an existing one with the personal context-stack from T03 (Module 01-style personal extras layered on top of an existing role).

// 06 · The conflict prompt

Two role overlays will eventually disagree. The BA's customer-context.md view says the top customer pain is onboarding friction; the PM's customer-interview-archive.md rolls up "pricing confusion" as the most-mentioned theme. Both citations are real. Who's wrong?

Usually: neither. The disagreement is a signal that the base is missing a fact — a fact both overlays would have used if it had been in the base. The conflict prompt surfaces these:

// conflict prompt · weekly steward task

Compare role-{a}.md and role-{b}.md.

For each base file they BOTH load or BOTH extend, check whether their use
of that file is consistent. Examples of inconsistency:
- They cite the same file but draw opposite conclusions.
- One quotes a section the other treats as missing.
- They reference the same person but assign different ownership.

For each file one loads and the other skips, decide whether the exclusion
is deliberate (different roles, different needs — fine) or accidental
(this role probably should be loading it — surface for review).

For each conflict found, output:
- Files in conflict.
- One-sentence summary of the disagreement.
- Quote from {a}; quote from {b}.
- One question I should answer to resolve it.

Do not silently pick a winner. Do not invent a resolution.

Resolution rules — facts vs. preferences:

The Friday overlay review — 10 minutes a week. The steward picks one overlay (rotate weekly) and audits its loads/skips against actual usage signals from the past week:

Five overlays × 10 minutes each = one overlay per week with 3 weeks of breathing room. The brain stays tuned to how the team actually works, not how it worked when the overlays were first written.

// Key takeaways

// one base, many views

  • One base, many views. The shared base (T01's four files + a couple of extras) is canonical. Role overlays are views on it — not duplicates.
  • Three-block overlay file. loads · skips · extends. The whole pattern fits in a 15-line markdown file per role.
  • The composition prompt is the only entry point. Read role-{slug}.md, then read what it says to read. One file determines a session; everything else cascades.
  • No fact lives in more than one file. When tempted to fork, add a view instead. Drift is the only failure mode that kills a team brain.
  • Conflicts mean the base is missing a fact. Don't pick a winner; surface the disagreement, fix the base, both overlays converge.
← Back to Team Brain track T01 · Shared Folder — the prereq