helmlog

Reference for deploying to the Raspberry Pi

Review code changes against the HelmLog-specific data licensing policy (docs/data-licensing.md) — embargoes, protest firewall, biometrics consent, gambling exclusion, fleet-benchmark thresholds, coach access expiry. The model recovers general PII / cross-tenant / audit-logging concerns by default; this skill encodes only the HelmLog-specific items that are not recoverable from general engineering judgment. TRIGGER when modifying code that handles user data, PII, co-op/federation data sharing, export endpoints, deletion/anonymization, or audit logging. Key files — storage.py, export.py, peer_api.py, peer_client.py, federation.py, transcribe.py, audio.py, web.py (data endpoints). DO NOT trigger for UI-only changes, instrument decoding, polar analysis, config, docs, or CSS/JS/templates.

Run pre-PR verification checks before creating a pull request. TRIGGER when implementation is complete and the user is ready to create or push a PR — e.g., "create a PR", "ready for review", "push this up", or running /pr-checklist. DO NOT trigger mid-implementation, during TDD cycles, when exploring code, or when the user is still writing features.

HelmLog-specific test patterns and the pre-existing-error allowlist for ruff/mypy. The Red-Green-Refactor cycle and lint commands are already mandated in CLAUDE.md — this skill encodes only the patterns and known-pre-existing-errors list that aren't recoverable from existing tests at a glance. TRIGGER when writing or modifying Python source code in src/helmlog/. DO NOT trigger for documentation, config, templates, CSS/JS, skill definitions, or changes that don't affect runtime behavior.

Run a focused per-race debrief and attach the summary as a moment on the session. TRIGGER when the user says "debrief race N", "debrief that race", "/debrief", "post-race analysis", or asks for analysis of a single specific race. DO NOT trigger for season-wide reviews (that's a manual run of scripts/analysis/full_analysis.py), broad questions about boat performance, or non-race sessions.

Detect OCS (over-the-line at gun, returned to clear) races against the live DB and apply the 'ocs' tag to any newly identified ones. TRIGGER when the user asks "check for OCS", "did we OCS", "tag OCS races", "/ocs-check", or after a race day to find any starts that should be marked OCS. Auto-trigger when running /debrief on a race that hasn't been OCS-checked yet.

Codebase comprehension and complexity tracking — module map, data flow, recent changes, and complexity hotspots. Run with no arguments for a full snapshot or with a date/commit/tag for a delta briefing. TRIGGER when the user asks for a system overview, wants to understand the architecture, asks "what changed while I was away", or needs to orient before a large task. DO NOT trigger for specific code questions, bug fixes, or implementation tasks — those are better served by reading the relevant module directly.

Systematic Pi troubleshooting runbook — checks all subsystems (systemd, nginx, Signal K, SQLite, audio, InfluxDB, Tailscale) and reports health. TRIGGER when the user reports a Pi problem ("helmlog is down", "not recording", "web interface broken", "service won't start") or asks for a health check. DO NOT trigger for development issues on Mac, test failures, code questions, or deployment instructions (use /deploy-pi for those).

Sailing instrument tribal knowledge that is NOT directly grep-recoverable from the code — common-mistake guards, B&G/instrument-vendor quirks, J/105 polar reference targets, and calibration miscalibration symptoms. Auto-triggers when working on sk_reader.py, can_reader.py, nmea2000.py, polar.py, boat_settings.py, synthesize.py, maneuver_detector.py, export.py, or calibration-related code. Skill content is intentionally narrow — for paths, PGN byte layouts, conversion constants, and table schemas already encoded in the source, read sk_reader.py / nmea2000.py / storage.py directly.

Add a new SQLite schema migration to storage.py

Draft a curated RELEASES.md entry from commits since the last stage/* tag. TRIGGER when preparing to promote main → stage, when the user asks for release notes, or when running the promote workflow. DO NOT trigger for general documentation edits, mid-development work, or changes to RELEASES.md that aren't promotion-related.

Blind A/B comparison of two skill versions using eval cases — measures relative improvement across correctness, completeness, conciseness, and actionability.

Generate a structured spec (decision table, state diagram, or EARS) from a GitHub issue. TRIGGER when starting work on a feature with combinatorial logic (role × policy × state), lifecycle state machines, or hardware-critical behavior — especially Critical or High tier modules (auth.py, federation.py, peer_auth.py, storage.py migrations, can_reader.py). DO NOT trigger for simple bug fixes, Low-tier changes, straightforward linear features, or documentation.

Scaffold a new hardware-isolated module with tests and wiring

Capture half-baked ideas into the ideation log (docs/ideation-log.md) for future reference. TRIGGER when the user mentions a speculative idea, "what if we...", "it would be cool if...", or explicitly asks to log an idea. Also trigger when a conversation surfaces an interesting possibility that isn't actionable yet. DO NOT trigger for concrete feature requests (those should be GitHub issues), bug reports, or actionable tasks with clear next steps.

Run federation integration tests — choose the appropriate layer (in-process pytest, Pi harness, or Docker compose) based on the change. TRIGGER when modifying federation.py, peer_api.py, peer_client.py, peer_auth.py, or federation-related storage/auth code. Also trigger when tests/integration/ files change. DO NOT trigger for unrelated test runs, UI changes, instrument decoding, or non-federation features.

Run evaluation test cases against a skill to measure quality, detect regressions, and benchmark performance. TRIGGER when the user asks to test or evaluate a skill, after refining a skill description, or when checking skill quality. DO NOT trigger for running pytest (use /tdd or /integration-test), general code review, or non-skill-related testing.