From 3dc80fec2549f16e818695ff04ca044ce05b37cb Mon Sep 17 00:00:00 2001 From: ded-furby <190979964+ded-furby@users.noreply.github.com> Date: Mon, 8 Jun 2026 06:42:39 +1000 Subject: [PATCH] docs: add reproducible debugging guidance --- docs/testing.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/docs/testing.md b/docs/testing.md index be02ab8..6df68d7 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -28,6 +28,38 @@ Run the full command/library suite through: basectl test base ``` +## Reproducible debugging and completion checks + +Before changing behavior, capture a reproducible failure path: + +1. Save the exact failing command, args, and environment assumptions. +2. Re-run once with full command output visible. +3. Test one hypothesis at a time and stop when evidence confirms or rejects it. + +Start with narrow diagnostics in this order: + +```bash +basectl check +basectl doctor +basectl test +``` + +When failures cross boundaries, map each symptom to ownership: + +- Shell startup/profile changes: `lib/bash/` and `cli/bash/`. +- Manifest and project-discovery behavior: `base_manifest.yaml`, `tests/integration/`, and command mapping code. +- Runtime orchestration changes: `bin/basectl` and `lib/shell/runtime/`. +- Python behavior changes: `cli/python/` and `lib/python/`. + +Use this completion gate before marking a change complete: + +- Run `git diff --check` and capture the command output. +- Run the narrowest validation commands for the changed layer and capture successful + command transcripts in the PR. +- Re-run the repro command(s) that previously failed to show the fix. +- Record whether `basectl check` / `basectl doctor` output and exit status changed, and why. +- If checks cannot run in the current environment, call that out explicitly in the PR notes. + ## Integration Tests Integration tests live under `tests/integration/`. They run real `basectl`