wzyn20051216/matlab-agent-skills / skills/matlab-signal-vision-ai
matlab-signal-vision-ai
UnverifiedMATLAB workflow for signal processing, DSP, image processing, computer vision, lidar, medical imaging, deep learning, and AI-assisted reproducible experiments. Use for filters, spectrograms, wavelets, object detection, segmentation, classification, training, inference, generated figures, and for verifying signal or vision results — units, windows, Nyquist, filter response, BER/SNR, masks and boxes, IoU/precision/recall/F1, label alignment, transform invertibility, and split leakage.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.5 KB |
| references/signal-measurement-contract.md | markdown | 10.3 KB |
| references/vision-verification-contract.md | markdown | 13.5 KB |
| scripts/mas_ber_check.m | other | 12.6 KB |
| scripts/mas_detect_check.m | other | 21.5 KB |
| scripts/mas_filter_check.m | other | 12.7 KB |
| scripts/mas_image_contract.m | other | 31.4 KB |
| scripts/mas_image_metrics.m | other | 4.5 KB |
| scripts/mas_measure_contract.m | other | 19.8 KB |
| scripts/mas_ofdm_ber.m | other | 6.8 KB |
| scripts/mas_sample_check.m | other | 9.6 KB |
| scripts/mas_seg_check.m | other | 23.0 KB |
| scripts/mas_spectrum_check.m | other | 7.8 KB |
| scripts/mas_split_seed.m | other | 3.6 KB |
| scripts/mas_stat_verdict.m | other | 10.0 KB |
| tests/test_signal_contract.m | other | 21.5 KB |
| tests/test_signal_vision.m | other | 15.8 KB |
| tests/test_stat_decision.m | other | 8.6 KB |
| tests/test_vision_contract.m | other | 35.3 KB |
references/signal-measurement-contract.md
View on GitHub# Signal Measurement Contract (MATLAB DSP / comms)
Purpose: stop reporting a plotted or computed number as a verified measurement.
This reference is loaded only when a signal measurement is being judged:
spectra, filters, sampling chains, BER.
## 0. The one rule
数据能画图不等于测对了. An FFT that renders a pretty peak proves only that FFT
ran. A number is not a measurement until its **units, window, regime and
uncertainty** are stated -- and each is then checked against the record, not
against itself. A missing criterion is `UNDETERMINED`, never `PASS`.
## 1. Units and conventions
| Dimension | Correct form | The trap |
|---|---|---|
| Frequency | `w = 2*pi*f`; every frequency reported as both `f` (Hz) and `fRadPerSec` | `freqz(b,a,w)` without `fs` means rad/**sample**; `freqz(b,a,250,1000)` reads 250 as the point count n, not 250 Hz. A 628 rad/s claim where 628 Hz was meant is caught by the Nyquist check. |
| Power | dB conversion is `10*log10` for power | `20*log10` applied to a power value is a factor-2-in-dB error; -3.01 dB IS 0.5 linear (a correct claim is routinely negative). |
| Amplitude | RMS vs peak; `rms <= peak` holds for ANY signal | swapped labels -- nothing else violates the inequality. Ratio ~sqrt(2) is consistent with a sinusoid; ratio ~1 is not one signal. |
| Energy per bit | `Es/N0 = Eb/N0 + 10*log10(k)` | at k = 2 the gap is 3.01 dB; a BER table read against "SNR" labelled Es but computed as Eb shifts every point. |
## 2. Record and analysis window
- Windowed periodogram power identity: `sum(x.^2.*w.^2)/sum(w.^2)` -- **not**
`mean(x.^2)`. The gap between the two is the taper re-weighting the noise
(measured 7.3e-3 Hann / 6.7e-3 Hamming for a noisy record), estimator
variance, not a scaling bug. `mas_measure_contract` compares a power claim
against BOTH values and reports which one matched: a claim made with a
different window lands in neither.
- Leakage: a tone at a bin boundary concentrates **0.408** of its energy
(measured) instead of 1.000; `leakage = HIGH` makes time-domain-derived
metrics unreadable and switches the relevant checks to `fail`/`undetermined`
rather than grading a noisy peak.
- A claim must state its window; the default assumption (`hann`) is recorded in
`r.claimWindow`, never silently substituted.
## 3. Steady vs transient
- `regime = 'steady'` (default): the record must be stationary at the stated
confidence -- first-half vs second-half block powers, two-sample t screen
with the **exact** t table for 95% and nu <= 15 (the Cornish-Fisher closed
form is 4% low at nu = 3, which makes a correct record fail ~1 run in 20).
Drift beyond the limit is printed as a `fail` with both half-powers.
- `regime = 'transient'`: stationarity is deliberately not asserted
(`status = na`); a note warns that whole-record spectra mix the transient.
The rest of the contract still applies.
## 4. Confidence intervals
- Power: block t-interval (default 12 blocks) -- every PASS carries one.
- Frequency: quoted only when each block holds >= 64 samples AND >= 10 cycles
of the measured tone. With 83 samples per block (4.15 cycles of a 50 Hz
tone) per-block peaks averaged **48.58 +/- 0.13 Hz for a 50.00 Hz signal** --
tight and wrong at the same time. Below the gate the tool says so instead.
- A record too short for an interval (blocks < 8 samples) is `UNDETERMINED`:
an uncertainty-free number is not graded as a success.
## 5. Four check states, one funnel
| Status | Meaning | Effect on verdict |
|---|---|---|
| `pass` | verified against the record/reference | -- |
| `fail` | contradicted by the record | FAIL |
| `na` | the contract does not apply (spec states no such requirement) | none |
| `undetermined` | missing evidence or missing criterion | UNDETERMINED |
Verdict: any `fail` -> FAIL; else any `undetermined` -> UNDETERMINED; else
PASS. `na` is only for "not asked for" -- it is never a silent pass, and
`undetermined` is never skipped.
## 6. Filter verification
- Two independent routes: `freqz(b,a,fGrid,fs)` vs direct evaluation of
`H(z) = sum(b_k z^-k)/sum(a_k z^-k)` at `z = exp(-j 2 pi f/fs)`; must agree
to 1e-9, else a unit convention is being misused.
- The stopband number is the **worst** response over `[fstop, fs/2]` (or
`[0, fstop]` for highpass) on a dense grid, with the worst point printed. A
3-tap comb designed to null 183.07 Hz: 61.79 dB at the token frequency vs
**11.30 dB** measured at 366.2 Hz -- an edge-only rule certifies the filter,
worst-over-band fails it against its 40 dB spec. Hand value: the comb's
minimum is `2/(3*sqrt(6))` -> 11.3033 dB.
- IIR stability = poles strictly inside the unit circle, with the margin
`1 - max|pole|` printed; a pole at 0.9999 carries a rounding warning.
- Passband ripple is graded only when the spec states `apassDb`; otherwise
measured and reported as `na`.
- Linear phase: graded only for FIR (a == 1) that is symmetric or
antisymmetric (types I-IV by length parity); the **measured** group delay
`-diff(unwrap(angle(H)))/diff(w)` must equal `(N-1)/2` samples. An IIR with
a symmetric numerator or an asymmetric FIR is not linear-phase and, when the
spec never asked, is `na` with the measured variation -- not `fail`.
## 7. Sampling chain
- Nyquist vs the **claimed** band, with the fold printed: 300 Hz content at
fs = 500 appears at `|300-500| = 200` Hz, indistinguishable from a real
200 Hz signal.
- Asymmetry: the spectrum can CONFIRM content below the claim; it can never
rule out content above Nyquist -- that is what the fold check is for.
- Reconstruction is graded only against an independent analytic truth, and the
record is first verified to BE samples of that truth (1e-9); a mismatched
pair would otherwise grade a reconstruction against the wrong function.
Bandlimited interpolation is exact for periodic, strictly-below-Nyquist
signals; for an aliased record the error blows up -- which is the measurement
of the damage, not an assertion about it. No truth -> `undetermined`
("no truth, no pass").
## 8. BER is a count, not an amplitude
- Grade with a z-test against counting noise: `z = (p_hat - p0)/sqrt(p0*(1-p0)/n)`,
|z| <= 3. A flat tolerance gets both directions wrong: at BER 1e-4 over 1e6
bits (~100 errors) counting noise is 10% -- slack where it should be tight;
at 1e-5 (~10 errors) it is 30% -- rejects correct measurements.
- Zero errors certifies only an upper bound `-ln(1-L)/n` (3.0e-6 at 95% over
1e6 bits), never "BER = 0"; against a 6 dB QPSK theory of 2.4e-3 that same
zero count is z = -48.9, meaning the noise is SMALLER than the label claims
-- just as wrong, just as flagged.
- Theory: BPSK/QPSK `0.5*erfc(sqrt(Eb/N0))` exact; 16/64QAM use the standard
Gray approximation and say so. A run whose CI cannot distinguish the claimed
SNR from a 2x different one returns `UNDETERMINED` (collect more bits).
- Tolerances come from counting noise, not taste: the frozen S1 reference uses
20%/20%/45% for 0/4/8 dB because at 8 dB only ~49 errors are counted and the
Poisson spread is 14% -- a 15% pass mark would reject correct code half the
time.
## 9. Tool -> dimension map
| Tool | Owns |
|---|---|
| `mas_measure_contract(x, fs, claims)` | units, Nyquist, freq/power/peak/rms agreement with the record, regime, expected-vs-measured, block CIs |
| `mas_filter_check(b, a, spec)` | dual-route response, stability, worst-over-band stopband, ripple, linear-phase group delay |
| `mas_sample_check(x, fs, opts)` | Nyquist margin + fold, peak vs claimed band, reconstruction vs truth |
| `mas_ber_check(nErr, nBits, spec)` | Eb/Es convention, z-test vs theory, Wilson CI, Poisson zero-error bound, resolution |
| `mas_stat_verdict(nErr, n, spec)` | the five evidence states of any counted claim; the state decides the verdict |
| `mas_spectrum_check` (legacy) | leakage, concentration, window-weighted Parseval |
### 9.1 The five states, and why two of them are not one
`sufficient-support`, `sufficient-refutation`, `insufficient-sample`,
`interval-straddles-target`, `criterion-missing`. The last three all print as
UNDETERMINED but prescribe opposite actions, so collapsing them loses exactly
the information a reader needs: `insufficient-sample` means *collect more
trials*, `interval-straddles-target` means *the estimate sits at the threshold,
so re-think the claim*, `criterion-missing` means *nobody stated what would
count*. An agent handed one "inconclusive" bucket tends to pick whichever
direction it wanted, which is the failure recorded in the Phase 5.5 H-SIG-B
episode: it computed the right numbers (expected count 0.31, P(0 errors) = 0.74,
exact 95 % upper bound 2.31e-2 = 9.7x the theoretical 2.39e-3, 41871 bits needed
for ~100 expected errors) and then wrote FAIL, i.e. it read "cannot show" as
"shows not".
Two rules the flow enforces in both directions:
- Zero counted events is a **bound**, not a rate: `p <= 1-(1-L)^(1/n)` exactly
(3/n at 95 %). If the stated target is above that bound the run certifies it
and says `sufficient-support`; saying UNDETERMINED there would discard the
only evidence a rare-event measurement can produce.
- Zero counted events with **plenty** of expected events is a refutation
(0 errors in 1e6 bits at 6 dB Eb/N0 means the noise is smaller than labelled,
`z = -49`), so the power test must not be applied blindly: the same zero count
is inconclusive at n = 128 and damning at n = 1e6.
## 10. Independent cross-checks used in tests
- Hand algebra: comb null `2/(3*sqrt(6))` -> 11.3033 dB at 366.14 Hz (tool
agrees to 0.06 Hz); moving-average ripple `20*log10(1/cos(pi*100/1000))` =
0.4359 dB; worst-over-band on a 20001-point grid 60.1024 vs tool 60.1029 dB
(diff 4.5e-4).
- Design generators, not the code under test: `kaiserord` orders 37/@5.6533 ->
60.10 dB vs a 50 dB spec; `buttord` order 7 -> 30.00 dB vs 25 dB.
- Closed forms: `erfc` for QPSK; Wilson interval with literal
`zq = 1.959963984540054`; `-ln(0.05)/1e6 = 2.9957e-6`.
- Negative controls (every metric that could pass vacuously has one):
half-bin offset must drop concentration to 0.408; 20log10 power gives 0.25
where 0.5 is correct; the comb-null filter passes an edge-only rule and must
fail worst-over-band; a 4 dB record labelled 6 dB must give z ~ +106; zero
errors against ~2400 expected must give z < -3.
- Never "run the same algorithm twice" and call it independent.
Evidence: `tests/test_signal_contract.m` 42/42, log at
`artifacts/phase53/evidence/task1_contract_tests.log`.Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies. | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |
| meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要". | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |