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]`

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.

- **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 inside
  this skill's own repo, 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.1.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.

If a consumer has renamed either workflow, search its history using both the current and historical
spellings before assuming a document is absent. The public templates use only the names above.

## Step 1: preflight the sources, and let the script decide the bookkeeping

```bash
# A zip first lands in the meeting's data/ dir under its VENDOR filenames.
uv run --script "${CLAUDE_SKILL_DIR}/scripts/meeting_resolve.py" extract \
  "<archive.zip>" "docs/meetings/standups/<author>/<date>/data"

uv run --script "${CLAUDE_SKILL_DIR}/scripts/meeting_resolve.py" plan \
  --repo-root . --sources "docs/meetings/standups/<author>/<date>/data" \
  --author "<Name>" --date <YYYY-MM-DD> --series <series> --json
```

`plan` reports the kind and why, the resolved template and where it came from, every target path,
each source's role, and any source it cannot use. Read its output before writing anything.
`--author`, `--series` and the meeting-type group also come from `MEETING_ANALYSIS_*` environment
variables or from `~/.config/meeting-analysis/config.toml`, so a regular author sets them once
rather than per run; anything passed on the command line wins.

**The refusal it can return means stop rather than work around.** `CONFLICT: ... already exists`
(exit 2): a committed doc is **never renamed or duplicated** -- it is cited from design docs,
audits, other analyses and pull-request descriptions, several of them by line number. Refine the
existing doc in place, or fix the date or author you passed. Never invent a free filename.

## Step 2: the directory shape is a convention, not a preference

```text
docs/meetings/<meeting-type>/<author>/<YYYY-MM-DD>/
  <slug>-<YYYY-MM-DD>.md      the deliverable, at the date directory's root
  data/                       sources exactly as received from the vendor
  derived/                    everything generated from them
  frames/                     extracted video frames (git-ignored)
```

- **The `<author>` segment is kebab-case and is not optional.** It exists so two people can write
  for the same meeting on the same day without contending for one filename.
- **The date appears twice on purpose.** The directory needs it so a series sorts and so the doc
  sits beside its own `data/` and `derived/`. The filename needs it because the filename is what
  survives leaving the directory: in an editor tab, a link, a PDF export or an attachment, the
  parent directory is no longer visible, and a bare `standup.md` is ambiguous across a daily series.
- **Vendor filenames are never renamed**, so they stay traceable to the artifact received.

### Source-quoting hazard: these filenames WILL break an unquoted command

Example vendor filenames:

```text
[Team Sync] Weekly.vtt
[Team Sync] Weekly 2026-07-30.pdf
```

They contain **spaces and square brackets**, and brackets are glob metacharacters, so `[Team Sync]`
is read by the shell as a character class. Consequences:

- **Always double-quote every path**, including in `ffmpeg`, `pdftotext` and the analysis scripts:
  `ffmpeg -i "data/[Team Sync] Weekly.mp4" ...`.

From sergeiwallace/skills, Apache-2.0.

More from sergeiwallace/skills