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

docs/solutions/skill-design/ce-prefix-required-for-skills-and-agents-2026-05-01.md

@@ -0,0 +1,110 @@
+---
+title: New skills and agents must use the ce- prefix; enforce it in tests, not just prose
+date: 2026-05-01
+category: skill-design
+module: compound-engineering
+problem_type: convention
+component: plugins/compound-engineering
+severity: low
+applies_when:
+  - Adding a new skill directory under plugins/compound-engineering/skills/
+  - Adding a new agent file under plugins/compound-engineering/agents/
+  - Authoring or reviewing a PR that introduces a new component to the plugin
+tags:
+  - naming-convention
+  - ce-prefix
+  - skill-authoring
+  - test-enforcement
+  - plugin-conventions
+related:
+  - docs/solutions/skill-design/beta-skills-framework.md
+related_pr: https://github.com/EveryInc/compound-engineering-plugin/pull/747
+---
+
+## Problem
+
+`plugins/compound-engineering/AGENTS.md` already stated that "all skills and agents use the `ce-` prefix to unambiguously identify them as compound-engineering components." But the rule was prose-only, and three legacy skills (`every-style-editor`, `file-todos`, `lfg`) sit unprefixed in the same directory as their `ce-`-prefixed siblings. The combination — a soft rule plus visible exceptions — let a new skill (`riffrec-feedback-analysis`) ship in PR #747 without the prefix. The user caught it post-merge of the first commit, requiring a rename commit on the same PR.
+
+A prose convention that has visible counterexamples and no machine check is, in practice, an *advisory* convention. Any author skim-reading the directory listing sees `every-style-editor` next to `ce-brainstorm` and reasonably concludes the prefix is optional.
+
+## Root cause
+
+Two layered problems:
+
+1. **The rule was unenforced.** Nothing in CI or the test suite would fail when a non-`ce-` skill was added. The frontmatter test asserts that the skill's `name:` matches its directory and that the directory uses `[a-z0-9-]+`, but does not check for the `ce-` prefix.
+2. **The exception list was implicit.** Three legacy skills predate the rule. Without an explicit allowlist, "predates the rule" looks identical to "the rule doesn't apply" when reading the filesystem.
+
+## Solution
+
+Make the rule mechanically enforced and pin the exceptions explicitly.
+
+### 1. Test enforcement
+
+Added to `tests/frontmatter.test.ts` inside the existing `frontmatter YAML validity` block:
+
+```ts
+if (pluginRoot === "plugins/compound-engineering") {
+  const SKILL_PREFIX_ALLOWLIST = new Set([
+    "every-style-editor",
+    "file-todos",
+    "lfg",
+  ])
+  test(`${pluginRoot}/${rel} skill name uses ce- prefix`, () => {
+    const dirName = path.basename(path.dirname(rel))
+    if (SKILL_PREFIX_ALLOWLIST.has(dirName)) return
+    expect(
+      dirName.startsWith("ce-"),
+      `Skill "${dirName}" must use the ce- prefix. ` +
+        `If this is a legacy skill that predates the rule, add it to ` +
+        `SKILL_PREFIX_ALLOWLIST in tests/frontmatter.test.ts.`,
+    ).toBe(true)
+  })
+}
+```
+
+A parallel test at the agent level (no allowlist, since every existing agent already conforms):
+
+```ts
+if (
+  pluginRoot === "plugins/compound-engineering" &&
+  /^agents\/[^/]+\.agent\.md$/.test(rel)
+) {
+  test(`${pluginRoot}/${rel} agent name uses ce- prefix`, () => {
+    const fileName = path.basename(rel, ".agent.md")
+    expect(
+      fileName.startsWith("ce-"),
+      `Agent "${fileName}" must use the ce- prefix.`,
+    ).toBe(true)
+  })
+}
+```
+
+The test failure message tells the author exactly what to do — either rename the skill or, if it is genuinely legacy, edit the allowlist (which a reviewer can then push back on).
+
+### 2. Strengthened prose
+
+Updated `plugins/compound-engineering/AGENTS.md` to call the prefix mandatory, name the legacy exceptions, point at the test, and forbid extending the allowlist. The prose now says "no exceptions" and tells authors that the test will fail. Prose alone wouldn't have prevented the original mistake, but pairing it with the test gives a single internally consistent story.
+
+### 3. Persistent author memory
+
+Saved a feedback memory at `~/.claude/projects/-Users-kieranklaassen-compound-engineering-plugin/memory/feedback_ce_prefix_required.md` so future sessions on this repo load the rule automatically and apply it before the test fires.
+
+## Prevention
+
+For any plugin convention that is currently prose-only, ask:
+
+- Is there at least one visible counterexample in the codebase that an author could mistake for permission?
+- Is there a mechanical check that would fail on violation?
+
+If the answer to the first is yes and the second is no, the convention will eventually be violated. The fix is one of:
+
+- Add a test that asserts the convention with a hard-coded allowlist for legacy exceptions.
+- Migrate the legacy exceptions so the rule is universal and no allowlist is needed.
+
+The allowlist pattern is preferred when migration is risky (renaming an installed skill breaks user invocations) but the rule applies cleanly going forward.
+
+## Related
+
+- `plugins/compound-engineering/AGENTS.md` — Naming Convention section now documents the rule and the allowlist.
+- `tests/frontmatter.test.ts` — implements the enforcement.
+- PR #747 — the original mistake and the rename + enforcement that came with it.

plugins/compound-engineering/AGENTS.md

@@ -88,6 +88,8 @@ Important: Just because the developer's installed plugin may be out of date, it'
 
 **Agents** follow the same convention: `ce-adversarial-reviewer`, `ce-learnings-researcher`, etc. When referencing agents from skills, use the bare `ce-<agent-name>` form (e.g., `ce-adversarial-reviewer`) — the `ce-` prefix is sufficient for uniqueness across plugins.
 
+**The `ce-` prefix is required for every new skill and agent — no exceptions.** Three legacy skills (`every-style-editor`, `file-todos`, `lfg`) predate the rule and remain unprefixed; they are pinned in `tests/frontmatter.test.ts` as the only allowed exceptions. Do not add to that allowlist. When adding a new skill, the directory name, the SKILL.md `name:` frontmatter, and any README references must all start with `ce-`. The frontmatter test enforces this and will fail on a missing prefix.
+
 ## Known External Limitations
 
 **Proof HITL surfaces a ghost "AI collaborator" agent** (noted 2026-04-16, may change): The Proof API auto-joins any header-less `/state` read under a synthetic `ai:auto-<hash>` identity, so docs created by the `skills/proof/` HITL workflow show a phantom participant alongside `Compound Engineering`. The only way to suppress it is to set `ownerId: "agent:ai:compound-engineering"` on create — but that transfers document ownership to the agent and prevents the user from claiming it into their Proof library, so we don't use it. Treat as cosmetic noise; don't reintroduce the `ownerId` workaround. Tracked upstream: https://github.com/EveryInc/proof/issues/951.

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 |
+| `ce-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/ce-riffrec-feedback-analysis/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: ce-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/ce-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.