Ppl

ppl: People Manager for the Brain Vault

you works with a lot of people. This skill turns "Alice Perl is a Security Researcher in my team" into a permanent, cross-referenced wiki entity. Once filed, every future synthesis, daily sync, save, or ingest links the mention to the person's page.

The wiki compounds. People compound too.

---

Vault Layout

• Vault root: ~/digital-brain/
• People folder: wiki/entities/people/ (create if missing)
• People index: wiki/entities/people/_index.md (create if missing — the canonical roster)
• Wiki index: wiki/index.md — has an ## Entities section; person rows live there too
• Log: wiki/log.md — append a ppl entry at the TOP after every add/edit
• Hot cache: wiki/hot.md — touch only if the person is currently active in recent threads

Why a sub-folder under entities/? Existing entity pages (Your Organization.md) live in wiki/entities/ directly. Keep organizations and tools there; group people under wiki/entities/people/ so the roster is greppable as one set.

---

Invocation Forms

Form	Action
/ppl <Name> <free-text role / context>	add (default) — create new person page
/ppl add <Name> <free-text>	same as above, explicit
/ppl edit <Name>	update existing person page
/ppl list	show the roster from _index.md
/ppl lookup <Name or alias>	display the person's page

If $ARGUMENTS is empty, show the four forms and ask which one.

---

Parsing /ppl <Name> <tail>

1. Split tokens. The Name is the leading run of [A-Z][a-z']+ tokens (capitalized words). Take the first 2 capitalized tokens by default. If only one capitalized token, take 1. If 3+ consecutive capitalized tokens before a lowercase word (e.g. Mary Jane Watson), take 3.
2. The tail is everything after the name — that's role + relationship + free context.
3. Heuristics on the tail (do not over-fit, but capture what's obvious):
   • Role — the noun phrase before "in/at/on/of" or before "my". Examples: Security Researcher in my team → role Security Researcher; head of engineering → role Head of Engineering.
   • Relationship to you — look for: my manager, my team, co founder / cofounder / co-founder, cpo, cto, ceo, head of …, peer, report, direct report, reports to me. Map to a short relationship value: manager, teammate, direct-report, cofounder, executive, peer, external. If multiple apply, store the closest to you (e.g. cofounder over executive).
   • Team — capture <role> in my team → team Your Organization unless tail says otherwise.
   • Company — default Your Organization if no other company is named; if the tail names a different company, use that.
4. Anything unparsed stays as free-form context in the page body. Don't drop it.

If parsing is ambiguous (e.g. lowercase first name, missing role), proceed with best-effort and add a > [!todo] Confirm callout at the bottom of the page listing the fields you weren't confident about.

---

add Workflow

1. Resolve the Full Name (parsing above). Slug = the Full Name verbatim (Obsidian filenames allow spaces).
2. Duplicate check: Glob wiki/entities/people/*.md and also check _index.md aliases. If a match exists (exact name, alias, or a single capitalized-token match like "Alice"):
   • Offer: "Already filed as [[Full Name]]. Run /ppl edit <Name> to update, or use a different name."
   • Stop unless the user typed /ppl add explicitly with a clearly distinct full name.
3. Ensure folder + index exist. If wiki/entities/people/ is missing, create it. If _index.md is missing, create it from the template in this skill (see "Templates" below).
4. Create wiki/entities/people/<Full Name>.md from the Person Page Template. Fill:
   • title, entity_type: person
   • role, relationship, team, company
   • created, updated to today (ISO YYYY-MM-DD)
   • aliases: include the first name and any obvious short form
   • tags: [entity, person, <relationship>, <team-slug>]
5. Update _index.md: add a row to the table under the matching relationship section (Team / Leadership / External / Other). Sort each section alphabetically by first name.
6. Update wiki/index.md: under the ## Entities section, add or update a bullet:

   - [[<Full Name>]] - <role>, <relationship>
   

   Keep the existing [[Your Organization]] line in place; people append below organizations.
7. Append to wiki/log.md at the TOP (under the header):

   ## [YYYY-MM-DD] ppl | <Full Name>
   - Role: <role>
   - Relationship: <relationship>
   - Location: wiki/entities/people/<Full Name>.md
   - From: /ppl invocation
   

8. Hot cache: only touch wiki/hot.md if the user explicitly says they're working with this person right now ("we're on a call", "we just shipped X together"). Default = no hot update.
9. Confirm: "Filed [[<Full Name>]] — <role>, <relationship>. Future mentions will link to this page."

---

edit <Name> Workflow

1. Resolve <Name> against filenames in wiki/entities/people/ and aliases in _index.md. If ambiguous, list candidates and ask.
2. Read the current page. Show the user the current frontmatter + body.
3. Ask what changed (role, relationship, team, context).
4. Apply edits. Bump updated: to today.
5. If a quick-reference field changed (role / relationship), also update the _index.md row and the wiki/index.md bullet.
6. Append a brief log entry: [YYYY-MM-DD] ppl edit | <Full Name> — <what changed>.

---

list Workflow

1. Read wiki/entities/people/_index.md.
2. Render the tables as-is. Show total count.
3. If _index.md doesn't exist yet, report "No people filed yet — try /ppl <Name> <role>".

---

lookup <Name or alias> Workflow

1. Find a match by filename or by aliases in _index.md. If multiple, ask.
2. Read and display the page. Highlight role, relationship, recent context.
3. Also surface recent log entries that mention [[<Full Name>]] (grep -l "[[<Full Name>]]" wiki/log.md wiki/hot.md).
4. If not found, suggest /ppl <Name> <role>.

---

Cross-Reference Rule (the whole reason this skill exists)

Once a person is filed, every wiki write must wikilink them. That includes:

• /save (synthesis, source, decision, session notes)
• /sync (daily mentions, topics, calendar)
• wiki-ingest (any extracted person whose name matches an existing people page)
• Manual edits to wiki/hot.md, wiki/index.md, etc.

The rule: when writing any wiki content, before saving, scan the draft for substrings matching (?:^|[^\[])<First>(?: <Last>)?(?:[^\]]|$) for each person in _index.md. If a match isn't already inside a wikilink, wrap it: [[Full Name]] (or [[Full Name|alias]] if you want display text to differ).

This is non-negotiable. The compounding value of the wiki is the link graph — an unlinked mention is a dead branch.

If a draft has 3+ mentions of the same person, link only the first mention to keep prose clean.

---

Templates

Person Page Template

---
type: entity
entity_type: person
title: "<Full Name>"
role: "<Role>"
relationship: "<relationship>"
team: "<Team or — >"
company: "<Company>"
aliases:
  - <First Name>
created: <YYYY-MM-DD>
updated: <YYYY-MM-DD>
tags:
  - entity
  - person
  - <relationship>
status: filed
related:
  - "[[entities/people/_index|People Index]]"
  - "[[Your Organization]]"
sources:
---

# <Full Name>

**Role:** <Role>
**Relationship to you:** <relationship description in plain English>
**Team / Company:** <Team>, <Company>

## Context

<free-form notes captured from the /ppl tail and any subsequent conversation>

## Recent Threads

<!-- Filled in over time by /sync, /save, and ingests. Each line: a date + a brief note + wikilink to the source page. -->

## Related

- [[Your Organization]]
- [[entities/people/_index]]

_index.md Template (create on first add if missing)

---
type: meta
title: "People Index"
updated: <YYYY-MM-DD>
tags: [meta, index, people]
status: evergreen
related:
  - "[[index]]"
  - "[[Your Organization]]"
---

# People

Navigation: [[index]] | [[hot]]

Everyone you interacts with at work. Add via `/ppl <Name> <role/relationship>`.

---

## Team (Your Organization)

| Name | Role | Relationship | Aliases |
| ---- | ---- | ------------ | ------- |

## Leadership

| Name | Role | Relationship | Aliases |
| ---- | ---- | ------------ | ------- |

## External

| Name | Role | Company | Aliases |
| ---- | ---- | ------- | ------- |

## Other

| Name | Role | Notes | Aliases |
| ---- | ---- | ----- | ------- |

The four sections are fixed. New rows go into the section that matches the person's relationship:

• teammate, direct-report, peer → Team (Your Organization)
• manager, cofounder, executive → Leadership
• anyone at a different company → External
• everything else → Other

---

Examples

Example 1 — /ppl Alice Perl Security Researcher in my team

• Name: Alice Perl
• Role: Security Researcher
• Relationship: teammate
• Team: Your Organization
• Creates wiki/entities/people/Alice Perl.md, adds row to Team section of _index.md, adds - [[Alice Perl]] - Security Researcher, teammate to wiki/index.md under Entities, logs the operation.

Example 2 — /ppl Carol Chen my manager co founder cpo

• Name: Carol Chen
• Role: CPO
• Relationship: cofounder (closer to you than manager or executive, all three flagged but only the closest wins)
• Aliases: Carol
• Body context preserves "manager + cofounder + CPO" verbatim.
• Goes into Leadership section.

Example 3 — /ppl Dave Park head of engineering

• Name: Dave Park
• Role: Head of Engineering
• Relationship: executive
• Goes into Leadership section.

Example 4 — /ppl list

Reads _index.md, renders all four section tables, reports total count.

---

Error Handling

• Folder doesn't exist → create it. Don't ask.
• _index.md missing → create from template. Don't ask.
• Duplicate name → offer /ppl edit or a distinct full name. Don't overwrite silently.
• Lowercase or single-word name → ask for confirmation: "Did you mean <Name> as a full name? Add a last name or confirm."
• Empty tail (no role) → create page with role: "—", add a > [!todo] Confirm role callout in the body, and remind the user to /ppl edit later.

---

Don'ts

• Don't write to wiki/hot.md unless explicitly told the person is in active context right now.
• Don't create a page under wiki/entities/ root — people go in wiki/entities/people/.
• Don't strip the original tail text from the body — keep verbatim under ## Context so nothing the user typed is lost.
• Don't auto-delete the stray ~/digital-brain/Alice P.md at the vault root — flag it and ask.