Initial commit: docs, decisions, and M1 sensor core
Planning docs (SPEC, ARCHITECTURE, MODULES, ROADMAP, DECISIONS) with decisions D1-D15 settled: RigDoctor name, Python 3 + Qt/PySide6 stack (core/CLI/daemon stdlib-only), Ubuntu + NVIDIA first, .deb packaging, read-only + suggestions, GUI + tray modules, stress module dropped. First code: the M1 sensor core (stdlib-only) and a CLI. - core engine: Reading/Sample model, Sampler, hwmon reader - self-probing sources (NVIDIA first): nvidia-smi GPU, coretemp/k10temp CPU, /proc/meminfo + DDR5 SPD memory, NVMe storage - CLI: snapshot (text/JSON), monitor, sources; record/report stubbed - stdlib unittest smoke tests Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,127 @@
|
||||
# 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).
|
||||
</content>
|
||||
</invoke>
|
||||
Reference in New Issue
Block a user