docs: implementation plan for power-profile fan-trigger

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-10 17:54:44 -07:00
parent 5f00fdc2be
commit 841ee432d6
1 changed files with 104 additions and 0 deletions
@@ -0,0 +1,104 @@
+# Power-Profile → Fan-Profile Sync Trigger Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make `scripts/power-profile.sh --menu` instantly trigger `scripts/fan-profile.sh` to re-evaluate (so fan auto mode applies the new mapping in under a second instead of waiting for the next 5 s waybar poll).
+
+**Architecture:** One-line change. Chain `pkill -RTMIN+9 waybar` (the fan widget's signal) onto the existing `pkill -RTMIN+8 waybar` after `powerprofilesctl set` succeeds. Reuses the existing single-source-of-truth mapping in `fan-profile.sh::map_profile_to_strategy` — no new logic, no new files.
+
+**Tech Stack:** bash, waybar (`signal:` mechanism), `powerprofilesctl`, `pkill -RTMIN+N`.
+
+**Spec:** `docs/superpowers/specs/2026-05-11-power-profile-fan-trigger-design.md`
+
+**Verification model:** Bash syntax check covers static correctness; end-to-end behaviour requires a live waybar + active power profile change (controller verifies after merge). One task only.
+
+---
+
+## File Structure
+
+| File | Change |
+|---|---|
+| `scripts/power-profile.sh` | One line modified (line 13): chain `&& pkill -RTMIN+9 waybar` onto the existing `&&`-chained command. |
+
+No new files. No other files touched.
+
+---
+
+## Task 1: Add fan-widget signal to power-profile menu handler
+
+After this task, picking a power profile from the wofi menu fires both the power-widget refresh signal (RTMIN+8) and the fan-widget refresh signal (RTMIN+9). The fan widget's existing handler (in `fan-profile.sh`) checks the auto-mode sentinel and applies the mapped fw-fanctrl strategy if appropriate.
+
+**Files:**
+- Modify: `scripts/power-profile.sh` (line 13)
+
+- [ ] **Step 1: Make the one-line change**
+
+Find line 13 in `scripts/power-profile.sh`:
+
+```bash
+    [ -n "$CHOICE" ] && powerprofilesctl set "$CHOICE" && pkill -RTMIN+8 waybar
+```
+
+Replace with:
+
+```bash
+    [ -n "$CHOICE" ] && powerprofilesctl set "$CHOICE" && pkill -RTMIN+8 waybar && pkill -RTMIN+9 waybar
+```
+
+The only change: append ` && pkill -RTMIN+9 waybar` to the end of the existing chain. Indentation, surrounding lines, and the `if`/`exit` block remain untouched.
+
+- [ ] **Step 2: Syntax-check the script**
+
+```bash
+bash -n scripts/power-profile.sh && echo "syntax ok"
+```
+
+Expected: `syntax ok` and exit 0.
+
+- [ ] **Step 3: Confirm both signals appear in the chain**
+
+```bash
+grep -n "pkill -RTMIN" scripts/power-profile.sh
+```
+
+Expected output (one line, both signals present):
+```
+13:    [ -n "$CHOICE" ] && powerprofilesctl set "$CHOICE" && pkill -RTMIN+8 waybar && pkill -RTMIN+9 waybar
+```
+
+- [ ] **Step 4: Confirm the status-emit branch is unchanged**
+
+```bash
+sed -n '17,27p' scripts/power-profile.sh
+```
+
+Expected: shows the `CURRENT=$(powerprofilesctl get)` block, `case "$CURRENT" in ... esac`, and `printf` JSON line — all byte-identical to before this commit.
+
+- [ ] **Step 5: End-to-end smoke test (controller — subagent skip)**
+
+Subagents have no display; skip this step. The controller will:
+
+```bash
+# Confirm both waybar signals are wired up correctly
+powerprofilesctl get                              # note current profile
+~/.local/bin/power-profile --menu                 # pick a different profile in wofi
+powerprofilesctl get                              # confirm it changed
+fw-fanctrl print | grep '^Strategy:'              # if fan auto is on, this should match the mapped strategy within ~1 s
+```
+
+If fan auto is off (`~/.local/state/fan-profile-auto` does not exist), `fw-fanctrl` strategy stays unchanged — that's the correct behaviour for Option C.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add scripts/power-profile.sh
+git commit -m "power-profile: signal fan widget on profile change"
+```
+
+---
+
+## Final verification (controller, post-merge)
+
+- [ ] With fan auto on: change power profile via the wofi menu → fan strategy follows within ~1 s (`fw-fanctrl print | grep ^Strategy:` shows the mapped value).
+- [ ] With fan auto off: change power profile via the wofi menu → fan strategy unchanged (`fw-fanctrl print | grep ^Strategy:` shows the previously-set manual value).
+- [ ] If `powerprofilesctl set` fails (simulate by stubbing `powerprofilesctl` in `PATH` to return exit 1), neither pkill fires — `journalctl --user -u waybar` shows no spurious refreshes.