# 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`.