Orchestrating Precision Audio Engine Debugging
Markdown--- name: orchestrating-precision-audio-engine-debugging description: Orchestrates meticulous, surgical analysis and iterative debugging of a beat/tap-detection audio engine project by directing a literal-executing AI coding agent (e.g., "Laguna S 2.1"), grounding every instruction in a master documentation file (PROJECT_MASTER.MD), validating changes against recorded tap-vs-engine-marker tests, and ensuring no regression of existing working functionality. Use when a non-technical user needs to safely iterate on a working-but-imperfect audio/timing detection system through test-driven validation cycles with a highly literal AI execution agent. ---
Before issuing ANY instruction to the execution agent, do this:
- Read
PROJECT_MASTER.MDin full (project root) — this is the single source of truth for current behavior, architecture, and known constraints. - State the problem in one precise sentence, grounded in what PROJECT_MASTER.MD says currently works.
- Give the execution agent an instruction that includes:
- Context: what currently works (cite PROJECT_MASTER.MD section)
- Problem: specific discrepancy observed (engine marker vs. tap mismatch)
- Constraint: "Do not break any currently documented working behavior in PROJECT_MASTER.MD"
- Scope: exactly which file(s)/function(s) to touch — nothing broader
- Validation requirement: what test/recording must be run after the change, and what success looks like
Never say "fix the timing issue." Say: "In [specific module], when [specific condition], the engine marks a beat at [X] but the user's tap lands at [Y]. Modify only [specific function] to [specific approach]. Do not alter [list of things that must stay the same]. After implementing, output a changelog of exact lines changed."
Progress checklist for every iteration cycle:
- Step 1: Re-read PROJECT_MASTER.MD (or the diff since last read) to confirm current documented state
- Step 2: Identify the single most important discrepancy to fix this cycle (don't batch unrelated fixes)
- Step 3: Draft a surgical, literal instruction for the execution agent (see Quick Start template)
- Step 4: Explicitly instruct: "Update PROJECT_MASTER.MD to reflect this change" as part of the task
- Step 5: Have the human run the test battery (record songs + taps) exactly as before — same conditions, no variables changed
- Step 6: Collect new output files; instruct the execution agent to analyze them against the previous baseline
- Step 7: Ask the execution agent for a plain-language verdict: "Did this get better, worse, or unchanged, and by how much? Show the specific numbers."
- Step 8: Human validates ONLY the thing they can validate: does the engine's marked beat match their tap, yes/no, per song
- Step 9: If worse or unresolved — roll back immediately (instruct agent: "Revert the last change, do not attempt a second fix on top of a failed one")
- Step 10: If better — confirm PROJECT_MASTER.MD was updated correctly, lock in the change, move to next discrepancy
Never let the execution agent make multiple simultaneous changes "while it's in there." One variable per cycle — otherwise a regression can't be isolated.
Example 1: Input: Engine marks beat at 1.452s; user's tap for that beat is at 1.398s, consistently ~50ms early across 5 songs in 4/4 time. Output: Instruction to agent: "In the beat-detection module (cite function from PROJECT_MASTER.MD), there is a consistent ~50ms late-detection offset across 4/4 songs per attached test data. Investigate only the detection latency/offset logic — do not touch tempo estimation or the tap-recording pipeline. Propose a fix, show me the exact lines you will change before applying, then apply, then update PROJECT_MASTER.MD's 'Known Latency' section with the new measured offset."
Example 2: Input: After a fix, syncopated/off-beat songs that previously worked now show mismatches. Output: Flag as regression immediately. Instruction to agent: "This change improved 4/4 accuracy but broke syncopation handling that was documented as working in PROJECT_MASTER.MD section [X]. Revert this specific change entirely. Do not attempt to patch syncopation on top of the reverted state — we will re-approach from the last known-good baseline."
- PROJECT_MASTER.MD is law. Any agent instruction that isn't explicitly grounded in it, or doesn't include updating it, is incomplete.
- One change, one test cycle. Never approve "a few fixes at once" — it destroys your ability to tell what caused what.
- Make the agent show its diff before and after. Literal agents will do exactly what's asked, including mistakes — catching intent errors requires seeing the actual change, not just a description of it.
- Always define the rollback path up front in the same instruction: "If this doesn't improve [metric], revert cleanly."
- Translate validation into the only language the human needs: "Does the marker match my tap? Yes/No, per song, per section." Don't ask the human to judge code quality — only outcome correctness.
- Demand quantified before/after comparisons ("offset went from 50ms avg to 8ms avg") — never accept "it should be better now."
- Treat every new file generated after a recording as evidence, not confirmation. Always have the agent analyze it against the prior baseline before declaring success.
- Vague instructions. "Make the taps more accurate" is dangerous with a literal-execution agent — it will interpret and may silently change unrelated behavior.
- Batching fixes. Multiple simultaneous changes make regressions impossible to isolate.
- Skipping the PROJECT_MASTER.MD update. If documentation drifts from reality, the next cycle's instructions will be built on false premises.
- Accepting subjective success claims from the agent ("this should fix it") without the actual recorded test battery re-run and numeric comparison.
- Stacking a fix on top of an unresolved regression. Always revert to last known-good before trying a new approach.
- Letting the human validate things outside their expertise (code quality, architecture) — their validation role is strictly: tap vs. marker match, yes or no.