meeting-analysis

Files (12)

• SKILL.md
• README.md · scripts/
• check_deps.sh · scripts/
• frame_dedup.py · scripts/
• install_deps.sh · scripts/
• local_asr.py · scripts/
• meeting_resolve.py · scripts/
• phash_distribution.py · scripts/
• probe_terms.py · scripts/
• recording_integrity.py · scripts/
• ruff.toml · scripts/
• transcript_diff.py · scripts/

SKILL.md (first lines)

# meeting-analysis

Turn whatever subset of meeting artifacts exists into a **citation-bearing analysis doc** that a
reader can audit against its sources.

**Usage:**

- `/meeting-analysis <zip-or-directory> [--author NAME] [--date YYYY-MM-DD] [--series NAME] [--kind recording-analysis|standup-update]`
- `/meeting-analysis --retrieve <meeting-name> [--date YYYY-MM-DD] [--time HH:MM]`
- `/meeting-analysis --retrieve --chat "<chat title>" --date YYYY-MM-DD [--time HH:MM]`

## Step 0, only with --retrieve: land the sources first

`--retrieve` is optional. It fetches the meeting's artefacts with the `teams` skill's `meeting`
command from this same repository, then continues at Step 1 with the directory it landed. Without
the `teams` skill, or for a meeting held on another platform, export the sources yourself and
start at Step 1. The command, its named-meetings config and its rules for picking an instance are
in the `teams` skill's SKILL.md; the short form:

```bash
TEAMS_DIR="$(dirname "$(realpath "${CLAUDE_SKILL_DIR}")")/teams"
uv run --script "$TEAMS_DIR/scripts/meeting.py" <meeting-name> [--date D] [--time HH:MM] --json
```

A meeting with no config entry is landed ad hoc with `--chat "<exact chat title>" --date
YYYY-MM-DD` and goes into its own `docs/meetings/<slug>-<date>/` directory
([Step 2](#step-2-the-directory-shape-is-a-convention-not-a-preference)).

**Check the sign-in first, with a read that costs nothing** (the teams skill's cheapest read, for
example a chat lookup). If it answers, carry on. If it is refused for want of a sign-in, follow the
teams skill's own sign-in section, and ask the user only for the step that needs a person. Re-run
the read to confirm before continuing.

1. Build the arguments from what the user gave. Explicit options pass through unchanged. From
   a prompt, map a named meeting to its config name (`meeting.py --list` prints them) and a day
   to `--date`; "today" is today's date in the config's timezone, and no date means the latest
   instance. **If the prompt names neither a configured meeting nor a chat with a date, ask the
   user which meeting and which day before running anything.** Never guess a chat.
2. Read the JSON object it prints. `complete: false` means an artefact is missing; `missing`
   says which. When the reason is the AI Summary, the output also printed an `AI Summary request:`
   line and an `AI Summary inbox:` line. Show both to the user, stop, and continue once the file is
   at the inbox path and the command has been re-run; an analysis written over notes without
   their AI Summary is the wrong document.
3. Treat exit 2 as a question for the user and do not retry. It means the name is unknown, the day had
   several instances and no `--time` picked one, or the output repository could not be found.
   Relay its message, which lists the choices.
4. Hand the result to Step 1: `--repo-root` is the JSON's `repo_path`; `--sources` is its
   `data_dir`; `--date`, `--author` and `--series` are its fields. When `ad_hoc` is false,
   `--meeting-root` is the parent of its `meeting_dir` and `--slug` is passed only when the JSON's
   `slug` is not null. When `ad_hoc` is true, pass `--meeting-dir <meeting_dir>` (relative to the
   repo root) and `--slug <slug>`: the doc is `<slug>-<date>/<slug>-<date>.md`. The analysis goes
   where the meeting's config says, which can be a different repository from the one you are in;
   in a git worktree, `meeting.py` takes `--repo-path <your worktree for that repository>` so
   nothing lands in a main checkout.
5. The meeting's chat is a source too. Read it before the transcript: a link, a decision or an
   action item is often only there. A transport that lands it writes `data/<title> <date> chat.md`
   (every message of the day with sender and local time, oldest first, reply quotes as quotes of
   the original message with its sender, links with their text and exact URL) and copies each
   attached file into `data/` under its own name. The `teams` skill's `land` does not write that
   file. Read the day's messages with its `thread --conv ID --date D --json` command (id, local
   time and sender per message, with an excerpt) and `messages --conv ID` (the full text), save
   them as `data/<title> <date> chat.md` in that shape, and say in provenance how the chat was read.

The deterministic parts (which doc kind, where it goes, what each source is, whether one is already
there) are done by `meeting_resolve.py` so they are not re-derived by hand each meeting. The
judgment parts (reading frames, settling a mishearing, deciding what the meeting actually settled)
are yours. Do not hand the judgment to the script or the bookkeeping to yourself.

**Every command below is written against `${CLAUDE_SKILL_DIR}`, and that is not cosmetic.** This
skill runs from a symlinked skills farm, from a repo-local `.claude/skills`, or from a vendored
copy inside a consumer repo, so a repo-relative path such as `scripts/meeting_resolve.py` resolves
to the wrong file or to nothing at all depending on which copy is active and what the working
directory is. Use `${CLAUDE_SKILL_DIR}` for the scripts and the repo's own paths for the content.

## Which copy am I?

There can be two copies of this unit on one machine: the canonical one in the skill repo and a
vendored copy inside a repo that carries meeting docs of its own.

- **The scripts are shared; the SKILL.md need not be.** The vendored unit is `scripts/**`, the
  bundled templates under `assets/`, and the shared `skill-cli-foundation` package. A consumer may
  write its own SKILL.md to carry its organisation's meetings, transport and worked examples.
- **Templates are resolved from the CURRENT repo first.** `meeting_resolve.py plan` prefers the
  working repo's committed `docs/meetings/TEMPLATE.md` (or `docs/meetings/standups/TEMPLATE.md`),
  because that is the copy a teammate reading the repo on the web will open and the copy the doc's
  relative link points at. Only when the current repo has none does it fall back to the copy this
  skill bundles under `${CLAUDE_SKILL_DIR}/assets/`, and it says which source it used.
- **When both exist and differ, `plan` reports `drifted: true`.** Say so in your report. A repo is
  allowed its own committed copy; a divergence nobody has noticed is how the two versions stop
  being the same document.
- **A vendored copy is verifiable.** A consumer repo carries `skills/vendor-lock.json` recording the
  source commit and a sha256 per file. Run
  `uv run --script "${CLAUDE_SKILL_DIR}/scripts/meeting_resolve.py" vendor-check` to confirm the copy
  is intact before trusting it; in the canonical checkout there is no lock and the command says so
  and exits 0.

## Pick the doc kind FIRST, and never bend one template into the other

Two kinds share the meetings tree. They have different sources, different purposes, and **their own
templates**. Conflating them is the known failure in this workflow.

| | Recording analysis | Standup update |
|---|---|---|
| Written | After the meeting | Before it |
| From | The recording, vendor transcript, notes export | Our own repo: git history, the task store, audit output |
| Answers | What the meeting settled, and what it did not | What we did since last time, and what is actually true now |
| Template | `docs/meetings/TEMPLATE.md` | `docs/meetings/standups/TEMPLATE.md` |
| `template_version` | `meeting-analysis-1.2.0` | `standup-update-2.3.0` |
| `meeting_type` | `standup` / `review` / `workshop` | `standup-update` |
| Slug | `<series>-standup-analysis-<date>` | `<series>-standup-update-<date>` |

**The discriminator is whether there is a recording or transcript to analyze.** The
recording-analysis template presupposes one: "What the recording shows that the transcript does
not", "Moments the frames do NOT corroborate" and "Terminology and transcription corrections" have
no meaning without it. **Filling those with "not applicable" means you picked the wrong kind.** A
standup update is instead written from our own repository, which is why its discipline is a
per-claim **evidence tier** (executed / read / asserted / blocked) rather than cross-source
checking: the tier is a required field, because the difference between a green unit suite and a
live verified path is one this workflow has gotten wrong before.

From sergeiwallace/skills, Apache-2.0.

More from sergeiwallace/skills