环形测试

---
name: ring-test
description: Plan a SumoX-26 ring test session (procedure, pass criteria, safety checklist) or log a completed one with real pass/fail numbers. Use before taking the robot to a ring, or right after a test session.
---

# /ring-test, ring test planner and logger

Two modes. Ask which applies if it isn't obvious from the conversation.

Ring testing is the only verification that counts for traction, edge detection and blade geometry, because none of those exist on a bench. See the test-rung ladder in `.claude/rules/workflow.md`.

## Mode 1: plan, before the test

1. **Ask what's being tested and what would count as passing.** A test without a pre-declared pass criterion is a demo, not a test.

2. Write the procedure:
   - What gets driven, from what starting position, at what speed
   - How many repetitions. Enough for a real pass rate, so 20 runs rather than 3
   - What gets measured, and how it's recorded
   - What gets changed between runs, one variable at a time

3. State the pass criterion numerically. Examples:
   - Edge sensing: *20/20 stops before the white border from full speed, from four approach angles*
   - Edge discrimination: *0 false triggers while crossing the brown centre lines, over 20 passes*
   - Traction: *measured push force against a known resistance, compared across wheel compounds*
   - Blade: *lifts a test opponent's front wheels off the ring in 8/10 head-on approaches*
   - Battery: *three full 3-minute matches without regulator sag or reset*

4. Pre-test safety checklist, mandatory, from `.claude/rules/workflow.md`:
   - [ ] Kill switch tested and working
   - [ ] Battery charged and secured
   - [ ] Blade checked for bend, ride height verified
   - [ ] Wheels clean
   - [ ] Edge sensors calibrated on this ring, today
   - [ ] Someone ready to hit the kill switch

5. Note the calibration trap: edge sensor thresholds are specific to the ring's surface and today's lighting. Recalibrate on arrival, every time. A threshold that worked last month on a different ring will not work. The arena also has brown centre lines, so calibrate against white, brown and black rather than just black and not-black.

## Mode 2: log, after the test

1. **Ask for the real numbers**, not impressions. "17/20 stops, and the 3 failures were all from the 45° approach" is data. "Edge sensing mostly works" is not.

2. Append to `docs/BUILD_LOG.md` using the standard format, with `**Tested:** ring` and the actual pass rate.

3. Diagnose failures against the table below, and record which hypothesis you're acting on.

4. Record parameter changes: old value, new value, and the observed effect. If `config.h` changed, note which constants and why.

5. Update the `.claude/PROJECT_NOTES.md` phase tracker only if the phase deliverable was genuinely met. A 17/20 pass rate does not close a phase that requires 20/20.

## Failure diagnosis

| Symptom | Likely cause | Check |
|---|---|---|
| Drives off the ring | Loop too slow, sensor too far back, threshold wrong | Measure worst-case loop time, check sensor mounting position, recalibrate |
| Stops randomly mid-ring | False edge trigger, from the brown centre lines, noise, or a reflection | Raise the threshold above brown, add hysteresis, check sensor shielding |
| Slow to react at the edge | Blocking call in the control path | Audit the loop for `delay()`, serial prints, unbounded I²C |
| Wheels slip | Hard compound or a dusty ring | Clean the wheels, test a softer compound on wood, confirm the robot is at the weight cap |
| Can't get under the opponent | Blade too high or bent | Measure ride height, check straightness, since blades bend on impact |
| Resets mid-run | Battery sag below regulator dropout | Measure voltage under stall load, not at rest |
| Wanders, or won't drive straight | Motor mismatch, wheel slip, uneven weight | Compare left and right motor response at equal PWM |
| Chases something that isn't there | Opponent sensor seeing past the arena | Confirm the range gate, and check what's standing beyond the safety zone |

## Rules

- Never round up the test rung. Bench is not ring. See `.claude/rules/workflow.md`.
- One variable at a time. Changing three parameters between runs tells you nothing about which one mattered.
- Record failures in full. The failed runs are the useful data; the successful ones just confirm it.
- Don't skip Phase 4, edge sensing, to get to the fun parts. It's the phase teams skip, and then they lose rounds to self-ring-outs.