Debug Log
Failure notes, decision changes, and engineering judgment.
Entry 001 · ReBalance calibration failureReBalance calibration failureWhen the signal got noisy, I stopped tuning the UI and went back to the measurement model.
failurecalibrationcalmer cue
- context
- FSR pressure values moved even when the user was trying to hold a neutral stance.
- problem
- The UI cue made small measurement changes feel like urgent corrections.
- decision
- Calibrate the baseline first, then expose raw jitter separately from the user-facing cue.
- tradeoff
- The interface became more explicit and less visually simple, but it told the truth about the signal.
- result
- The public cue could stay calm while the raw stream remained available for debugging.
- learned
- Noisy hardware often needs a better measurement model before it needs better polish.
- Raw pressure values drifted enough to make the correction cue feel nervous.
- The fix was not more visual polish — it was calibration: separate noisy input from readable output.
- Next pass: tune dead zone, expose raw strip, keep the user cue calm.
Entry 002 · Flip That Digit debounceFlip That Digit — debounce & release timingPrecise user input requires accounting for mechanical bounce and release timing, not just boolean state transitions.
specdebouncetiming
- context
- Basys3 switches and buttons do not behave like ideal digital events.
- problem
- Held or bouncing inputs could count twice or skip the intended release boundary.
- decision
- Model input as a release-aware state machine before updating game score.
- tradeoff
- The loop has more states, but each game event has a clear physical meaning.
- result
- Input handling became deterministic enough for constrained gameplay.
- learned
- Reliable embedded interaction starts by modeling the physical transition.
- Initial implementation treated button presses as clean edges; gameplay suffered from double-count and missed releases.
- Added debounce state with a small hold window and explicit release detection to make single presses reliable.
- Lesson: model the physical world (bounce, hold, release) in the state machine rather than trying to filter it downstream.
Entry 003 · Operation Surf access modelOperation Surf — access control shaped data qualityPermissions belong in the API layer; leaving them only in the UI produced data leaks and inconsistent behavior.
modelapi-enforcementcoordination
- context
- Volunteer, program, shift, and signup data had different visibility requirements.
- problem
- Client-only checks could not reliably protect private coordination details.
- decision
- Move role-aware filtering and payload shaping into the API layer.
- tradeoff
- Routes became more responsible for workflow shape, but access rules became enforceable.
- result
- Frontend fetching got simpler and public payloads avoided admin-only fields.
- learned
- Data shape is part of product behavior, not just backend plumbing.
- Early deployments relied on client-side role checks and returned inconsistent results when third-party tools accessed the API.
- Moved role enforcement into Next.js API routes and validated at the query layer — reduced accidental overexposure.
- Designing the data model to match how volunteers organize events reduced coordination overhead in the field.
Entry 004 · Vybe Tutor adaptive engineVybe Tutor — deterministic adaptation & privacyKeep grading and adaptation local and deterministic; rely on AI only for explanation generation.
promptingvalidationadaptation
- context
- AI output could generate useful explanations, but learning state needed predictable behavior.
- problem
- Letting the model grade or advance difficulty would make progress hard to trust.
- decision
- Validate generated content with contracts and keep grading/adaptation as local pure functions.
- tradeoff
- The system has stricter boundaries, but the learner loop stays responsive and testable.
- result
- AI stays useful without owning assessment or privacy-sensitive state.
- learned
- Probabilistic generation works best when deterministic product logic boxes it in.
- Gemini provides explanations, but grading must be local to avoid privacy risks and to keep the loop responsive.
- Implemented Zod-validated contracts for all AI outputs so the host can trust structured responses before rendering.
- Adaptive difficulty is implemented as pure functions with unit tests to ensure predictable learning trajectories.