sdr-wideband-suite/AGENTS.md

AGENTS.md

This file is the repo-level working guide for humans, coding agents, and LLMs. Read it before making changes.

---

1. Purpose of this file

Use this file as the canonical “how to work in this repo” guide. It is intentionally practical and operational.

Use it to answer questions like:

• Where should changes go?
• What must not be committed?
• How should builds/tests be run?
• Which docs are canonical?
• How should debugging work be documented?
• How should agents behave when touching this repo?

---

2. Repo intent

sd r-wideband-suite is a Go-based SDR analysis and streaming system with:

• live spectrum/waterfall UI
• signal detection/classification
• extraction / demodulation / recording
• GPU-assisted paths
• streaming audio paths
• extensive telemetry/debugging support

This repo has gone through active streaming-path and audio-click debugging. Do not assume older comments, notes, or experimental code paths are still authoritative. Prefer current code, current docs in docs/, and current branch state over historical assumptions.

---

3. Canonical documentation

Keep as primary references

• README.md
  • high-level project overview
  • build/run basics
  • feature summary
• ROADMAP.md
  • longer-lived architectural direction
• docs/known-issues.md
  • curated open engineering issues
• docs/telemetry-api.md
  • telemetry endpoint documentation
• docs/telemetry-debug-runbook.md
  • telemetry/debug operating guide
• docs/audio-click-debug-notes-2026-03-24.md
  • historical incident record and final resolution notes for the audio-click investigation

Treat as historical / contextual docs

Anything in docs/ that reads like an incident log, deep debug note, or one-off investigation should be treated as supporting context, not automatic source of truth.

Do not create multiple competing issue lists

If new open problems are found:

• update docs/known-issues.md
• keep raw reviewer/ad-hoc reports out of the main repo flow unless they are converted into curated docs

---

4. Branching and workflow rules

Current working model

• Use focused branches for real feature/fix work.
• Do not keep long-lived junk/debug branches alive once the useful work has been transferred.
• Prefer short-lived cleanup branches for docs/config cleanup.

Branch hygiene

• Do not pile unrelated work onto one branch if it can be split cleanly.
• Keep bugfixes, config cleanup, and large refactors logically separable when possible.
• Before deleting an old branch, ensure all useful work is already present in the active branch or merged into the main line.

Mainline policy

• Do not merge to master blindly.
• Before merge, prefer at least a short sanity pass on:
  • live playback
  • recording
  • WFM / WFM_STEREO / at least one non-WFM mode if relevant
  • restart behavior if the change affects runtime state

---

5. Commit policy

Commit what matters

Good commits are:

• real code fixes
• clear docs improvements
• deliberate config-default changes
• cleanup that reduces confusion

Do not commit accidental noise

Do not commit unless explicitly intended:

• local debug dumps
• ad-hoc telemetry exports
• generated WAV debug windows
• temporary patch files
• throwaway reviewer JSON snapshots
• local-only runtime artifacts

Prefer small, readable commit scopes

Examples of good separate commit scopes:

• code fix
• config default cleanup
• doc cleanup
• known-issues update

---

6. Files and paths that need extra care

Config files

• config.yaml
• config.autosave.yaml

Rules:

• These can drift during debugging.
• Do not commit config changes accidentally.
• Only commit them when the intent is to change repo defaults.
• Keep in mind that config.autosave.yaml can override expected runtime behavior after restart.

Debug / dump artifacts

Examples:

• debug/
• tele-*.json
• ad-hoc patch/report scratch files
• generated WAV capture windows

Rules:

• Treat these as local investigation material unless intentionally promoted into docs.
• Do not leave them hanging around as tracked repo clutter.

Root docs

The repo root should stay relatively clean. Keep only genuinely canonical top-level docs there. One-off investigation output belongs in docs/ or should be deleted.

---

7. Build and test rules

General rule

Prefer the repo's own scripts and established workflow over ad-hoc raw build commands.

Important operational rule

Before coding/build/test sessions on this repo:

• stop the browser UI
• stop sdrd.exe

This avoids file locks, stale runtime state, and misleading live-test behavior.

Build preference

Use the project scripts where applicable, especially for the real app flows. Examples already used during this project include:

• build-sdrplay.ps1
• start-sdr.ps1

Do not default to random raw go build commands for full workflow validation unless the goal is a narrow compile-only sanity check.

GPU / native-path caution

If working on GPU/native streaming code:

• do not assume the CPU oracle path is currently trustworthy unless you have just validated it
• do not assume old README notes inside subdirectories are current
• check the current code and current docs first

---

8. Debugging rules

Telemetry-first, but disciplined

Telemetry is available and useful. However:

• heavy telemetry can distort runtime behavior
• debug config can accidentally persist via autosave
• not every one-off probe belongs in permanent code

When debugging

Prefer this order:

1. existing telemetry and current docs
2. focused additional instrumentation
3. short-lived dumps / captures
4. cleanup afterward

If you add debugging support

Ask:

• Is this reusable for future incidents?
• Should it live in docs/known-issues.md or a runbook?
• Is it temporary and should be removed after use?

If a reviewer provides a raw report

Do not blindly keep raw snapshots as canonical repo docs. Instead:

• extract the durable findings
• update docs/known-issues.md
• keep only the cleaned/curated version in the main repo flow

---

9. Documentation rules

Prefer curated docs over raw dumps

Good:

• docs/known-issues.md
• runbooks
• architectural notes
• incident summaries with clear final status

Bad:

• random JSON reviewer dumps as primary docs
• duplicate issue lists
• stale TODO/STATE files that nobody maintains

If a doc becomes stale

Choose one:

• update it
• move it into docs/ as historical context
• delete it

Do not keep stale docs in prominent locations if they compete with current truth.

---

10. Known lessons from recent work

These are important enough to keep visible:

Audio-click investigation lessons

• The final click bug was not a single simple DSP bug.
• Real causes included:
  • shared-buffer mutation / aliasing
  • extractor reset churn from unstable config hashing
  • streaming-path batch rejection / fallback behavior
• Secondary contributing issues existed in discriminator bridging and WFM mono/plain-path filtering.

Practical repo lessons

• Silent fallback paths are dangerous; keep important fallthrough/fallback visibility.
• Shared IQ buffers should be treated very carefully.
• Debug artifacts should not become permanent repo clutter.
• Curated issue tracking in Git is better than keeping raw review snapshots around.

---

11. Agent behavior expectations

If you are an AI coding agent / LLM working in this repo:

Do

• read this file first
• prefer current code and current docs over old assumptions
• keep changes scoped and explainable
• separate config cleanup from code fixes when possible
• leave the repo cleaner than you found it
• promote durable findings into curated docs

Do not

• commit local debug noise by default
• create duplicate status/todo/issue files without a strong reason
• assume experimental comments or old subdirectory READMEs are still correct
• leave raw reviewer output as the only source of truth
• hide fallback behavior or silently ignore critical path failures

---

12. Recommended doc update pattern after meaningful work

When a meaningful fix or investigation lands:

1. update code
2. update any relevant canonical docs
3. update docs/known-issues.md if open issues changed
4. remove or archive temporary debug artifacts
5. keep the repo root and branch state clean

---

13. Minimal pre-commit checklist

Before committing, quickly check:

• Am I committing only intended files?
• Are config changes intentional?
• Am I accidentally committing dumps/logs/debug exports?
• Should any reviewer findings be moved into docs/known-issues.md?
• Did I leave stale temporary files behind?

---

14. If unsure

If a file looks ambiguous:

• canonical + actively maintained -> keep/update
• historical but useful -> move or keep in docs/
• stale and confusing -> delete

Clarity beats nostalgia.