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.

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).

Workflow

The bug-fix workflow is these eight steps — the agent table and prose below key to their step numbers:

1. Investigate root cause (don't guess)
2. Write test that reproduces bug (must FAIL) — read ~/.claude/skills/aidex-bugfix/references/test-patterns.md before choosing the test type: it holds the signal→type decision matrix, the naming convention, the regression-test structure, and the cases where an automated test is the wrong call. The summary below is the first column of that matrix, not a substitute for it.
3. Confirm test fails for the right reason — the failure message names the buggy behavior, not an import/syntax/setup error. Verify this before writing the fix.
4. Implement minimum fix
5. Confirm test passes — capture the GREEN output as proof (see Proof of done)
6. Run surrounding tests (no regressions) — select them, don't run everything: ~/.claude/skills/aidex-audit/scripts/affected-tests.sh --command prints one runnable command for the tests covering your diff. Exit 3 means no selection is available (no module-map.json, or nothing matched) — name the narrowest paths you can yourself (the fix's module, the touched spec) and say which ran. The full suite gates the INTEGRATION boundary — merge to trunk, push, deploy, or the end of an unattended run — not this commit (decision/2026-08-24-full-suite-gate-moves-from-commit-to-integration). Committing on a selected run is legitimate and must never be silent: state which subset ran and that the full suite has not. A selection marked # INCOMPLETE is the one exception that still forces the full suite before the commit — an unmapped change is unknown scope, so the selection proves nothing. That same command also names, on stderr, any file in your diff that measurably breaks and has no E2E reaching it. Write that spec now, before the fix lands — against a disposable database, never dev (rules/e2e-testing.md).
7. Commit test + fix together
8. Guided human verification, at the integration boundary — before the fix merges, pushes or the run ends, not before the commit. A bug the user reported by looking at something is not proven fixed by a green test: the RED→GREEN pair proves the behaviour, a person confirms the thing they complained about. Read and follow ~/.claude/skills/aidex-conventions/references/human-verification-conventions.md — it owns the four moves, the .context/proofs/<slug>/human-verification.md artifact and its proof_links entry, and the recorded skip. Most bugs are not human-visible and skipping is right; it is recorded as human-verification: skipped — <reason> and never left absent, because absent reads the same as forgotten. For a visual/CSS-only bug this step is not optional — it is the only verification there is (see the exception below).

Agent Configuration

This skill uses specialized agents for parallel investigation:

Agent definitions: agents/ directory in this skill folder.

Test Type Decision Guide

Summary of the matrix in test-patterns.md (step 2 reads the full file). 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

• Defer to the project's own testing helpers/patterns for how to write the test
• Follow the project's commit conventions for Step 7 (detect them; git-commit if present)
• If Step 7 needs a new branch (e.g. you were on the default branch), resolve and state its base first — default branch unless explicitly confirmed otherwise (aidex-worktree's branch-base rule)
• 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-<module>-<n> finding.
• If the project tracks a changelog, update it per the project's own rules
• Proof of done. The RED→GREEN pair is the proof the bug is fixed — don't claim it without it. Record it as one commit-body line naming (a) the RED failure reason and (b) the GREEN command + result — e.g. RED: AssertionError expected full IBAN / GREEN: vitest 730/730. For a rare larger capture, save it under .context/proofs/<slug>/ and reference it via proof_links per aidex-conventions (00-global.md §7.1). This is a byproduct of Steps 3 and 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 selected suite stays green, with the full suite once at the loop's end, not per iteration) 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 Step-1 root-cause hypothesis plus the suite covering the diff (the full one at the integration boundary), ideally with a maker≠checker split, and only once the RED test failed for the right reason (Step 3). 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