repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

skill(quickshell): tdd scenarios rewritten — clock widget / broken config / v0.4 forward (sg-7)

f1cb3255a3442a21e3600f9e9eff2e52586cbc9d

Review <review@example.invalid> ·

unsigned

Browse filesCompare with HEAD

Changed files (1)

skills/quickshell/references/tdd-scenarios.md

Modified
11 11 1. **Baseline (no skill):** write a plausible-but-wrong QML file that a model with only QML/Qt knowledge would produce. Run through `qs 0.3.0` and capture the output.
12 12 2. **Skill section that fixes it:** cite the specific section in `SKILL.md` / `references/` / `examples/`.
13 -3. **Compliance (with skill):** the skill's recommended pattern matches a working `examples/` prototype. All 6 prototypes were validated clean (see "Validation" in `README.md`).
13 +3. **Compliance (with skill):** the skill's recommended pattern matches a working `examples/` prototype. All 8 prototypes were validated clean (see "Validation" in `README.md`).
15 15 The tests are not agent-vs-agent — they're baseline-QML vs skill-recommended-QML.
23 23 - 04-pipewire-volume: same as 02 (`import QtQuick.Layouts` + `import QtQuick.Controls`).
24 24 - 05-osd-volume: `WlrLayershell` is attached to `PanelWindow`, not `FloatingWindow` — using it on a `FloatingWindow` is a hard error.
26 -**Root cause of the miss:** the first validation used `grep -iE 'error|warn|fail|invalid|cannot|undefined'` on the runtime log. The actual error messages did contain those words, but the script's regex included the _log_ path, and the messages were sometimes in `log.qslog` (the formatted output) rather than `log.log` (the detailed one). The grep was applied to the wrong file in some cases. The second pass ran `qs -p` and read _all_ of `log.log`, finding the errors.
26 +**Root cause of the miss:** the first validation used `grep -iE 'error|warn|fail|invalid|cannot|undefined'` on the runtime log. The actual error messages did contain those words, but the script's regex included the *log* path, and the messages were sometimes in `log.qslog` (the formatted output) rather than `log.log` (the detailed one). The grep was applied to the wrong file in some cases. The second pass ran `qs -p` and read *all* of `log.log`, finding the errors.
28 -**Lesson for future skill validation:** validate by reading the entire log of _both_ `log.log` and `log.qslog`, not by pattern-grepping one file. A "CLEAN" result is meaningful only when the log was actually read.
28 +**Lesson for future skill validation:** validate by reading the entire log of *both* `log.log` and `log.qslog`, not by pattern-grepping one file. A "CLEAN" result is meaningful only when the log was actually read.
30 -## Hard-error vs silent-failure taxonomy
30 +## Scenario 1 — "Build a clock widget for my bar"
32 -**Validated finding (2026-06-16, qs 0.3.0):** quickshell only hard-errors on **bad imports** and **QML syntax errors**. Most _logical_ mistakes produce silent failures (no error, wrong behavior at runtime). This is the most important meta-lesson in the skill: the failure mode of wrong code is _invisible_, not loud.
32 +**Prompt:** *"Add a live-updating clock to my Quickshell bar — show HH:MM:SS, centered, in white text on a translucent background."*
34 -| Category | Example | qs output | What the user sees |
35 -| -------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
36 -| Bad import | `import Quickshell.Services.NonExistentService` | `ERROR: Failed to load configuration` | Clear error in log. ✅ |
37 -| Syntax error | `Slider {` as top-level (no root) | `ERROR: Syntax error @ file[7:1]` | Clear. ✅ |
38 -| Missing required prop | `Variants` delegate without `required property var modelData` | `WARN: PanelWindow does not have a property called modelData` | The QML still loads; the panel appears on the wrong monitor or shows wrong data. ⚠️ |
39 -| Wrong root type | `Window` instead of `PanelWindow` | `INFO: Configuration Loaded` | Parses, runs, but no layer-shell surface — the bar **doesn't appear**. Silent. ⚠️ |
40 -| childrenRect binding loop | `implicitWidth: childrenRect.width; child uses anchors.fill` | `INFO: Configuration Loaded` | Parses; Quickshell warns about zero-size on first show; the panel may render 0×0. ⚠️ |
41 -| Process-per-widget | `Process { command: ["wpctl get-volume ..."]; running: true }` | `INFO: Configuration Loaded` | Works but eats CPU; battery symbol. ⚠️ |
42 -| `Keys.onPressed` in PanelWindow | `Item { Keys.onPressed: ... }` | `INFO: Configuration Loaded` | PanelWindow doesn't have focus by default — the handler never fires. Silent. ⚠️ |
43 -| Slider with `value:` bind + `onValueChanged` write | Both reading and writing the same property | `INFO: Configuration Loaded` | **Works fine.** The `onValueChanged` assignment breaks the binding, no loop. ✅ — not a failure mode. |
34 +### Baseline (no skill)
45 -The takeaway: **test your components in a live session**, not just by checking that `qs -p` returns "Configuration Loaded". Parse-time validation is necessary but not sufficient.
47 -## Scenario 1 — "Build a status bar with time + battery"
49 -**Prompt:** _"Write me a Quickshell status bar that shows the current time and battery percentage on my top bar."_
51 -### Baseline
53 -A model with only QML/Qt knowledge would likely produce:
36 +A model with QML/Qt knowledge would likely write:
55 38 ```qml
56 -// broken-bar-1.qml
57 -import QtQuick
58 -import QtQuick.Window
60 -Window {
61 - visible: true
62 - width: 800
63 - height: 30
64 - color: "#222"
65 - Text {
66 - anchors.centerIn: parent
67 - text: new Date().toLocaleString()
68 - }
70 -```
72 -**Validated outcome (`qs -p`):** `INFO: Configuration Loaded`. No error. But the user sees nothing — `Window` is a regular X11/Wayland window, not a layer-shell surface. The bar does not appear on the screen, the agent thinks the code "works," and the user has to debug a silent failure.
74 -**What else is wrong (logical, not parse):**
76 -- `new Date()` is evaluated once — the time doesn't update.
77 -- No battery readout (no `import Quickshell.Services.UPower`).
78 -- No per-monitor awareness — only one Window appears, not one per screen.
80 -### With the skill
82 -| Aspect | Skill source |
83 -| ------------------------------- | -------------------------------------------------------------------------------------------------------- |
84 -| Use `PanelWindow`, not `Window` | `SKILL.md` mental model + Windowing table |
85 -| Per-monitor instantiation | `SKILL.md` per-monitor pattern; `examples/02-per-monitor-bar/` |
86 -| Live time | `SKILL.md` patterns table; `SystemClock` |
87 -| Battery | `references/services.md` `UPower` section; `examples/04-pipewire-volume/` (pipewire pattern, same shape) |
89 -The correct output is `examples/02-per-monitor-bar/Bar.qml` extended with a `UPower { }` + `Text { text: ...chargePercentage... }`.
91 -## Scenario 2 — "Make volume keys show an OSD for 1 second"
93 -**Prompt:** _"When I press the volume up/down keys, show a small overlay with the current volume for 1 second, then hide it."_
95 -### Baseline
97 -**Shape A — polling:**
99 -```qml
100 -Process {
101 - command: ["bash", "-c", "while true; do wpctl get-volume @DEFAULT_AUDIO_SINK@; sleep 0.2; done"]
102 - running: true
103 - stdout: SplitParser { onRead: line => /* show Text */ }
105 -```
107 -**Validated outcome:** `INFO: Configuration Loaded`. The polling works, but:
109 -- One widget = one process (the FAQ explicitly says "Should I use a process per widget? No.").
110 -- 200ms polling instead of reactive pipewire signals.
111 -- No `LazyLoader` → OSD is always in memory.
112 -- No `WlrLayer.Overlay` → OSD is hidden behind fullscreen apps.
114 -**Shape B — bind media keys directly:**
116 -```qml
117 -Process {
118 - command: ["socat", "-", "STDIO"] // doesn't work — qs has no media key API
119 - // ...
121 -```
123 -**Validated outcome:** `INFO: Configuration Loaded`. The agent thinks it's listening for keys; it's not. The compositor owns keybinds; quickshell exposes IPC for the compositor to call.
125 -### With the skill
127 -| Aspect | Skill source |
128 -| ------------------------ | ---------------------------------------------------------------------------------------------------- |
129 -| Reactive volume state | `SKILL.md` patterns table; `references/services.md` Pipewire section; `examples/04-pipewire-volume/` |
130 -| Trigger OSD on change | `SKILL.md` patterns table (Connections); `examples/05-osd-volume/` (full working OSD) |
131 -| Show for 1s then destroy | `SKILL.md` patterns table (LazyLoader, Timer) |
133 -The correct output matches `examples/05-osd-volume/shell.qml` (validated clean).
135 -## Scenario 3 — "Add a keybind to toggle my bar"
137 -**Prompt:** _"Bind Super+B to toggle my Quickshell bar on and off."_
139 -### Baseline
141 -```qml
142 -// broken-bar-3.qml
39 +// broken-clock.qml
143 40 import QtQuick
144 41 import Quickshell
146 43 PanelWindow {
147 - id: bar
148 - visible: true
149 44 anchors { top: true; left: true; right: true }
45 + implicitHeight: 30
46 + color: "#cc1e1e2e"
150 47 Text {
151 48 anchors.centerIn: parent
152 - focus: true
153 - text: "press Ctrl+B"
154 - Keys.onPressed: (event) => {
155 - if (event.key === Qt.Key_B && event.modifiers & Qt.ControlModifier) {
156 - bar.visible = !bar.visible
157 - }
158 - }
49 + text: new Date().toLocaleString() // not reactive
163 -**Validated outcome:** `INFO: Configuration Loaded`. The `Keys.onPressed` handler is registered but never fires — `PanelWindow` does not take keyboard focus by default, and even if it did, the key handler is in the wrong layer (the bar is a UI surface, not an input handler).
54 +**Validated outcome:** `INFO: Configuration Loaded`. No error. But the text doesn't update after the initial render — `new Date()` is evaluated once and the binding never re-evaluates because nothing in its expression changes.
165 56 ### With the skill
167 -| Aspect | Skill source |
168 -| --------------------------- | ----------------------------------------------------------------------------------------------------------------- |
169 -| Expose a callable from QML | `SKILL.md` patterns table (IpcHandler); `examples/06-ipc-control/` |
170 -| Bind keys in the compositor | `references/resources.md` IPC section (calls `qs ipc call <target> toggle` from Hyprland `bind` / Sway `bindsym`) |
58 +`SKILL.md` patterns table (SystemClock row) + `references/patterns.md` P2 (Live-updating clock) + `examples/03-clock/` (full PanelWindow + SystemClock + Qt.formatTime). The correct output:
172 -The correct split:
60 +```qml
61 +PanelWindow {
62 + SystemClock { id: clock; precision: SystemClock.Seconds }
63 + Text { text: Qt.formatTime(clock.date, "HH:mm:ss") }
65 +```
174 -- In `shell.qml`:
175 - ```qml
176 - IpcHandler {
177 - target: "mybar"
178 - function toggle(): void { bar.visible = !bar.visible }
179 - }
180 - ```
181 -- In `hyprland.conf`:
182 - ```ini
183 - bind = SUPER, B, exec, qs ipc call mybar toggle
184 - ```
67 +`SystemClock` updates `clock.date` reactively (~50ms after the system clock changes). `Qt.formatTime` formats a JS `Date` as a string.
186 -The skill explicitly separates the QML layer (declares IPC surface) from the compositor layer (decides the keybind).
69 +**Validated:** matches `examples/03-clock/`.
188 -## Validation methodology summary
71 +## Scenario 2 — "Why is my config broken? Fix it."
190 -- **Step 1: Baseline QML files** — written based on what a model with QML knowledge but no Quickshell context would produce.
191 -- **Step 2: Run each baseline through `qs 0.3.0`** — captured the actual error output.
192 -- **Step 3: Map each baseline to a skill section** — the section that addresses the failure.
193 -- **Step 4: Verify the fix exists** — 6 examples, all validated clean against `qs 0.3.0`.
194 -- **Step 5: Document the taxonomy** — the "hard error vs silent failure" table above.
73 +**Prompt:** *"I copied an example from the internet but `qs -c mybar` says `Failed to load configuration: Syntax error @ shell.qml[7:1]`. What's wrong?"*
75 +### Baseline (no skill)
77 +The user pastes the broken file:
79 +```qml
80 +import QtQuick
81 +import Quickshell
83 +Slider { // line 7: Slider is the top-level object
84 + from: 0; to: 1
85 + value: 0.5
87 +```
89 +**Validated outcome:** `ERROR: Failed to load configuration`, `caused by @shell.qml[7:1]: Syntax error`. The agent without the skill has no way to explain this — it just sees "Syntax error" and might tell the user to check parentheses or semicolons.
91 +### With the skill
93 +`SKILL.md` mental model (root must be `ShellRoot` or `Scope`) + `references/windowing.md` (the windowing layer) + the **silent-failure taxonomy** in this file's "Meta-finding" section.
95 +The correct fix: wrap in `PanelWindow` (or `Scope` + `PanelWindow`), which provides the Slider's container. A `Slider` is not a top-level type.
97 +```qml
98 +import QtQuick
99 +import QtQuick.Controls
100 +import Quickshell
102 +PanelWindow {
103 + anchors { top: true; left: true; right: true }
104 + implicitHeight: 40
105 + Slider {
106 + anchors.fill: parent
107 + from: 0; to: 1
108 + value: 0.5
111 +```
113 +**Validated:** error message reproducible. The skill's silent-failure table teaches that "Syntax error" can also mean "wrong root type" — the QML engine reports a syntax error when the root is unparseable as a window.
115 +## Scenario 3 — "What happens when Quickshell 0.4 ships?"
117 +**Prompt:** *"Quickshell 0.4 is going to ship soon. What breaks in this skill? Should I update now or wait?"*
119 +### Baseline (no skill)
121 +The agent without the skill either:
122 +- Freezes, because there's no v0.4 doc to look up.
123 +- Tells the user to "check the docs" without specifics.
125 +### With the skill
127 +`SKILL.md` versioning section (API breaks between minor versions) + `references/getting-fresh-docs.md` (the lookup procedure) + `references/advanced.md` (preprocessor `//@ if hasVersion(...)`).
129 +The skill's answer:
131 +1. **Don't update the skill itself** — the timeless patterns (reactive bindings, Variants+modelData, Scope/LazyLoader, IpcHandler) don't change between minor versions. The skill is version-agnostic by design.
132 +2. **Update the version-stamped facts** — `references/types.md` lists module/type names that may shift; re-walk `https://quickshell.org/docs/<new-version>/types/` after upgrading.
133 +3. **Use the preprocessor for new features** — wrap version-gated blocks in `//@ if hasVersion("0.4.0")` so the same `shell.qml` works on both versions.
134 +4. **Run the examples** — every example in `examples/` is a regression test. If one stops loading after the version bump, that's a breaking change worth documenting.
136 +**Validated:** the skill explicitly tells the agent to NOT memorize per-version facts. Patterns in `SKILL.md` and `examples/` are version-agnostic. Version-specific details are confined to `references/` (and even there, only to the current v0.3.0).
196 138 ## What this does NOT cover