docs/09-risks.md

09 — Risks & Mitigations

Risks ranked by impact × likelihood. Each has an owner, a mitigation, and a contingency.

Risk matrix

#	Risk	Likelihood	Impact	Severity	Status
1	Cloud GPU unavailable during demo	Low	Critical	HIGH	Mitigated
2	SA3 inference too slow on Vega	High	High	HIGH	Mitigated
3	LoRA training fails / produces bad output	Medium	High	HIGH	Mitigated
4	Voice recognition unreliable in noisy venue	High	Medium	MEDIUM	Mitigated
5	Reaper Web Control API changes / doesn't work	Medium	Medium	MEDIUM	Mitigated
6	Pattern templates too few / too low quality	Medium	Medium	MEDIUM	Mitigated
7	Onomatopoeia parser doesn't understand users	Medium	Low	MEDIUM	Mitigated
8	Screenreader breaks during demo	Low	Medium	MEDIUM	Mitigated
9	Network drops during demo	Medium	High	MEDIUM	Mitigated
10	Solo bottleneck — running out of time	High	High	HIGH	Mitigated
11	Team conflict / teammate leaves	Medium	High	MEDIUM	Monitor
12	Licensing issues with training data	Low	High	MEDIUM	Mitigated
13	Browser doesn't support Web Speech API	Low	High	MEDIUM	Mitigated
14	MIDI export has bugs that only show in Reaper	Medium	Medium	MEDIUM	Mitigated
15	Audio sample quality is generic	Medium	Medium	MEDIUM	Mitigated

---

High-severity risks

Risk 1: Cloud GPU unavailable during demo

Scenario: RunPod has an outage, you can't reach your instance, the venue WiFi blocks the connection, or your account gets suspended.

Mitigation:

• Pre-generate ALL demo samples before the event, store in cache/ directory
• Have a backup account on a different provider (Vast.ai + RunPod)
• Test cloud GPU connection from the venue WiFi before the demo

Contingency:

• Run inference on Vega locally (slow but works)
• Use pre-generated samples only and label them as "preset variations"
• Record a video of the working demo as ultimate fallback

Owner: You. Verified: Test cloud GPU from venue network on day 1 morning.

---

Risk 2: SA3 inference too slow on Vega

Scenario: A 30-second sample takes 15 minutes on your Vega. The demo times out.

Mitigation:

• Establish baseline performance in pre-hack week 1 (see C1 in 08-build-plan.md)
• If > 5 min per sample on Vega, commit to cloud-only
• Pre-generate demo samples on cloud GPU
• Cache aggressively (LRU + disk)

Contingency:

• Demo with cached samples only, narrate "this was generated earlier by the model"
• Show inference happening live as a "by the way, look, it's running" secondary moment, not the main demo

Owner: You. Verified: Run scripts/smoke_test.py on Vega before the event.

---

Risk 3: LoRA training fails / produces bad output

Scenario: Training crashes, or the resulting LoRA makes samples worse than the base model.

Mitigation:

• Run a small training (200 steps) first to verify the pipeline
• Train the real LoRA at least 3 days before the event, so you have time to iterate
• Keep the base model as a fallback (can disable LoRA at inference time)
• Document the training hyperparameters so you can reproduce if needed

Contingency:

• Ship with the base SA3 model only, label output "Stable Audio 3, no fine-tuning"
• Do a quick second training attempt during the hackathon if you have cloud GPU time
• Be honest with the jury: "we attempted fine-tuning but the base model worked better for the time we had"

Owner: You. Verified: Complete first training run before pre-hack week 3.

---

Risk 10: Solo bottleneck — running out of time

Scenario: You try to do everything alone, run out of time, ship a half-finished product.

Mitigation:

• Aggressive scope cut (see 08-build-plan.md)
• Pre-build as much as possible in the 3 weeks before
• Define the minimum viable demo path and protect it ruthlessly
• Daily checkpoint reviews to catch overruns early

Contingency:

• Ship a narrower demo: voice prompt → MIDI export only, no samples
• Have a video walkthrough of the missing features
• Focus the live demo on the 2–3 things that work perfectly

Owner: You. Verified: C6 (demo path works) at end of day 1.

---

Medium-severity risks

Risk 4: Voice recognition unreliable in noisy venue

Scenario: The hackathon venue is loud. Web Speech API gets garbage transcripts. Demo fails.

Mitigation:

• Use a headset mic / close-mic'd setup, not the laptop mic
• Test voice recognition in a noisy environment before the event
• Have a fallback path: type the prompt instead of speaking
• Push-to-talk (Spacebar to start/stop) avoids picking up ambient noise

Contingency:

• Switch to typed prompts for the demo if voice fails
• Use a quieter corner of the venue for the live demo
• Have a backup video of working voice mode recorded in a quiet space

Owner: You. Verified: Test voice in actual venue conditions.

---

Risk 5: Reaper Web Control API changes / doesn't work

Scenario: Reaper updates, the WebSocket format changes, your client breaks.

Mitigation:

• Test against your installed Reaper version (currently 7.x) before the event
• Hard-pin the WebSocket protocol version in your client
• Have the fallback path: "type the BPM manually"

Contingency:

• Demo without Reaper integration, just type the BPM
• Show Reaper integration in a video if live fails

Owner: You. Verified: Test on your Reaper install before the event.

---

Risk 6: Pattern templates too few / too low quality

Scenario: You write 5 patterns, all of them are slightly wrong. Jury asks for a beat you don't have.

Mitigation:

• Aim for 18–20 patterns before hackathon
• Write the 6 demo-critical ones first
• Each pattern tested in Reaper before the event
• Have a "blank bar" fallback that lets the user define their own

Contingency:

• Generate variations from existing patterns (different bars, different cymbals, half-time)
• Be honest: "we focused on metal first, here's what we have"

Owner: You. Verified: C3 (6 patterns authored) at end of week 2.

---

Risk 7: Onomatopoeia parser doesn't understand users

Scenario: User says "tupatupatupa" but the parser doesn't recognize it. Falls back to genre vocabulary, picks the wrong pattern.

Mitigation:

• Curate the onomatopoeia table with multiple variants per pattern
• Phonetic matching with Levenshtein distance
• Confidence threshold (0.7) below which the parser asks for confirmation
• "I heard X, did you mean Y?" response

Contingency:

• The user can always type the pattern name explicitly
• "Try one of these patterns: [list]" response

Owner: You. Verified: Test the top 20 onomatopoeia phrases manually.

---

Risk 8: Screenreader breaks during demo

Scenario: NVDA crashes, VoiceOver doesn't pick up the UI, the screenreader demo fails.

Mitigation:

• Test NVDA + Chrome on the demo machine before the event
• Have a backup screenreader (VoiceOver on Mac, JAWS if you have access)
• Record the screenreader demo as a backup video
• Rehearse the keyboard navigation by feel, not by sight

Contingency:

• Show the recorded video of the working screenreader demo
• Skip the live screenreader demo, focus on the voice mode
• Describe the accessibility features narratively

Owner: You. Verified: Test on the demo machine, not your dev machine.

---

Risk 9: Network drops during demo

Scenario: Venue WiFi dies, you can't reach the cloud GPU for inference.

Mitigation:

• Pre-generate all demo samples, store locally
• Run a local copy of the audio service on the demo machine as backup
• Have a mobile hotspot as tertiary fallback

Contingency:

• Demo with cached samples only
• Acknowledge the network issue honestly if it comes up

Owner: You. Verified: Confirm cloud GPU + local backup both reachable from venue.

---

Risk 11: Team conflict / teammate leaves

Scenario: A teammate you recruited flakes, or there's conflict about direction.

Mitigation:

• Have all critical code paths owned by you as backup
• Set clear expectations early (what's the demo, what's the deadline)
• Communicate scope cuts in real time

Contingency:

• Cut features the flaky teammate was working on
• Lean on the must-haves list

Owner: You. Status: Monitor.

---

Risk 12: Licensing issues with training data

Scenario: A sample you used is actually copyrighted, you get called out, model card needs to be pulled.

Mitigation:

• Every sample has a documented source and license in the manifest
• Prefer CC0 / CC-BY / original recordings
• For Freesound samples, filter to CC0 or CC-BY only, document the user
• For your own recordings, document date and context

Contingency:

• If a license is questioned, replace that sample and retrain (time permitting)
• Be transparent in the model card about licensing discipline

Owner: You. Verified: Manifest reviewed before publishing.

---

Risk 13: Browser doesn't support Web Speech API

Scenario: Demo machine has Firefox, Web Speech API doesn't work.

Mitigation:

• Test on the demo browser before the event
• Chrome is the assumption — install it on the demo machine

Contingency:

• Switch to typed prompts only
• Use a different laptop with Chrome

Owner: You. Verified: Test on demo browser.

---

Risk 14: MIDI export has bugs that only show in Reaper

Scenario: MIDI plays wrong in Reaper, or doesn't import at all.

Mitigation:

• Test every pattern in Reaper before the event
• Use a known-good GM drum map
• Set tempo in the MIDI file header to match project tempo
• Test on the actual Reaper version you'll use at the event

Contingency:

• Fix the bug live (if quick)
• Show the MIDI in a different DAW if Reaper is broken
• Generate a Reaper project file (.rpp) that includes the MIDI in a known-good arrangement

Owner: You. Verified: Full end-to-end test in Reaper.

---

Risk 15: Audio sample quality is generic

Scenario: Even with the LoRA, the samples sound like generic AI drums, not brutal.

Mitigation:

• Iterate on the training dataset (more samples, better curation)
• Iterate on prompt engineering (try different intensity descriptors)
• Generate multiple variations and pick the best

Contingency:

• Show the variations, frame as "exploring the space"
• Be honest: "SA3 with our LoRA is good but not perfect yet — here's what it produces"

Owner: You. Verified: Listen to samples before the event.

---

Risk ownership summary

Owner	Risks
You (all)	All risks by default
Future teammate (frontend)	R10 (solo bottleneck) — if recruited
Future teammate (ML)	R3 (LoRA), R2 (Vega speed) — if recruited

What we're explicitly NOT risking

• Building features that won't be demoed
• Custom DAW plugins (too risky for the timeframe)
• Mobile apps
• Cloud accounts / user authentication
• Anything that requires a third-party API key beyond SA3

---

Current Jam Buddy bugs & findings (verified against Stability API docs)

These are open/confirmed items tracked for the current work. Docs consulted: platform.stability.ai/docs/api-reference → post /v2beta/audio/stable-audio/audio-to-audio.

1. SA3 strength (noise/denoising) is NOT being sent — open bug (high priority)

The SA3 audio-to-audio request schema exposes a strength parameter (a.k.a. denoising): 0 = output identical to input, 1 = as if no input was given. We do not send it, so it defaults to 1 = full diffusion. This explains:

• "generations render nothing new" (input take fully morphed / barely anchors output)
• "output contains more than one instrument" (the take's instrument doesn't anchor, model freely adds others)

Stability's guidance for audio-to-audio is strength ≈ 0.5–0.8 (diffuse the take but keep it as the anchor). This is the pending "Noise knob" task — wire strength into tools/jam_buddy_api.py and expose it in the UI. UNSENT today.

2. The audio API has NO negative_prompt — confirmed

SA3 audio-to-audio only accepts: prompt, audio, model, duration, seed, steps, cfg_scale, output_format, strength. There is no negative_prompt. (Negative prompts exist on Stable Image, not Stable Audio.) So we cannot steer away from extra instruments via a negative prompt — the positive prompt + cfg_scale

• strength are the only levers. The local CPU fallback (small-music) DOES accept a negative prompt.

3. Demo examples can't be played — RESOLVED

The clickable demo chips (Gradio-style) load MIDI as a take, but preview playback doesn't work — the MIDI examples need to render to audio to actually be audible as a "playable example." Consider pre-rendering the demo MIDIs to audio (or ensuring the Web-MIDI synth preview actually plays).

Resolved: demos now load their pre-rendered MP3 as an audio take (with the BPM knob pinned to the source MIDI's tempo), and playback is a play/stop toggle on the waveform. Single-select + instant highlight/knob update.

4. Stale .next cache corrupts the dev server (recurring) — OPEN

next dev's incremental cache corrupts after heavy edits. Symptoms: API routes 500 (MODULE_NOT_FOUND in webpack-runtime.js) OR the page renders blank (every /_next/static/chunk 404s while GET / still returns 200). Often a leftover process squats on port 3000. Fix today: kill the port-3000 PID (netstat -ano | grep :3000, taskkill /F /PID), rm -rf apps/web/.next, restart pnpm dev, verify chunks load (not just GET /). Address later — candidate: a dev:clean npm script that clears .next before starting, or a more robust dev workflow.