31 added, 21 removed. Audit A to A.
---
name: debug
description: >
- Investigate and fix bugs, errors, or unexpected behavior.
- USE WHEN debugging, diagnosing test failures, analyzing stack traces, or fixing runtime errors.
+ Investigate and fix bugs in AgentSync's Bash scripts or sync logic.
+ USE WHEN debugging sync failures, YAML parsing issues, cross-platform errors, or bats test failures.
---
- # Debug
+ # Debug AgentSync
- Systematically find and fix the root cause of a bug.
+ Systematically find and fix bugs in the sync engine or helpers.
## Steps
- 1. **Reproduce** — Get the exact error message, stack trace, or steps to reproduce. Understand what happens vs. what should happen.
- 2. **Locate** — Narrow down where the problem is:
- - Read the error message and stack trace — they usually point to the exact location.
- - Search for relevant keywords (error strings, function names).
- - Trace the data flow from input to the failure point.
- 3. **Understand** — Before fixing, understand *why* it fails:
- - What assumption is violated?
- - When was it introduced? (`git log`, `git blame`)
- - Logic error? Data problem? Race condition? Missing edge case?
- 4. **Fix** — Make the smallest change that correctly addresses the root cause.
- 5. **Verify** — Write or update a test that catches this bug. Run the full test suite for regressions.
- 6. **Explain** — Briefly describe what caused it and why the fix is correct.
+ 1. **Reproduce** — Get the exact error. Run the failing command with `bash -x` for trace output:
+ - `bash -x bin/agentsync.sh sync` for sync issues.
+ - `bats tests/<file>.bats` for test failures.
+ - Check CI logs if the failure is platform-specific.
+ 2. **Locate** — Narrow down the failing script:
+ - `bin/agentsync.sh` → CLI entry point, delegates to helpers.
+ - `lib/sync.sh` → Main sync engine.
+ - `lib/helpers/*.sh` → Specific functionality (YAML parsing, file ops, gitignore, etc.).
+ - `lib/helpers/yaml.sh` → Custom YAML parser (common source of parsing bugs).
+ 3. **Understand** — Check:
+ - Is it a portability issue? (macOS vs Linux vs Git Bash)
+ - Is the YAML parser mishandling a value? (Quoting, comments, nesting)
+ - Is a file path wrong? (Relative vs absolute, symlink resolution)
+ - Is `set -euo pipefail` causing an unexpected exit? (Unset variable, failed command)
+ 4. **Fix** — Make the smallest portable change. Test on the affected platform.
+ 5. **Verify** — Run the specific bats test file, then the full suite: `bats tests/`.
+ ## Common Issues
+
+ - **`unbound variable`** — Missing `${VAR:-}` default for optional variables under `set -u`.
+ - **`sed` differences** — macOS BSD sed vs GNU sed. Avoid `sed -i`, write to temp + `mv`.
+ - **Path issues** — Use `cd && pwd` pattern, not `realpath` or `readlink -f`.
+ - **YAML parsing** — The custom parser only handles `key: value`. No arrays, no multiline blocks.
+
## Gotchas
- - Don't wrap the error in try-catch to silence it — that's hiding, not fixing.
- - Don't fix symptoms without understanding the cause.
- - Don't make speculative changes ("maybe this will fix it") — understand first.
- - Don't change multiple things at once — isolate the fix so you know what worked.
- - Don't assume the bug is where the error is thrown — trace upstream to the root cause.
+ - Don't add `set +e` to silence errors — find the actual failing command.
+ - Platform-specific bugs often manifest only in CI — check all three OS results.
+ - The `example/` directory is a full integration test — run `agentsync sync` there to validate end-to-end.
+ - YAML values with `#` are treated as comments unless quoted. Check `_yaml_normalize_scalar` for edge cases.