rigdoctor/docs/DECISIONS.md

RigDoctor — Decisions & Open Questions

Format: each item is OPEN (needs a call) or DECIDED (with date + rationale). Decisions D1–D15 were all settled on 2026-05-21; the original open questions are kept below with their resolutions so the reasoning is traceable. No tracked decisions are currently open.

Decided

D1 — Project name — DECIDED 2026-05-21

RigDoctor. Confirmed as the final name (repo, package, and CLI command rigdoctor). Alternatives (RigWatch, GameDoc, Penguin Pit Crew, LGD) dropped.

D2 — Language / runtime — DECIDED 2026-05-21

Python 3 + Qt (PySide6).

• Why Python: fastest AI-assisted development (largest codegen corpus) and a perfect fit for the real workload — parsing nvidia-smi/sysfs/journalctl, CSV/JSON, subprocess.
• Why Qt/PySide6: one toolkit covers both the desktop GUI and the system-tray applet.
• Layering that preserves "low overhead": the core engine, CLI, and crash-logger daemon stay stdlib-only (no hard deps, tiny footprint); only the GUI and tray modules pull in PySide6. This maps cleanly onto the modular installer — a headless/server user never installs Qt.
• Trade-off accepted: the GUI carries a Qt runtime dependency (not a single static binary). Mitigated by shipping a .deb that declares python3 + python3-pyside6 (see D8).

D3 — Distro priority order — DECIDED 2026-05-21

Ubuntu first, by an explicit margin. Debian comes along for free via apt. Arch (pacman) / Fedora (dnf) / openSUSE (zypper) are best-effort later. The package-manager and distro abstraction stays in the design so other distros can be added, but all primary development, testing, and packaging target Ubuntu.

D4 — GPU vendor priority — DECIDED 2026-05-21

NVIDIA first. It's the seed hardware (RTX 3070) and the source of the motivating crash. AMD and Intel come later behind the vendor abstraction; nothing should hard-code NVIDIA in a way that blocks them.

D5 — MVP scope — DECIDED 2026-05-21

M1 + M3 + M4 (the Essential bundle), NVIDIA-only, CLI-first. This is the first build target — it captures the seed crash and explains the logs before any installer, GUI, tray, or multi-vendor work.

D6 — Crash-logger trigger model — DECIDED 2026-05-21

Let the user choose. All three modes are supported and selectable (installer + config):

1. Always-on systemd --user service.
2. Game-launch-triggered (auto-start when a game/Steam session starts, stop after).
3. Manual (CLI command, or the tray applet's "start recording" button). Still open: the exact game-launch detection mechanism — see D12.

D7 — Stress / repro module — DECIDED 2026-05-21

Out of scope. Module M7 is dropped. RigDoctor will not build or bundle stress/load generators. Users who want to reproduce load can run existing tools (gpu-burn, vkmark, stress-ng) themselves alongside the logger.

D8 — Distribution / packaging — DECIDED 2026-05-21

.deb package as the primary distribution channel (matches the Ubuntu-first focus). The .deb declares dependencies per module group; the interactive installer (M9) handles module selection on top. AUR / Flatpak / COPR are possible later, not now.

D9 — Scope of action (read-only vs apply-fixes) — DECIDED 2026-05-21

Read-only + suggestions. RigDoctor diagnoses, monitors, and suggests actions in plain language (with the exact command where possible), but does not apply changes itself in this stage. Auto-applying fixes (governor, power profile, etc.) is a deliberate later milestone, gated behind explicit user consent when it lands.

D10 — GUI is a first-class deliverable — DECIDED 2026-05-21

The app must run three ways: (a) CLI-only / headless (full functionality from the terminal, works over SSH), (b) a desktop GUI, and (c) a system-tray / top-menu-bar applet with quick actions. This supersedes the original "terminal-first, GUI maybe later" non-goal. GUI and tray are separate optional modules over the shared core engine.

D11 — Tray / menu-bar applet — DECIDED 2026-05-21

A small always-available applet in the Linux top menu bar (system tray / StatusNotifierItem, via Qt's QSystemTrayIcon; on Ubuntu/GNOME this surfaces through the AppIndicator extension). Provides quick actions and at-a-glance status. Still open: the exact set of quick actions/indicators — see D13.

D12 — Game-launch detection mechanism — DECIDED 2026-05-21

Layered approach, no root (logger stays a systemd --user service):

1. Wrapper (precise, primary): rigdoctor wrap %command% for per-game Steam launch options, plus an installer helper that registers RigDoctor as a global Steam compatibility tool (covers all Proton games without per-game edits). The same wrapper field works in Lutris/Heroic. Deterministic start/stop, knows the title, needs no watcher daemon. Build first.
2. Zero-config watcher (fallback): low-frequency poll of Steam's RunningAppID (~/.steam/registry.vdf) plus a /proc heuristic for non-Steam launchers, for users who won't edit launch options. Build later.
3. GameMode (opportunistic): if Feral gamemoded is present, use its D-Bus GameRegistered/GameUnregistered signals (via gdbus/busctl — no Python dbus dep).

• Explicitly rejected: root-only kernel mechanisms (proc-connector netlink PROC_EVENTS, eBPF) — they'd force the logger to run as root.
• Phasing: wrapper ships with the game-launch trigger mode (Phase 4); watcher + GameMode follow.

D13 — Tray / menu-bar applet: actions & indicators — DECIDED 2026-05-21

Live readouts (from M1) + a Run Diagnostic action.

• At-a-glance live data shown inline in the tray dropdown, refreshed periodically: CPU temp, GPU temp, memory used/total (e.g. "14 GB / 32 GB"). A status dot (normal / throttling / alert) is proposed alongside.
• Run Diagnostic — the primary action. Launches the guided diagnostic session (SPEC §4): prompts which game to focus on, starts a focused log collection for that game's session (M3, scoped via the D12 game detection), then scans/analyzes (M4) and presents the findings.
• Supporting actions (proposed minimal set): Open dashboard (M10), Start/Stop recording (manual trigger), Snapshot now, Quit.

D14 — Final installer module list & bundles — DECIDED 2026-05-21

Use the current MODULES.md catalog and bundles as final. Modules: M1, M2, M3, M4, M5, M6, M8, M9, M10, M11 (M7 dropped). Bundles: Essential / Monitoring / Diagnostics / Desktop UI (+ Custom). No further additions planned for v1.

D15 — Distro package-name mapping → apt-only — DECIDED 2026-05-21

What it was: RigDoctor's optional modules need a few system packages (smartmontools, lm-sensors, dmidecode, python3-pyside6, AppIndicator). The same tool is named differently per distro (e.g. lm-sensors on apt vs lm_sensors on pacman/dnf; Qt is python3-pyside6 on apt). Supporting multiple distros would require a table mapping each logical dependency to the right package name per package manager. Decision: apt-only. We maintain package names for Ubuntu/apt only and do not build or maintain mappings for other package managers. A thin seam is left in the design so another package manager could be added later, but multi-distro support is not a planned deliverable. Revisit only if Ubuntu-only proves too narrow.

Open

None currently — all tracked decisions (D1–D15) are resolved. New questions will be added here as they arise. Remaining detail to flesh out during build: the tray's supporting-action set (D13 proposed list) and per-module apt package names (filled in as modules land).