path: root/docs/plans/2026-04-07-people-rolodex-implementation.md

# People Rolodex Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** Replace the old roster and name-dictionary setup with a lightweight `~/org/people.org` rolodex that powers lookup, completion, reports, and dynamic people abbrevs from one Org file.

**Architecture:** Keep a single cached parser for top-level headings in `~/org/people.org`, treat each heading as one person card, and build all lookup and insertion commands from that cache. Use explicit Org commands for overview/card mode, a small CAPF for Corfu, Marginalia annotations for minibuffer completion, dynamic buffer-local abbrevs sourced from the parsed cards, and a dedicated interactive add-person command that writes a compact subtree directly into `people.org`.

**Tech Stack:** Emacs Lisp, Org mode, Vertico, Orderless, Marginalia, Corfu, CAPF, abbrev

---

### Task 1: Replace the old name dictionary and roster model in `config.org`

**Files:**
- Modify: `config.org`

**Step 1: Write the failing test**

Define the expected end state as code-level checks while editing:

- there is no reference to `name-dictionary.el`
- there is no reference to `ss/people-roster-file`
- there is no capture template that writes a roster entry
- the rolodex source file points to `~/org/people.org`

**Step 2: Run test to verify it fails**

Run: `rg -n "name-dictionary|people-roster|roster.org" config.org README.md`

Expected: FAIL by finding the legacy model still present.

**Step 3: Write minimal implementation**

In the “Name shortcuts” section:

- rewrite the prose to describe the lightweight rolodex
- remove the legacy dictionary variables and functions
- remove the old roster parsing code
- add a single `ss/people-file` constant consumer model
- add entry parsing helpers for:
  - canonical name
  - abbrev
  - aliases
  - role
  - location
  - engagement
  - relationship
  - current focus
  - team
- cache entries by `file-attribute-modification-time`
- parse only level-1 headlines

**Step 4: Run test to verify it passes**

Run: `rg -n "name-dictionary|people-roster|roster.org" config.org`

Expected: PASS with no remaining legacy implementation references.

**Step 5: Commit**

Do not commit yet. Verification and README updates are still pending.

### Task 2: Implement rolodex overview, card view, lookup, insertion, reports, and add-person flow

**Files:**
- Modify: `config.org`

**Step 1: Write the failing test**

List the required commands before coding:

- `ss/people-open`
- `ss/people-find`
- `ss/people-overview`
- `ss/people-insert-name`
- `ss/people-insert-summary`
- `ss/people-report-by-relationship`
- `ss/people-report-by-engagement`
- `ss/people-report-by-role`
- `ss/people-report-by-location`
- `ss/people-add`

Also require:

- aliases match but insert canonical names
- reports group under Org headings in a read-only buffer
- opening `people.org` always restores overview mode

**Step 2: Run test to verify it fails**

Run: `rg -n "defun ss/(people-open|people-find|people-overview|people-insert-name|people-insert-summary|people-report-by-relationship|people-report-by-engagement|people-report-by-role|people-report-by-location|people-add)" config.org`

Expected: FAIL because some or all required commands do not exist yet.

**Step 3: Write minimal implementation**

Add:

- file creation helper for `~/org/people.org`
- overview-mode helper that widens, jumps to start, and shows top-level headings only
- entry-open helper that widens, jumps, narrows to subtree, and reveals subtree
- minibuffer completion metadata and Marginalia annotator
- CAPF that returns canonical names and single-line annotations
- insertion helpers for canonical name and compact summary
- grouped report renderer
- interactive prompts for add-person, including default abbrev generation and constrained choices for engagement/relationship
- direct Org insertion for a compact starter card with `Context` and `TODOs` sections

**Step 4: Run test to verify it passes**

Run: `rg -n "defun ss/(people-open|people-find|people-overview|people-insert-name|people-insert-summary|people-report-by-relationship|people-report-by-engagement|people-report-by-role|people-report-by-location|people-add)" config.org`

Expected: PASS with all commands present.

**Step 5: Commit**

Do not commit yet. Generated files and docs still need verification.

### Task 3: Rewire Org directories, keybindings, and capture flow to the new people model

**Files:**
- Modify: `config.org`

**Step 1: Write the failing test**

Define the required workflow changes:

- `ss/org-people-directory` should no longer point to `areas/people/`
- there should be a `ss/people-file` under `~/org/`
- keybindings should point at the new rolodex commands
- `org-capture` should no longer include the old roster template

**Step 2: Run test to verify it fails**

Run: `rg -n "areas/people|nR|people-roster|C-c n r" config.org`

Expected: FAIL by showing the old path and capture/binding behavior.

**Step 3: Write minimal implementation**

- update Org path constants so people notes are no longer treated as a PARA subdirectory
- make `people.org` part of the created note roots where appropriate
- keep Denote people-note capture removed or re-scoped so the rolodex remains distinct from narrative notes
- bind the new commands to sensible keys, including a way to open `people.org` and add/find people

**Step 4: Run test to verify it passes**

Run: `rg -n "areas/people|nR|people-roster" config.org`

Expected: PASS with the roster model removed.

**Step 5: Commit**

Do not commit yet. Documentation and generated output still need verification.

### Task 4: Update the README to reflect the new rolodex end state

**Files:**
- Modify: `README.md`

**Step 1: Write the failing test**

Identify stale statements to remove:

- references to `name-dictionary.el`
- references to `~/org/areas/people/roster.org`
- manager/email/employee-time roster fields
- capture docs for the old roster template

Add the new documented state:

- `~/org/people.org` is the only source of truth
- commands, keybindings, reports, and overview/card behavior
- people-specific abbrevs come dynamically from `people.org`

**Step 2: Run test to verify it fails**

Run: `rg -n "name-dictionary|roster.org|manager|employee time|email" README.md`

Expected: FAIL because the README still documents the old roster.

**Step 3: Write minimal implementation**

Edit the README sections for:

- note layout
- completion setup
- abbrevs
- capture flow
- note creation and linking

Make the current workflow truthful and concise.

**Step 4: Run test to verify it passes**

Run: `rg -n "name-dictionary|roster.org|employee time" README.md`

Expected: PASS with stale docs removed.

**Step 5: Commit**

Do not commit yet. Final verification still needs to run.

### Task 5: Tangle and verify the generated configuration

**Files:**
- Modify indirectly via tangling: `init.el`

**Step 1: Write the failing test**

Require two checks:

- `config.org` tangles without Lisp errors
- generated `init.el` loads under batch Emacs

**Step 2: Run test to verify it fails**

Run: `emacs --batch -Q --eval '(progn (require (quote ob-tangle)) (org-babel-tangle-file "config.org"))'`

Expected: If there are syntax or tangle issues, this fails and guides fixes.

**Step 3: Write minimal implementation**

Fix any syntax, quoting, or load-order issues reported by the tangle or load checks.

**Step 4: Run test to verify it passes**

Run: `emacs --batch -Q --eval '(progn (require (quote ob-tangle)) (org-babel-tangle-file "config.org"))'`

Expected: `init.el` and `early-init.el` are regenerated successfully.

Run: `emacs --batch -Q --load ./init.el`

Expected: Emacs exits successfully after loading the generated main config.

**Step 5: Commit**

Stop after verification and summarize the verified unit to the user before any commit.