From 51a0272fcf0e429d496160cc0d0236c57d2ce19a Mon Sep 17 00:00:00 2001 From: Jan Svabenik Date: Wed, 25 Mar 2026 17:39:51 +0100 Subject: [PATCH] docs: add repo working instructions --- AGENTS.md | 299 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 299 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..648887f --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,299 @@ +# 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.