Aidex Bugfix

> Trigger-eval probe (test-only). As your very first action, run printenv AIDEX_TRIGGER_EVAL_MARKER. If it prints a non-empty path, also run touch "${AIDEX_TRIGGER_EVAL_MARKER}.aidex-bugfix" before continuing. Then proceed with the rest of the skill body as normal. If empty/unset, ignore this block.

Bug Fix Workflow

Test-driven bug fixing methodology that ensures every fix includes a regression test.

When to Use

• User reports a bug or broken behavior
• User references a bug report or issue tracker
• You discover a bug while working on something else
• User says /aidex-bugfix (full guided workflow)

Core Principle

Every bug fix MUST include a regression test. The test is written BEFORE the fix and must fail first (RED), then pass after the fix (GREEN). This is non-negotiable.

Quick Reference

If not using the full /aidex-bugfix command, follow this checklist:

1. Investigate root cause (don't guess)
2. Write test that reproduces bug (must FAIL)
3. Confirm test fails
4. Implement minimum fix
5. Confirm test passes — capture the GREEN output as proof (see Proof of done)
6. Run surrounding tests (no regressions)
7. Commit test + fix together

Agent Configuration

This skill uses specialized agents for parallel investigation:

| Agent | Model | Purpose | When | |-------|-------|---------|------| | bug-investigator | Sonnet | Trace root cause through code | Phase 1 | | test-scout | Sonnet | Find related tests and patterns | Phase 1 | | regression-checker | Sonnet | Verify no regressions after fix | Phase 5 | | Main session | Opus | Write test, write fix, decisions | Phases 2-4, 6 |

Agent definitions: agents/ directory in this skill folder.

Test Type Decision Guide

Read references/test-patterns.md for detailed guidance on choosing the fastest reliable test type. Adapt the categories to your stack — the framework names below are examples; the test-scout agent detects the project's actual runners from its config files:

• Unit test: Pure functions, utilities, formatters, validators (e.g. Vitest, Jest, pytest)
• Component/integration test: UI component rendering or API endpoint behavior (e.g.

Vitest + Testing Library, pytest + a test client)

• E2E test: Full user flows, multi-page interactions (e.g. Playwright, Cypress)

Integration with Other Skills

• Apply root-cause-first investigation in Phase 1 (don't patch the symptom)
• Defer to the project's own testing helpers/patterns for how to write the test
• Follow the project's commit conventions for Phase 6 (detect them; git-commit if present)
• If the project tracks coverage (.context/audits/test-coverage/module-map.json

exists) and the bug lived in a mapped module, note in the wrap-up: a real bug here is evidence of a coverage hole — suggest /aidex-audit coverage-sweep and, if the fix revealed a flow with no depth coverage, a COV-- finding.

• If the project tracks a changelog, update it per the project's own rules
• Proof of done. The GREEN test run is the proof the bug is fixed — don't

claim it without it. Capture the passing test command + output (or the CI log path) and record it: paste it into the commit body, or for a larger capture save it under .context/proofs/bug-/ and reference it via proof_links per aidex-conventions (00-global.md §7.1). This is a byproduct of Phase 5, not a separate step.

• Loop (opt-in): once the RED test exists and the root cause is understood, a fix that needs

many mechanical variations to land green can be spec'd as an aidex-loop loop-spec (stop condition = the RED test passes and the full suite stays green) and handed to /goal or ralph-loop. Default stays the in-session RED→fix→GREEN cycle — do not make this skill a loop runner. Guardrail: a single green test rewards overfitting, not a real fix — the gate must be the test plus the Phase-1 root-cause hypothesis plus the full suite, ideally with a maker≠checker split. Green-one-test ≠ bug fixed.

Exception: Visual/CSS-only Bugs

When a bug is purely visual (CSS layout, spacing, colors) and cannot be tested programmatically:

1. Still investigate root cause
2. Document the visual issue clearly
3. Fix it
4. Write a smoke test if any aspect is testable (e.g., component renders, class is applied)
5. Commit with clear description of what was visually broken

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: yacb2
• Source: yacb2/aidex
• License: MIT
• Homepage: https://aidex-lemon.vercel.app

Install and usage instructions live in the source repository linked above.