Fix Bug Procedure

Read CLAUDE.md first. Understand the boundary principle (core vs server) and terminology rules before writing code.

Step 1: Understand the bug

• Read the issue description or task assignment completely
• Read the source file containing the bug
• Read ALL existing tests for that module (tests/test_{module}.py)
• Identify the exact code path that fails

Step 2: Root cause analysis

Write down (in your commit message or PR body):

1. What the code currently does
2. What it should do
3. Why the existing tests did not catch it (this identifies the test gap)

Step 3: Write failing behavior test FIRST

Before touching source code, write a test in tests/test_behavior/ that demonstrates the bug.

The test MUST:

• Assert the expected behavior of the public API
• Fail with the current code
• Follow the naming convention: test_{module}_{parameter_or_feature}_{expected_behavior}
• Live in tests/test_behavior/test_{module}_behavior.py

Run the test to confirm it fails:

pytest tests/test_behavior/test_{module}_behavior.py -v -k "test_name"

Step 4: Fix the source code

Make the minimal change to fix the bug. Do NOT:

• Refactor surrounding code in the same commit
• Add features beyond what the fix requires
• Change unrelated files

Step 5: Verify the fix

pytest tests/ -v --tb=short
ruff check src/ tests/

The behavior test from Step 3 must now pass.

Step 6: Check regression scope

If the fix changes behavior of a public API parameter:

• If the fix touches an adapter, run the adapter parity check:

  pytest tests/test_adapter_parity.py -v
  

Step 7: Docs-code sync check

pytest tests/test_docs_sync.py -v

Step 8: Full verification

pytest tests/ -v && ruff check src/ tests/

ALL must pass before committing.

Step 9: Commit

• Conventional commit: fix: {description}
• No Co-Authored-By
• Include root cause analysis in commit body

Do NOT

• Skip the behavior test — every bug fix must prove the fix works
• Fix multiple bugs in one commit — one fix per commit
• Break core's standalone capability — core must run without the server
• Use banned terminology — check .docs-style-guide.md before writing any user-facing string