dsh-compound-engineering 0.0.0-stage → 0.1.1

package/skills/ce-retune/references/noise-floor.md

@@ -0,0 +1,131 @@
+# Noise Floor and the Registered Bar
+
+Phase 2 protocol. Measure what changing nothing produces, then write down the bar before a change exists.
+
+## What the A/A run buys
+
+Two builds of the corpus at the same commit, run under one harness on one task, produce a distribution rather than a result. That distribution is the floor. Any later claim smaller than it is unsupported no matter how confidently it was reported. In the engagement this was the single most valuable measurement of the session. 12 runs across two identical builds gave workflow adherence 7 of 12 and output tokens from 21,872 to 155,682, a 7.12x spread on identical code. It retired every small-sample claim in flight, including an outside analyst's "2 of 8 improved to 5 of 8", which sits entirely inside the range that doing nothing produces.
+
+The A/A also tests the instrument. Identical builds that differ significantly are not evidence about the corpus. They are a harness, provenance, or scoring bug. Chase that before continuing.
+
+## Setup
+
+Required capability: a harness that can point a run at a specific source checkout of the corpus (Phase 0's build selector) and writes a per-run artifact you can parse. Both arms must go through the *same* runner, task, and model configuration.
+
+1. Materialize two checkouts of the corpus at the same commit. Record the commit for each arm.
+2. Hash both trees and assert equality before the first run (`find <dir> -type f | sort` then a checksum over the file list and contents). An accidental difference between arms gets read as noise and poisons the floor silently.
+3. Label the arms concretely by path, not by intent (`build-a`, `build-b`). Nothing downstream should be able to guess an arm from a filename that also encodes a hypothesis.
+4. **Prove the selector is honored, in one run, before planning any.** Point a single run at `build-a`, then open the finished artifact and confirm it names `build-a` in the durable field below. Two failures both look like a normal run: a harness that silently falls back to its installed copy of the corpus, and one that records the arm nowhere. Either makes all 12 runs unlabeled and unusable, and both are invisible until you try to score. If you want a positive control, put a harmless unique string in a **third**, throwaway checkout and confirm it reaches that run's trace. Never put it in either arm, which step 2 requires to stay byte-identical, and re-assert the hashes before the counted runs begin.
+5. Plan 12 or more runs total, split evenly. Below about 10 the floor estimate is itself noise; the spread ratio in particular needs the tails.
+
+## Interleave, never batch
+
+Alternate arms run by run (A, B, A, B) and alternate which arm goes first across pairs (A/B, then B/A). Never run all of arm A and then all of arm B.
+
+Batching confounds the comparison with API load, rate-limit backoff, transient service degradation, and time of day. Those effects are large and they are indistinguishable after the fact from a real difference between builds. There is no post-hoc correction, because the confound and the effect are the same column. Interleaving costs nothing. It is the same number of runs, reordered, and it makes each pair a matched observation you can analyze paired if you want the extra power.
+
+If a run dies for an infrastructure reason, re-run *that arm's* slot rather than dropping the pair, and mark the row so the archive's broken-run taxonomy (`references/baseline-mining.md`) still classifies it correctly.
+
+## Provenance per row
+
+Every scored row must carry which build produced it, **read from the artifact the harness wrote**, never inferred from run order, timestamp, or the order you launched things.
+
+The engagement's first scorer read the field the harness exposes for the source-checkout override *while a run is in flight*. On completion the harness folds that value into the run's metadata and clears the live field, so every finished row had an empty build column and the arms were unverifiable from the scored data. The runs were fine. The measurement was worthless until re-scored.
+
+The rule that generalizes: **read the durable post-completion field first, fall back to the transient in-flight one.**
+
+```
+build = run.metadata.<override-field> or run.<live-override-field> or None
+```
+
+Then check it before scoring. Assert every row has a non-empty build value before computing anything, and fail loud with the offending run ids rather than scoring a partially-labeled table. A row whose arm you cannot establish is not a data point.
+
+Minimum row schema:
+
+| field | why it is here |
+|---|---|
+| `run_id` | join key back to the raw trace |
+| `build` | arm, from the durable field |
+| `commit` | proves the arms were the same source |
+| `pair_index`, `position_in_pair` | recovers the interleave for paired analysis |
+| `adherence` | followed the workflow (separate from outcome) |
+| `outcome` | did the job |
+| `broken` | empty transcript / error exit / infra death |
+| `output_tokens` | the variance channel, and usually the noisier one |
+| `terminal_marker` | how the run ended, verbatim |
+
+Adherence and outcome stay separate columns here for the same reason they do in Phase 1.
+
+## Statistics that survive small n
+
+Required capability: a scripting environment with an exact-test library, or the closed forms. Wilson and the risk difference are arithmetic on the counts; Fisher's exact is a sum of hypergeometric terms. If the required analysis is unavailable, do not substitute a normal approximation. The streak below can provide descriptive confirmation; its statistical interpretation requires the assumptions stated there.
+
+At n = 6 per arm the normal approximation to a proportion is wrong in ways that matter. It produces intervals that exclude values the data plainly permit, including 0 and 1. Use:
+
+- **Wilson score intervals** for each arm's rate. Not Wald, not "plus or minus 1.96 times the standard error".
+- **Risk difference with a confidence interval** as the headline comparison. Report the interval, not the point estimate. An interval that spans zero *is* the finding.
+- **Fisher's exact test** for the 2x2, not chi-square, at these counts.
+- **A spread ratio** for continuous channels: max over min of output tokens, per arm and pooled. In this corpus the token spread moved earlier and further than the completion rate, and it is what makes a corpus unmeasurable.
+
+Report both channels. A build whose rate is unchanged but whose spread halved is a real result. The reverse, a rate that improved while the spread widened, is a warning that you got lucky.
+
+### Make "inconclusive" a printed outcome
+
+The summarizer must, whenever a result is not significant, print the runs-per-arm that *would* have been needed for 80% power at the observed effect. Otherwise "no significant difference" reads as an empty slot in the report and someone fills it with narrative.
+
+Two-proportion sample size at 80% power, alpha 0.05, two-sided:
+
+```
+n_per_arm = 7.849 * (p1*(1-p1) + p2*(1-p2)) / (p2 - p1)^2
+```
+
+Against the engagement's 58% baseline, detecting +30 points gives about 31 per arm from that formula, and the power tool used reported about 39 once it applied a continuity correction. **Take the larger.** Corrections differ by method and land roughly 20-40% above the plain figure at these rates, so with no tool to hand, plan on the plain figure inflated by a third rather than treating 31 as the budget. Print the number next to the non-result, in the same line, so the cost of the claim is visible where the claim is.
+
+## One-armed confirmation
+
+A pre-registered streak can serve as an operational confirmation bar on one frozen build under fixed measurement conditions. Under a null with a **known, fixed success probability `p` and independent runs**, one pre-specified attempt at N consecutive clean runs has all-success probability `p^N`. That calculation alone is not a significance level for an adaptive search.
+
+Establish the baseline before the change, from runs other than the ones being tested. Estimating `p` from the streak's own runs makes the calculation circular and meaningless. A baseline measured independently from A/A and archive runs is still an estimate. Account for its sample size and uncertainty in any statistical claim. When baseline uncertainty, changed conditions, or dependence between runs is unaccounted for, report the observed confirmation descriptively rather than as an exact test.
+
+For one pre-specified attempt under the fixed `p = 0.58` null:
+
+| consecutive clean runs | probability of all successes | odds |
+|---|---|---|
+| 3 | 0.195 | 1 in 5 |
+| 5 | 0.066 | 1 in 15 |
+| 8 | 0.0128 | 1 in 78 |
+
+**Keep the search history when interpreting the result.** Across 20 independent attempts under that same null, the probability of at least one eight-run success is `1 - (1 - 0.58^8)^20`, about 0.2272, not 0.0128. This is an illustrative calculation, not a measured CE error rate; adaptive candidates need not be independent. A search-wide significance claim must account for candidate selection and the stopping rule. Changing a candidate resets its streak, not the search history.
+
+**Stop an attempt at the first behavioral failure.** A failed streak is a finding to diagnose before changing the candidate, not permission to repeat it until it passes. Keep every attempt and classify infrastructure retries under the registered broken-run rule. Never pool successes across builds. A cleared operational bar without a supported statistical analysis remains descriptive confirmation. A streak probability is not an effect-size estimate or a percentage improvement.
+
+**Separate diagnostic runs from final confirmation.** One or two diagnostic runs after a cut can locate the next failure; they do not count toward a streak. Begin final confirmation only after a clean diagnostic run, with the candidate and confirmation rule fixed. Use fresh runs whose results were not used to select it. If those results guide another edit or another confirmation attempt, they enter the selection history and cannot be ignored in a later significance claim.
+
+## Registering the bar
+
+The registration is a written artifact at a path you can point a skeptic at, not an intention (`references/workflow-shapes.md` for where the engagement's artifacts live). It must name:
+
+- the metric, in the exact form the summarizer computes it;
+- the effect size worth detecting, and why that size and not a smaller one;
+- the design (two-armed with n per arm, or streak with N), and whether the result is descriptive confirmation or a statistical claim;
+- for a statistical claim, the baseline evidence and uncertainty, independence assumptions, and error control covering candidate selection and repeated attempts;
+- the stopping rule, including what counts as a broken run that does not consume the streak;
+- the phases the probe task traverses, from the validation below.
+
+**When the affordable n cannot detect the effect you care about, say so and change the design, not the interpretation.** Consider a cheaper metric that moves more per run (token spread usually moves before completion rate) or a bigger effect. A streak can instead support the limited confirmation described above; it is not a substitute for the two-armed design's power or effect-size estimate. Running an underpowered two-armed test and reporting its point estimate is the failure mode this whole phase exists to prevent, and it is exactly what the outside analyst's 2-of-8 versus 5-of-8 was.
+
+## Sizing the probe task
+
+A full realistic task costs too much to repeat 12 to 40 times. Build a probe whose **work** is small but whose **path** is complete. It must cross every phase boundary of the corpus, produce each phase's artifact, and require each handoff, with the substance of each step shrunk to near-nothing.
+
+Then validate that it does, before spending n on it:
+
+1. Run it once with tracing on.
+2. For each phase, check the trace for its boundary marker: the dispatch, the artifact write, the check that decides the phase. Score against the phase-marker map Phase 1 already built (`references/baseline-mining.md`) rather than re-deriving markers here. A probe scored against a second, differently-derived map is not comparable to the archive baseline.
+3. List the phases the probe never entered.
+
+**A probe that structurally cannot enter a phase can never fail in it.** Its green result certifies only the phases it traversed, and the unentered ones stay unmeasured while the streak makes the corpus look verified. Two of the engagement's landed cut passes came out of auditing exactly those unreachable phases; none of them could have come from the runs. That is why Phase 5 requires reading the phases the instrument cannot reach, and why the unentered list belongs in the registration rather than in a footnote afterward.
+
+## Reading a tie honestly
+
+If both builds succeed on a capable model, that shows **no regression**, not improvement. A ceiling result on the strong axis is compatible with the change having done nothing, and it says nothing at all about a more literal model or a different harness. Report it as "no regression detected, effect indistinguishable from zero at n = X" and keep the improvement claim unmade.

package/skills/ce-retune/references/workflow-shapes.md

@@ -0,0 +1,73 @@
+# Workflow Shapes
+
+Which orchestration shape fits each phase, and what breaks when you pick the wrong one.
+
+Two primitives are assumed, both platform-neutral:
+
+- **A dispatch primitive** that launches an independent agent with its own context window and returns a result to the orchestrator (in one host it is a subagent-spawning tool; in another a job runner). Only two properties matter: fresh context per agent, and a result the orchestrator can read.
+- **A concurrency cap** the host enforces on how many agents run at once (often around 10). Dispatches above the cap queue rather than fail, so a 31-unit fan-out is three waves, not one. Plan the wave count; do not assume flat cost.
+
+Classify a rejected dispatch by whether an agent launched. Correct a pre-launch argument rejection once, and leave capacity-limited work queued. Any other launch failure follows the phase's own failure direction. In the corpus audit, the proposal and defense contexts must be independent for the audit to mean anything, so a launch failure there is a blocker: stop the audit rather than running the missing side inline.
+
+## The shapes
+
+| Phase | Shape | Why | Failure when mismatched |
+|---|---|---|---|
+| Archive mining | Serial, local, zero model calls | Classification is a deterministic function of fields present in each log; you will re-run it as the taxonomy changes | Agent-per-log gives a different taxonomy each pass, so the exclusion set cannot be re-derived or audited |
+| A/A and A/B runs | Serial within an arm, interleaved across arms, nothing else running | Contention is a confound; interleaving spreads service drift evenly across arms | Concurrent runs inflate duration and can manufacture a timeout that reads as a halt |
+| Corpus audit | Fan out by unit, pipelined into per-unit adversarial defense | Units are independent and each needs a full directory read; defense for a unit needs only that unit's findings | A barrier between audit and defense costs the slowest unit and buys nothing |
+| Cross-cutting rewrite | One agent authors the contract, then fan out application | The replacement text must be identical everywhere to stay greppable and revertable | No contract: N phrasings of one rewrite. No fan-out: context exhaustion, silent skips |
+| Cut passes | Fan out by disjoint file sets, one agent edits every copy of a shared byte-identical asset, barrier before verification | Concurrent edits to one file lose each other; verification must see one tree | Overlapping file sets produce a tree nobody wrote and nobody can bisect |
+| Verification | Fan out by independent check, never by file | The checks need different tools and different judgment, and one must be a read no grep can do | Splitting by file runs the same suite N times and skips the coherence read entirely |
+| Residual critic | One agent, last, scoped to what did not land | A fresh reader with no stake in the passes is the only one who will call a pass partial | A critic asked to verify the work reports green, which is worth nothing |
+
+## Per phase
+
+**Archive mining is serial and local.** The temptation is to dispatch one agent per log file because there are hundreds of them. Resist it. A script is faster, deterministic, and re-runnable, and re-runnability is the point. The correction that decides whether a baseline is usable at all, excluding empty transcripts and error exits, changes the taxonomy after you have already classified everything, so you will run the classifier more than once. A script re-runs for free and produces the same answer. An agent fleet re-costs the whole archive and produces a slightly different answer. See `references/baseline-mining.md` for the fields and the taxonomy.
+
+**A/A and A/B runs are serial per arm and interleaved across arms.** Never run measurement concurrently with anything else you intend to measure. Metrics differ in how they survive contention, and the distinction decides whether a contended run is salvageable:
+
+- **Robust to contention:** did it complete, did it follow the workflow, which phase it reached, token counts. A run either entered a phase or it did not, regardless of what else was executing.
+- **Destroyed by contention:** wall-clock duration and everything derived from it, including anything that depends on a timeout. A contended run that times out mid-phase is indistinguishable from a corpus-caused halt, which is the exact failure this skill is trying to attribute.
+
+So a contended run can still support a completion or adherence claim. It cannot support a latency claim, and it cannot be counted as a halt. Protocol and sample-size math are in `references/noise-floor.md`.
+
+**The corpus audit fans out by unit and pipelines into defense.** One agent per skill directory, each reading that directory in full. That full read is what makes per-unit parallelism worth its cost, and it is why one agent cannot do all the units. Pipeline the adversarial defense stage per unit. A unit's defender needs that unit's findings plus the project's own documented learnings, tests, and history, never the global finding list, so a defense can start the moment its audit returns. A global barrier here only makes every defender wait on the slowest auditor.
+
+Budget the defense stage as first-class work, not a review formality. It is the stage that removes cuts, and the removals are the phase's product as much as the proposals are. If you compress the phase for time, compress the number of units in flight, not the defense. Dispatch shape and finding schema live in `references/corpus-audit.md`.
+
+**A cross-cutting rewrite writes the contract first, then fans out.** When one pattern must change in many units, have a single agent author the canonical contract: the exact text to remove, the exact text to replace it with, and the boundary cases where it does not apply. Then fan out application against that contract.
+
+- **Skip the contract** and N agents produce N phrasings of one rewrite. The change stops being greppable, so you cannot confirm coverage. It stops being revertable as a unit. And when the next measurement fails you cannot tell whether the cause is the change or one agent's variant of it.
+- **Skip the fan-out** and one agent reads 30 directories until its usable context is gone. The failure is not an error. It is degradation: the late units get shallow work or get silently skipped, and the output looks complete.
+
+**Cut passes use disjoint file sets, one agent for every copy of a shared asset, then a barrier.** One problem per pass, one agent per pass, and file sets that do not intersect. Byte-identical duplicated assets are the trap. If two passes each touch their own copy of the same file, you get divergence that a parity test catches at best and ships at worst. Assign every copy of a duplicated asset to exactly one agent, even when that agent's problem is not the one the copy most obviously belongs to. Close the fan-out with a barrier before verification. Verification reads a tree, and a tree with a pass still landing in it is not the tree you will ship. Loop mechanics are in `references/cut-passes.md`.
+
+**Verification fans out by independent check.** The axes are different tools and different judgment, so they parallelize cleanly while splitting by file does not:
+
+| Check | What it can see | What it cannot |
+|---|---|---|
+| Mechanical suite | Pinned strings, schemas, parity between duplicated assets | Whether the surviving prose still makes sense |
+| Packaging and manifest checks | Install-time validity, catalog and inventory drift | Runtime behavior |
+| Residual-pattern sweep | Remaining instances of the class you just removed, including in files no pass edited | Instances phrased differently from the pattern |
+| Coherence read | Dangling cross-references, orphaned "as described above", a phase whose predecessor was deleted | Anything requiring the full suite |
+
+Run the mechanical suite once, as one check, not once per agent. Keep the coherence read in the fan-out and give it a human-style instruction: read the changed files end to end and name anything that no longer follows. It is the only check that finds a reference left pointing at removed text, and no grep will do it.
+
+**The residual critic is one agent, run last.** Give it the pass list, the registered bar, and the measured results, and ask for one line per intended change: landed, partial, or not landed, plus what a next pass would have to do. Instruct it explicitly that declaring success is not its job and that returning an empty list requires naming what it checked to reach that conclusion. Without that framing it will summarize the work approvingly, which tells you nothing you did not already believe.
+
+## Cross-cutting rules
+
+**Fan out by disjoint file ownership, never by item.** Disjoint file ownership means each agent edits its own set of files and no file appears in two agents' sets. One item routinely touches several files and one file routinely hosts several items, so an item-partitioned fan-out silently produces two agents writing the same file. Partition the file set first, then assign each item to the agent that edits its files. An item spanning two agents' file sets is either one agent's job with both files, or it is a contract-then-fan-out (above), not a split.
+
+**A barrier is only justified when the next stage needs cross-item context.** Legitimate: deduplicating findings across all units, an early exit that depends on a total count, a synthesis that compares items against each other. Not legitimate: "I want the list flattened before I continue." That is orchestrator convenience, and it costs you the slowest agent in every wave.
+
+**Pass large context by path plus a short gist.** Give an agent the file paths it must read and two or three sentences of why, not the inlined contents. Inlining spends the orchestrator's context to fill an agent's, which is backwards. The fresh context window is the reason you dispatched.
+
+**Every artifact of this method needs a path decided before the phase that writes it.** The registration and the scored run table (`references/noise-floor.md`), the phase-marker map and the extractor (`references/baseline-mining.md`), the ruled finding set (`references/corpus-audit.md`), the file-assignment manifest and the rewrite contract (`references/cut-passes.md`). Pick one directory for the whole engagement and keep them together. The registration must be re-readable by a skeptic after results exist. The extractor and map must be re-runnable when the taxonomy changes. A contract or manifest passed only through a dispatch prompt cannot be checked afterward against what the agents actually did. The durable ones (registration, final scored table, write-up) belong in the repo's own docs location; per-run scratch does not.
+
+**Give a schema to anything you will aggregate.** If the orchestrator will count, sort, dedup, or compare results, specify the fields and the enum values in the dispatch prompt. Parsing prose across dozens of returns is where item counts quietly stop matching.
+
+**Budget the serial segments.** A one-agent contract phase blocks its entire fan-out, and a barrier before verification blocks on the slowest pass. When reporting elapsed time, name the serial segments separately instead of letting the total read as the shape's natural speed. Otherwise the next person concludes the fan-out was slow and removes the contract.
+
+**State what a fan-out did not cover.** Units that queued past the cap and never ran, units an agent skipped, files outside every agent's set: list them. Silent truncation is indistinguishable from full coverage in the result, and a coverage claim you did not verify is the same defect as a bar chosen after the fact.

package/skills/ce-riffrec-feedback-analysis/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: ce-riffrec-feedback-analysis
+description: "Analyze recorded product feedback into evidence for bugs and requirements. Use when a Riffrec capture or other screen, voice, or notes artifact needs interpretation. Use for Riffrec setup, capture, or sharing help when no recording exists yet."
+---
+
+# 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.
+
+**Done:**
+
+- Setup ends with a current capture/share path.
+- Quick analysis ends with one evidence-backed bug report and no durable artifact unless requested.
+- Extensive analysis ends with the complete evidence set and a `ce-brainstorm` handoff unless the user asked for extraction only.
+- A missing input, analyzer failure, or unresolved route ends with an actionable blocker rather than a partial success claim.
+
+## Choose the path
+
+Route from the input. Read only the references named for that route; do not load the other path references.
+
+- **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/analyzer.md`, then `references/quick-bug-report.md`.
+- **Extensive analysis** — input is longer, contains multiple issues, requirements, or a workflow walkthrough, or the user wants requirements material. Read `references/analyzer.md`, then `references/extensive-analysis.md`. Continue into `ce-brainstorm` unless the user explicitly asked only to extract or analyze artifacts.
+
+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 kickoff material, 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.
+
+The Compound Engineering output format used by the extensive path is documented in `references/compound-engineering-feedback-format.md`.

package/skills/ce-riffrec-feedback-analysis/references/analyzer.md

@@ -0,0 +1,18 @@
+# Analyzer contract
+
+All non-setup paths use the bundled analyzer through this one invocation shape. The path reference supplies a concrete `INPUT_PATH`. Set `OUTPUT_DIR` only when that path owns an override; otherwise leave it empty so the script owns its default.
+
+Set `SKILL_DIR` to the absolute directory containing the loaded `ce-riffrec-feedback-analysis` `SKILL.md`. Resolve Python by executing each candidate so a Windows Store stub is not mistaken for a working interpreter:
+
+```bash
+SKILL_DIR="<absolute path of the directory containing this SKILL.md>";
+INPUT_PATH="<absolute input path>";
+OUTPUT_DIR="${OUTPUT_DIR:-}";
+PY="$(for c in python3 python py; do command -v "$c" >/dev/null 2>&1 && "$c" -c '' >/dev/null 2>&1 && { echo "$c"; break; }; done)"; [ -n "$PY" ] || { echo "no working Python 3 interpreter on PATH" >&2; exit 1; };
+ANALYZER_ARGS=("$INPUT_PATH"); [ -z "$OUTPUT_DIR" ] || ANALYZER_ARGS+=(--output-dir "$OUTPUT_DIR");
+"$PY" "$SKILL_DIR/scripts/analyze_riffrec_zip.py" "${ANALYZER_ARGS[@]}"
+```
+
+Accepted inputs are a Riffrec `.zip` or unpacked capture directory containing `session.json` and `events.json`; `.mp4`, `.mov`, or `.webm` video; `.m4a`, `.mp3`, or `.wav` audio; or meeting-notes `.md`.
+
+If no interpreter works or the analyzer fails, report the command's exit status and stderr and stop that path. Do not silently substitute a partial artifact set.

package/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 capture bundle 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
+
+-> Invoke `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.

package/skills/ce-riffrec-feedback-analysis/references/extensive-analysis.md

@@ -0,0 +1,98 @@
+# 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. Set `INPUT_PATH` to the supplied capture and use the invocation in `references/analyzer.md`. Set `OUTPUT_DIR` when the user supplied a destination; otherwise leave it empty so the analyzer owns its default. In a repo with `docs/brainstorms/`, that default goes under `docs/brainstorms/riffrec-feedback/` as an exception for evidence and kickoff artifacts, not as the place durable brainstorm output goes.
+
+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. Unless the user explicitly asked only to extract or analyze artifacts, announce that analysis is complete and invoke `ce-brainstorm` with `requirements-kickoff.md` plus `source-materials.md` as its evidence manifest. The callee owns requirements confirmation and the durable requirements-only unified plan.
+
+## 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/`: normalized capture contents and copied standalone 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.

package/skills/ce-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.

package/skills/ce-riffrec-feedback-analysis/references/quick-bug-report.md

@@ -0,0 +1,38 @@
+# 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. Create `OUTPUT_DIR` with `mktemp -d "${TMPDIR:-/tmp}/riffrec-quick-XXXXXX"`, set `INPUT_PATH` to the supplied capture, and use the invocation in `references/analyzer.md`. Capture the analyzer's 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.