diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/plans/2026-04-07-people-rolodex-implementation.md | 239 | ||||
| -rw-r--r-- | docs/plans/2026-04-07-people-roster-design.md | 151 |
2 files changed, 0 insertions, 390 deletions
diff --git a/docs/plans/2026-04-07-people-rolodex-implementation.md b/docs/plans/2026-04-07-people-rolodex-implementation.md deleted file mode 100644 index 16578f8..0000000 --- a/docs/plans/2026-04-07-people-rolodex-implementation.md +++ /dev/null @@ -1,239 +0,0 @@ -# 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. diff --git a/docs/plans/2026-04-07-people-roster-design.md b/docs/plans/2026-04-07-people-roster-design.md deleted file mode 100644 index f68b140..0000000 --- a/docs/plans/2026-04-07-people-roster-design.md +++ /dev/null @@ -1,151 +0,0 @@ -# People Roster Design - -## Goal - -Turn the managed-people list into a small, searchable database inside Emacs. -The setup should make it easy to: - -- look up a person quickly by name -- see role and engagement type at a glance -- filter the roster by manager, role, or employment type -- keep notes and follow-ups close to the record -- avoid duplicating the same information across multiple files - -## Recommendation - -Use a single Org file as the source of truth and layer completion plus search on top of it. - -Recommended stack: - -- `org-mode` for storage -- `consult` for fast lookup -- `corfu` or `completion-at-point` for inline name completion when typing inside notes -- `embark` for actions on a selected person -- `org-ql` for filtered views and reports - -This keeps the data editable in plain text while still making it queryable and useful as a working tool. - -## Data Model - -Store one person per Org heading in `~/org/areas/people/roster.org`. - -Suggested properties: - -- `NAME` -- `ROLE` -- `ENGAGEMENT` with values such as `permanent`, `sow`, or `other` -- `TEAM` -- `MANAGER` -- `EMAIL` -- `LOCATION` -- `NOTES` - -Example: - -```org -* Ajay Shirke -:PROPERTIES: -:NAME: Ajay Shirke -:ROLE: Engineering Manager -:ENGAGEMENT: permanent -:TEAM: Platform -:MANAGER: You -:EMAIL: ajay@example.com -:END: - -Current context, follow-ups, or other notes go here. -``` - -## Lookup Workflow - -Add a command that prompts for a person and opens their entry. - -Typical flow: - -1. `M-x ss/people-find` -2. type a name, role, or partial string -3. preview matching entries -4. open the selected person - -The lookup command should display useful summary text in the completion UI, such as: - -- full name -- role -- engagement type -- team - -That makes the list useful even before opening the record. - -## Inline Completion - -Use Corfu only for in-buffer completion when typing names in notes, tasks, or meeting logs. - -The CAPF should: - -- trigger on word boundaries -- offer canonical names from the roster -- annotate candidates with role and engagement type -- stay read-only and avoid changing the buffer - -This is a narrow use of completion: it helps insert a person’s name without turning the completion layer into the database itself. - -## Actions - -Use Embark-style actions on a selected person so lookup is not a dead end. - -Useful actions: - -- open the person’s Org entry -- copy a short summary -- insert the name into the current buffer -- insert a formatted roster card -- jump to related notes or follow-ups - -This makes completion a launcher for common manager tasks. - -## Reports - -Use `org-ql` or equivalent Org searches for views that answer manager questions. - -Useful reports: - -- all `permanent` people -- all `sow` people -- people grouped by role -- people grouped by manager -- people with notes older than a threshold - -These reports should be generated from the same Org file rather than maintained separately. - -## File Layout - -Planned files: - -- `config.org` - - adds the lookup commands, completion functions, and report helpers -- `~/org/areas/people/roster.org` - - stores the roster entries - -Optional later additions, only if needed: - -- `~/org/areas/people/notes/` - - supporting notes for long-lived context - -## Trade-offs - -Why this approach: - -- one source of truth -- plain-text editing -- easy search and filtering -- works well with existing Org habits - -What it avoids: - -- a separate database format to learn -- duplicated JSON or Lisp data files -- maintaining one file for lookup and another for reporting - -## Next Step - -Implement the roster helpers in `config.org`, then add the first few people entries to `~/org/areas/people/roster.org`. |