feat(riffrec-feedback-analysis): add Riffrec feedback skill with three-path routing

plugins/compound-engineering/README.md

@@ -41,6 +41,7 @@ For `/ce-optimize`, see [`skills/ce-optimize/README.md`](./skills/ce-optimize/RE
 |-------|-------------|
 | `/ce-sessions` | Ask questions about session history across Claude Code, Codex, and Cursor |
 | `/ce-slack-research` | Search Slack for interpreted organizational context -- decisions, constraints, and discussion arcs |
+| `riffrec-feedback-analysis` | Convert [Riffrec](https://github.com/kieranklaassen/riffrec) recordings, videos, audio, or notes into structured feedback. Routes between setup, quick bug report, and extensive analysis that hands off to `ce-brainstorm` |
 
 ### Git Workflow
 

plugins/compound-engineering/skills/riffrec-feedback-analysis/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: riffrec-feedback-analysis
+description: Riffrec product-feedback workflow. ALWAYS load when the user posts a `riffrec-*.zip`, a bundle with `session.json` + `events.json` + `recording.webm` + `voice.webm`, a video/audio recording for product feedback, or asks how to capture and share Riffrec sessions. Routes between setup, quick bug report, and extensive analysis.
+---
+
+# Riffrec Feedback Analysis
+
+Turn raw product feedback into structured evidence for downstream agents. This skill is the consumption side of [Riffrec](https://github.com/kieranklaassen/riffrec), a capture tool that records synchronized screen + voice + event sessions and emits a `riffrec-*.zip` bundle.
+
+## Choose the path
+
+Route to the matching reference based on the input. Read only that reference; do not load the others.
+
+- **Setup** — user has no recording yet and asks how to install Riffrec, capture a session, or share feedback. Read `references/install-riffrec.md`.
+- **Quick bug report** — input is a short recording (under ~60 seconds), the user describes a single specific issue, or asks for "quick", "small", or "just transcribe". Read `references/quick-bug-report.md`. Emit one concise bug report; skip the full artifact set and brainstorm handoff.
+- **Extensive analysis** — input is a longer recording, contains multiple issues / requirements / workflow walkthroughs, or the user wants requirements or brainstorm material. Read `references/extensive-analysis.md`. Always continue into the `ce-brainstorm` skill.
+
+When the input is ambiguous (e.g., a zip arrived without context), inspect the recording length and event count before choosing. If still unclear, ask the user which path applies before running anything heavy.
+
+## Common rules
+
+- Keep raw recordings, audio chunks, zip contents, session dumps, and extracted screenshots local-only by default. Do not commit `raw/` or `frames/` directories unless the user explicitly asks and privacy is acceptable.
+- Text/metadata artifacts (requirements docs, analysis summaries, problem analyses, source manifests) may be committed when they are needed for traceability and contain no sensitive data.
+- Use repo-relative screenshot paths in any committed doc so later agents can open the evidence without absolute local paths.
+
+## Analyzer entrypoint
+
+All non-setup paths share the same analyzer:
+
+```bash
+python scripts/analyze_riffrec_zip.py /path/to/input
+```
+
+Accepted inputs: a Riffrec `.zip`, an `.mp4` / `.mov` / `.webm` video, an `.m4a` / `.mp3` / `.wav` audio file, or a meeting-notes `.md`. Use `--output-dir <dir>` to control where artifacts land. In repos with `docs/brainstorms/`, the default is `docs/brainstorms/riffrec-feedback/`. The quick path overrides the output dir to a temp location so nothing pollutes the repo.
+
+The Compound Engineering output format used by the extensive path is documented in `references/compound-engineering-feedback-format.md`.

plugins/compound-engineering/skills/riffrec-feedback-analysis/references/compound-engineering-feedback-format.md

@@ -0,0 +1,116 @@
+# Compound Engineering Feedback Format
+
+Use this shape when converting Riffrec evidence into a durable brainstorm or planning input.
+
+## Finding
+
+```markdown
+### F1. <Short problem title>
+
+- **Severity:** P0/P1/P2/P3
+- **Observed:** <What happened, grounded in transcript/events/screenshots>
+- **Expected:** <What the user appeared to expect or what the product should do>
+- **Evidence:** <Moment IDs and screenshot links>
+- **Confidence:** High/Medium/Low, with reason
+- **Requirement candidates:** R1, R2
+```
+
+## Requirements Kickoff
+
+```markdown
+---
+date: YYYY-MM-DD
+topic: <topic>
+---
+
+# <Topic Title>
+
+## Problem Frame
+
+<Who is affected, what is changing, and why it matters.>
+
+---
+
+## Actors
+
+- A1. User: <Role in the recorded workflow>
+- A2. Product surface: <System under test>
+- A3. Agent/assistant, if relevant: <Role in the workflow>
+
+---
+
+## Key Flows
+
+- F1. Recorded feedback triage
+  - **Trigger:** A Riffrec zip is available for review.
+  - **Actors:** A1, A2
+  - **Steps:** <3-7 product steps seen in the recording>
+  - **Outcome:** <What should be true after the fix>
+  - **Covered by:** R1, R2
+
+---
+
+## Requirements
+
+**Observed product behavior**
+- R1. <Concrete product behavior requirement>
+
+**Feedback evidence and reviewability**
+- R2. <Requirement about making the issue observable or preventing recurrence>
+
+---
+
+## Acceptance Examples
+
+- AE1. **Covers R1.** Given <state>, when <action>, <outcome>.
+
+---
+
+## Success Criteria
+
+- <Human outcome>
+- <Downstream agent handoff quality>
+
+---
+
+## Scope Boundaries
+
+- <Deliberate non-goal>
+
+---
+
+## Key Decisions
+
+- <Decision>: <Rationale>
+
+---
+
+## Dependencies / Assumptions
+
+- <Material dependency or assumption>
+
+---
+
+## Outstanding Questions
+
+### Resolve Before Planning
+
+- <Only product questions that block planning>
+
+### Deferred to Planning
+
+- [Technical] <Questions better answered during codebase exploration>
+
+---
+
+## Next Steps
+
+-> /ce-brainstorm to confirm, correct, and regroup the captured requirements before any planning.
+```
+
+## Evidence Rules
+
+- Prefer moment IDs and screenshot links over prose-only claims.
+- Mark visual interpretation as an inference when the screenshot does not prove intent.
+- Requirements should describe product behavior, not implementation details.
+- Do not include absolute local paths in CE docs; use repo-relative paths when possible.

plugins/compound-engineering/skills/riffrec-feedback-analysis/references/extensive-analysis.md

@@ -0,0 +1,119 @@
+# Extensive analysis path
+
+Use this path when the input is a longer recording (over ~60 seconds), contains multiple issues, requirements, or workflow walkthroughs, or the user explicitly wants requirements material. The goal is a full Compound Engineering-compatible artifact set that feeds `ce-brainstorm`.
+
+## Workflow
+
+1. Run the analyzer:
+
+   ```bash
+   python scripts/analyze_riffrec_zip.py /path/to/input
+   ```
+
+   Use `--output-dir <dir>` when the artifact should live somewhere specific. In a repo with `docs/brainstorms/`, the default output goes under `docs/brainstorms/riffrec-feedback/`.
+
+2. Read the generated `analysis.md`, `problem-analysis.md`, `review-prompt.md`, and `requirements-kickoff.md`.
+
+3. Read `source-materials.md` before brainstorm. It is the source-of-truth manifest for the original raw feedback location, transcript, local-only frames, chunks, analysis artifacts, and screenshot paths. Use it to keep brainstorm and planning traceable to the original feedback evidence.
+
+4. Inspect the extracted screenshots for high-signal moments using the platform's image-view tool. Prioritize screenshots selected because of click events near verbal complaints, failed network requests, console errors, or repeated interaction.
+
+5. Fill or refine `problem-analysis.md` using the frame review structure from `review-prompt.md`. The final problem analysis must have exactly these top-level categories:
+
+   - **Visual/UI Problems**
+   - **Functional Problems**
+   - **Requirements**
+   - **Usability/UX Problems**
+
+   Each numbered item should describe the problem, location, UI element, frame reference, and relevant transcript context when available. Focus on WHAT is wrong, not HOW to fix it.
+
+6. Convert evidence into requirements. Keep these categories distinct:
+
+   - **Observed facts:** transcript quotes, click targets, request statuses, screenshot contents.
+   - **Inferences:** likely user intent, likely broken control, suspected missing state.
+   - **Requirements:** product behavior needed to resolve the problem.
+
+7. When the current workspace contains the product source code, run a source-mapping pass before or during brainstorm. Use the transcript language, visible UI labels, screenshot paths, route names, and generated requirements to search the codebase for likely components, controllers, services, models, tests, and state stores. For larger sessions, split this mapping by product area and use sub-agents when available so independent areas can be inspected in parallel.
+
+8. Add source mapping to the brainstorm material as suspected implementation surfaces, not as proven root cause unless the code clearly proves it. Include confidence levels and short evidence notes explaining why each file or component is relevant.
+
+9. Always continue into brainstorm. Once `analysis.md`, `problem-analysis.md`, `source-materials.md`, and `requirements-kickoff.md` exist, say "Analysis complete. Ready to brainstorm the findings." Then immediately load the `ce-brainstorm` skill with the generated `requirements-kickoff.md`, unless the user explicitly asked only to extract or analyze artifacts.
+
+10. In brainstorm, first ask the user to confirm the captured requirements: "Did this capture the requirements correctly, and what is missing, wrong, or grouped badly?" Do not move to planning until brainstorm has confirmed or corrected the requirements.
+
+## Automatic handoff
+
+Do not end the workflow after extraction in normal use. The intended sequence is:
+
+1. Run the analyzer.
+2. Read `source-materials.md` so brainstorm has direct links to raw feedback, transcript, frames, and analysis artifacts.
+3. Inspect or refine `problem-analysis.md` when the evidence needs human-visible interpretation.
+4. Load the `ce-brainstorm` skill with `requirements-kickoff.md`.
+5. Ask the user to confirm, correct, or regroup the captured requirements.
+6. Let `ce-brainstorm` produce the durable requirements doc under `docs/brainstorms/`.
+
+Only stop after step 1 or 2 when the user asks specifically for raw artifacts, transcript, screenshots, or analysis without brainstorming.
+
+## Capture scale
+
+Prefer over-capture to under-capture. The purpose of this path is to preserve product feedback as structured data for later AI work, not to decide what is worth implementing during extraction.
+
+When analyzing a feedback source:
+
+- Capture every distinct problem, bug, request, expectation, confusion point, and "note to self" that appears in the transcript or frames.
+- Include concrete examples from the source material for each issue when possible: timestamp, transcript phrase, screenshot path, clicked UI element, email/thread ID, or observed state.
+- Include concrete source-code mapping when possible: likely component/service/controller/model/test files, route or API endpoint names, relevant state variables, and confidence level. This mapping should make it obvious where a later implementation agent should start looking.
+- If only video is available, infer likely screens and components from visible UI labels, layout, URLs, route names, copied text, screenshots, and transcript references. Mark uncertain mappings explicitly instead of omitting them.
+- If only audio or notes are available, map from product terminology and workflow descriptions to likely code areas when the repo is present, and label the mapping as transcript-derived.
+- Do not drop lower-priority items during analysis. Mark them as lower priority or secondary if needed, but keep them represented.
+- Separate capture from prioritization. Brainstorm may regroup, split, defer, or reject items later, but the first requirements pass should preserve the full signal.
+- If a feedback session contains many issues, create a comprehensive capture document and state that planning should split it into smaller plans.
+- Treat source mapping as supporting material, not a filter. If a problem cannot yet be mapped to code, keep the problem and mark the source mapping as unknown.
+
+## Source mapping grounding
+
+When mapping feedback to source code, classify each mapping as one of:
+
+- **Likely buggy surface:** the code path exists and directly handles the observed behavior.
+- **Missing or incomplete surface:** the feedback names a behavior, but the repo has no clear UI, route, controller action, or component implementing it yet.
+- **Indirect surface:** the code is adjacent to the behavior, but the exact interaction may happen through rendered email content, third-party UI, generated HTML, or another layer.
+- **Unknown:** no grounded source mapping found yet.
+
+Every source mapping should include:
+
+- Requirement/example ids, such as `R14`, `AE4`, or `EX17`.
+- File paths with line numbers when practical.
+- A short evidence note from code, not just a file guess.
+- Confidence: `High`, `Medium`, `Low`, or `Unknown`.
+
+Prefer saying "I did not find a current inbox implementation for this surface" over forcing a speculative mapping. Missing surfaces are useful product findings and should stay in the brainstorm.
+
+## Output shape
+
+The analyzer writes:
+
+- `analysis.md`: session summary, transcript, selected moments, screenshot links, candidate findings, and review checklist.
+- `problem-analysis.md`: a categorized problem statement scaffold for visual, functional, requirement, and UX findings.
+- `review-prompt.md`: a filled prompt containing screenshot paths and transcript for a deeper visual analysis pass.
+- `source-materials.md`: a manifest linking the original source location, local-only raw files, transcript locations, chunks, local-only frames, and generated artifacts.
+- `requirements-kickoff.md`: a CE-friendly requirements starter with Problem Frame, Actors, Key Flows, R-IDs, Acceptance Examples, Success Criteria, Scope Boundaries, Questions, and Next Steps.
+- `analysis.json`: structured session, event, transcript, moment, and artifact metadata.
+- `frames/`: extracted PNG screenshots for selected moments. Local-only by default.
+- `raw/`: extracted zip contents and copied source media. Local-only by default.
+
+Long media is transcribed in chunks when a single transcription request is too large. Chunk transcripts include timestamp prefixes so the review pass can still connect discussion points to approximate video regions.
+
+For audio-only or notes-only sources, the visual sections intentionally say that no frames are available. In those cases, extract functional problems, requirements, and UX friction from transcript or notes only.
+
+## Review heuristics
+
+Select moments when they contain:
+
+- Verbal complaint cues: "weird", "doesn't work", "can't", "broken", "bug", "problem", "confusing", "should".
+- Clicks on controls shortly before or after a complaint.
+- Repeated clicks on the same control.
+- Failed requests outside known development noise.
+- Console errors, uncaught exceptions, or failed form submissions.
+- Visible toasts, validation errors, disabled controls, empty states, or surprising navigation.
+
+The script's findings are deliberately conservative. Look at screenshots and transcript together before turning a candidate finding into a requirement.

plugins/compound-engineering/skills/riffrec-feedback-analysis/references/install-riffrec.md

@@ -0,0 +1,27 @@
+# Setup: Add Riffrec to a project
+
+Use this path when the user has no recording yet and wants to start capturing product feedback with [Riffrec](https://github.com/kieranklaassen/riffrec).
+
+Riffrec is a browser-based capture tool that records the screen, microphone audio, console output, network requests, and DOM events into a single `riffrec-*.zip` bundle. The bundle is what this skill consumes downstream.
+
+## What to tell the user
+
+1. Riffrec lives at <https://github.com/kieranklaassen/riffrec>. Refer them to the README for the current install command — it is the source of truth and may change.
+2. The general shape of integration:
+   - Add the Riffrec capture script or package to the project's web app.
+   - Wire a "Record feedback" affordance somewhere accessible during real use (a bug report button, a dev-only floating recorder, or a keyboard shortcut).
+   - Confirm a sample session ends with a downloadable `riffrec-*.zip`.
+3. Once a zip exists, the user runs this skill again with the zip path. The skill will pick the **quick bug report** or **extensive analysis** path automatically based on length and content.
+
+## Recommended capture habits
+
+Surface these to the user during setup so the recordings they share later are easy to analyze:
+
+- Speak the issue out loud while reproducing it. The transcript is the single highest-signal artifact.
+- Click the affected UI even when it does nothing — failed clicks are the strongest signal in event extraction.
+- Keep recordings focused. Many short clips beat one long one when issues are unrelated.
+- Note when a step is intentional vs. accidental ("oops, that wasn't what I meant"). The analyzer cannot infer intent.
+
+## After install
+
+When the user returns with their first zip, route to `references/quick-bug-report.md` or `references/extensive-analysis.md` per the SKILL.md routing rules. Do not run the analyzer in the setup path — there is nothing to analyze yet.

plugins/compound-engineering/skills/riffrec-feedback-analysis/references/quick-bug-report.md

@@ -0,0 +1,44 @@
+# Quick bug report path
+
+Use this path when the input is a short recording (under ~60 seconds), the user describes a single specific issue, or the user explicitly asks for "quick", "small", "simple", or "just transcribe". The goal is one concise bug report, not a multi-artifact requirements package.
+
+## Workflow
+
+1. Run the analyzer to a temp directory so nothing pollutes the repo:
+
+   ```bash
+   python scripts/analyze_riffrec_zip.py /path/to/input --output-dir "$(mktemp -d -t riffrec-quick-XXXXXX)"
+   ```
+
+   Capture the printed output directory; later steps read from it.
+
+2. Read only `analysis.md` from the temp output. Skip `problem-analysis.md`, `review-prompt.md`, `requirements-kickoff.md`, and `source-materials.md` — they are designed for the extensive path.
+
+3. Pick at most one or two screenshots from `frames/` that directly show the reported issue. Prefer frames near a verbal complaint, a failed click, a console error, or a failed network request.
+
+4. Emit a single concise bug report. Default to printing it inline in the chat so the user can confirm before anything is written to disk. Only write a file if the user asks for one — and even then, prefer a single `bug-report.md` next to the source recording or in a path the user names. Do not auto-create `docs/brainstorms/...` for this path.
+
+## Bug report shape
+
+Keep it focused and short. Include only what the recording supports:
+
+- **Title** — one short sentence naming the broken behavior.
+- **Steps to reproduce** — bullet list reconstructed from clicks and transcript.
+- **Expected vs. actual** — what the user said should happen vs. what happened.
+- **Evidence** — transcript quote(s) with timestamps, plus 0–2 screenshot references.
+- **Suggested next step** — single sentence: file an issue, open `ce-debug`, or escalate to extensive analysis if more issues surfaced.
+
+## Source mapping (optional, only if obvious)
+
+If the workspace is the product source code AND the broken surface is named clearly in the transcript or visible UI, add one short "Likely surface" line with file path and confidence (`High` / `Medium` / `Low`). Skip this section entirely when the mapping is speculative — speculative mappings belong in the extensive path, not a quick bug report.
+
+## What to skip
+
+- No `problem-analysis.md`, no `requirements-kickoff.md`, no Visual / Functional / Requirement / UX category split.
+- No automatic handoff to `ce-brainstorm`. The quick path ends with the bug report.
+- No commit of `raw/` or `frames/` — they live only in the temp dir and are discarded by the OS.
+- No source-mapping pass across the codebase.
+
+## Escalation
+
+If, while reading the transcript, the recording turns out to contain multiple distinct issues, requirements, or a workflow walkthrough, stop and tell the user: "This recording has more than one issue — switching to the extensive path." Then load `references/extensive-analysis.md` and re-run the analyzer with a non-temp output directory.