minutes-brief

# /minutes-brief

Fast, non-interactive briefing that synthesizes your relationship history with someone into a one-page brief — designed so you can read it in 60 seconds before walking into a call.

This is the **proactive layer**. It's built to be invoked silently by a hook (e.g., 15 min before a calendar event) and to also work as a manual `/minutes-brief` command. Unlike `/minutes-prep`, brief asks no questions and sets no goals — it just hands you the facts.

## How it works

### Phase 0: Determine the target

Three ways the user can invoke this:

**1. With a name** (`/minutes-brief sarah`, "brief me on Alex")
→ Use that name directly. Before searching, check for learned aliases:

```bash
node "${CLAUDE_PLUGIN_ROOT}/hooks/lib/minutes-learn-cli.mjs" aliases "<name>" 2>/dev/null
```

If aliases exist, search across all returned variants and treat them as the same person for the rest of the flow. If the user explicitly says two names are the same person, persist it:

```bash
node "${CLAUDE_PLUGIN_ROOT}/hooks/lib/minutes-learn-cli.mjs" set-alias "Sarah Chen" "Sarah" "User confirmed these refer to the same person"
```

Then skip to Phase 1.

**2. With "auto" or no argument** (`/minutes-brief`, "brief me on my next call")
→ Auto-detect the next upcoming calendar event. Try sources in order — use the first that works:

- **Google Calendar MCP** (best — Claude users):
  ```
  gcal_list_events(timeMin: "<now ISO>", timeMax: "<+2hr ISO>", condenseEventDetails: false)
  ```
  Filter to events with 2+ attendees, skip all-day events, pick the soonest. Pull attendee names from the event.

- **`gog` CLI** (if installed):
  ```bash
  gog calendar list --today --json 2>/dev/null
  ```

- **Apple Calendar via osascript** (every Mac, zero install):
  ```bash
  osascript -e 'tell application "Calendar" to get {summary, start date} of (every event of every calendar whose start date >= (current date) and start date < ((current date) + 2 * hours))'
  ```

If none return anything, ask once: "I can't find an upcoming meeting. Who do you want a brief on?" Then take whatever they say and move on.

**3. Hook-fireable mode** (`/minutes-brief --auto`, or invoked silently from a hook)
→ Same as auto, but **never ask questions**. If no upcoming meeting and no name, exit silently with no output. Hooks should never spam the user.

### Phase 1: Gather data in parallel

The Minutes CLI already does the hard work. Fire all four of these as separate Bash tool calls in the same message — Claude Code will run them in parallel because they're independent. **The CLI's stream contract is messy; each command below has a specific shape documented below the block — read them before running.**

```bash
# 1. Person profile. stdout is CONTAMINATED: WARN tracing lines + JSON, mixed.
#    Use sed to extract from the first "{" to EOF before parsing as JSON.
minutes person "<name>" 2>/dev/null | sed -n '/^{/,$p'

# 2. Open commitments — what they owe you and what you owe them.
#    Clean JSON on stdout when --json is passed.
minutes commitments -p "<name>" --json 2>/dev/null

# 3. Recent decisions involving them, last 30 days.
#    Clean JSON on stdout by default (insights does NOT accept --json — output is already JSON).
minutes insights --participant "<name>" --kind decision --since <30-days-ago> 2>/dev/null

# 4. Recent meetings with them, last 60 days. Newline-delimited JSON (one object per line).
minutes search "<name>" --limit 10 --since <60-days-ago> --format json 2>/dev/null
```

**CLI stream-handling notes** — the Minutes CLI is actively developed and its stream contract is not fully settled. Today (0.8.0):

- `minutes person` writes tracing WARN lines **and** the JSON profile to **stdout** (not stderr, as you'd expect). The WARN lines appear first. The `sed -n '/^{/,$p'` pipe above strips them. If you pass `minutes person`'s raw stdout to a JSON parser, it will blow up on the first WARN line.
- `minutes person` also writes a human-readable summary ("Profile for Mat: …") to **stderr**. Harmless but weird. We redirect stderr to `/dev/null` to keep it out of the pipeline.
- `minutes commitments --json`, `minutes insights`, `minutes search --format json`, and `minutes people --json` all produce clean JSON on stdout when stderr is redirected. No extraction needed.
- **Do not invent new flags** on top of what's shown above — e.g. `minutes insights --json` is not a real flag, `minutes export --since` is not a real flag. The CLI will reject unknown flags with a usage error.

If a future CLI release changes any of these contracts, update this skill in the same PR that ships the CLI change.

**The `minutes person` empty-but-not-empty trap.** Some real meetings have malformed frontmatter that the CLI's strict schema rejects — you can see it in the WARN lines. When that happens, `minutes person "<name>"` returns an empty profile (`{"recent_meetings": [], ...}`) **even though meetings with that person actually exist on disk**. Before declaring "first meeting on record", always cross-check with `minutes search`:

```bash
minutes search "<name>" --limit 1 --format json 2>/dev/null
```

If `search` returns hits but `person` is empty, surface that as: "I have meetings with this person on record but the person profile is broken (likely a frontmatter schema issue). Here's what search found instead." Then read those meeting files directly and synthesize from the raw transcripts. Never lie to the user about a "first meeting" when it isn't one.

For multi-attendee meetings, focus on the **single most-mentioned attendee** (the one with the highest meeting count via `minutes person`). Mention the others briefly at the end. Don't try to brief 5 people at once — it dilutes the signal to nothing.

### Phase 2: Read what you actually need

Extract the file paths of the most recent 1–2 meetings from `minutes search`'s JSON output. Each line of the search output is a JSON object with a `path` field — the absolute path to the meeting file. Parse those, t