Skip to content

kunitoki/sonic-skills / skills/audio-math-explainer

audio-math-explainer

Unverified

Explains DSP math concepts to developers who need the theory behind an algorithm. Use whenever the user asks how a signal-processing concept works, wants intuition behind a formula, or hits a math-shaped bug. Trigger on phrases like "how does a Fourier transform work", "explain z-transforms", "what is convolution", "why does my biquad ring", "what is windowing for", "what causes aliasing", or "how do I convert gain to dB". Also trigger when the user pastes DSP code and asks why it behaves a certain way.

Audio Math Explainer

The rule: DSP math is small and composable — each concept builds directly on the last. Start with what the user needs, then connect it to code they're writing.

Step 1 — Identify the concept

TopicCore ideaCommon "why"
Fourier transform / DFT / FFTDecompose signal into frequency components"Why does my FFT output look wrong?"
ConvolutionWeighted moving average; LTI system response"How does an IR reverb work?"
Z-transformFrequency-domain analysis of discrete systems"How do filter poles/zeros work?"
Biquad / IIR filtersRecursive difference equation with feedback"Why does my filter ring / go unstable?"
FIR filtersNon-recursive weighted sum"How do I design a linear-phase filter?"
WindowingReduce spectral leakage in DFT"Why are FFT edges smeared?"
Sample rate / NyquistHighest representable frequency = sr/2"What causes aliasing?"
DecibelsLog scale for amplitude/power ratios"How do I convert gain to dB?"

If the user's question maps to multiple rows, start with the most fundamental one and build up.

Step 2 — Explain with three anchors

For each concept, give exactly these three things in order:

  1. Intuition — one sentence a musician could understand
  2. Math — the key formula (inline, no walls of derivation)
  3. Code — one-line pseudocode or a real function call from common audio libraries

Keep each anchor to 1–3 lines. Cut anything that doesn't directly answer the question.

Step 3 — Connect to the user's code

After the three anchors:

  • Locate where the math appears in their implementation (coefficient calculation, loop structure, buffer size choice, etc.)
  • Name the exact variable or line where theory becomes code
  • If a value looks wrong, explain which part of the math it violates

Quick connection table

Math conceptWhere it shows up in code
DFT basis frequenciesbin_index * sr / N — each FFT bin
Convolution sumFIR tap loop: y[n] = sum(h[k] * x[n-k])
Z-plane pole radiusIIR feedback coefficients a1, a2
Nyquist limitif (freq > sampleRate / 2) clamp(...)
Window functionMultiply x[n] *= window[n] before FFT
dB conversiongain_db = 20 * log10(amplitude)

Output format

### [Concept name]

**Intuition:** [one sentence]

**Math:** `[formula]`

**Code:** `[one-liner]`

**In your code:** [where this appears and what it means for their specific question]

See references/dsp-math-reference.md for full formula tables, gotchas, and property lists.

receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 318kUpdated Claude CodeCodexUnverifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 318kUpdated Claude CodeCodexUnverifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 318kUpdated Claude CodeCodexUnverifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 318kUpdated Claude CodeCodexUnverifiedInstall