wingedguardian/genesis-agi/debugging

Debugging

Purpose

Systematically diagnose and resolve bugs, failures, or unexpected behavior in Genesis or its dependencies.

When to Use

• A test fails unexpectedly.
• Runtime error or unexpected behavior is reported.
• An awareness tick or reflection produces anomalous results.
• Obstacle resolution escalates a technical issue.

Workflow

1. Reproduce — Confirm the issue. Get the exact error, stack trace, or

unexpected output. Define "expected vs. actual."

1. Isolate — Narrow the scope. Which module? Which function? Which input

triggers it? Use binary search on the call chain.

1. Hypothesize — Form 2-3 candidate explanations. Rank by likelihood.
2. Test hypotheses — Write a minimal test or add logging to confirm/deny

each hypothesis. Start with the most likely.

1. Fix — Apply the minimal correct fix. Do not fix adjacent issues in

the same change.

1. Verify — Run the failing test. Run the full test suite. Confirm no

regressions.

1. Document — Record the root cause and fix as an observation. Update

procedures if the bug class is recurring.

Output Format

issue: <one-line description>
date: <YYYY-MM-DD>
root_cause: <what actually went wrong>
fix: <what was changed>
files_modified:
  - <file path>
regression_risk: low | medium | high
lesson: <what to remember to prevent recurrence>

Examples

Example: Hook fails in non-login shell

Trigger: Post-commit hook throws KeyError: 'HOME' in CI-like environment.

Expected output:

issue: Post-commit hook crashes when HOME not set in non-login sessions
date: 2026-04-06
root_cause: Hook script reads os.environ["HOME"] but non-login shells
  (systemd, cron) strip HOME from environment
fix: Guard with os.environ.get("HOME", "/root") fallback + persist HOME
  in /etc/environment during install
files_modified:
  - .claude/hooks/genesis-hook
  - scripts/install_guardian.sh
regression_risk: low
lesson: Never assume HOME exists — non-login shells strip it. Always
  use get() with fallback for environment variables in hook scripts.

References

• tests/ — Test suite for verification
• src/genesis/learning/procedural/ — Procedure updates for recurring patterns