| name | expose-tunable-knob |
| description | Expose a live-adjustable control instead of guessing a magic constant for a parameter the agent cannot itself perceive. Use when tuning visual, audio, or UX output (color, size, position, timing, volume) that only the user can judge. |
| allowed-tools | Read, Edit, Write, Grep, Glob, Bash(cargo test *), Bash(npm test *), Bash(pytest *) |
| model | opus |
| created | "2026-07-08T00:00:00.000Z" |
| modified | "2026-07-08T00:00:00.000Z" |
| reviewed | "2026-07-08T00:00:00.000Z" |
Expose Tunable Knob
An agent iterating on a perceptual parameter — a mask's size, a color
threshold, an animation's timing, an audio gain — hits a hard wall the moment
it can't render, watch, or listen to its own output. A human running a live
webcam feed, a rendered UI, or a mixed audio track can judge instantly whether
a value looks or sounds right; the agent, reasoning purely from code and
possibly one static screenshot, cannot. The naive move — pick a value from
domain reasoning, ship it, wait for feedback, repeat — burns a full
rebuild/re-run/re-report round-trip per guess, and the agent's guess still
carries no more information than the human's own eyes would supply directly.
When to Use This Skill
| Use this skill when... | Skip when... |
|---|
| Tuning a value whose correctness is judged by a sense the agent lacks (sight, sound, feel) | The value has an objective, computable correctness criterion (a test asserts the exact number) |
| The user has already pushed back once on a guessed default ("that's better, but...") | This is the first attempt — try a principled default before adding a knob |
| The parameter is genuinely continuous/subjective (position, size, gain, ratio, threshold) | The parameter is binary/structural (a feature flag, an algorithm choice) — that's a decision, not a tuning value |
The runtime already has (or can cheaply gain) a live control surface — a GUI slider, a config‑reload flag, a CLI --watch | Changing the value requires a full redeploy/recompile cycle with no faster path — a knob doesn't help if it's still one guess per round-trip |
The pattern
- Implement the mechanism, not the magic number. Parameterize whatever
currently hardcodes the value — a mask's expansion ratio, a debounce delay,
a color-mix weight — so it reads from config/state rather than a literal.
- Pick a reasoned starting default, not an arbitrary one. Use the best
available signal: the reference implementation's value, a "just a little
more than currently" nudge in the diagnosed direction, or a rough
calculation — record why in a doc comment, since the next reader (agent
or human) needs the reasoning, not just the number.
- Expose a live control at the layer the human already interacts with —
a UI slider (
egui::Slider, a web form range input), a hot-reloadable
config key, a CLI flag re-read per invocation. The requirement is that the
human can change it and see the result without asking the agent to
redo anything.
- Stop guessing values past this point. Once the knob exists, further
"should I bump this to 0.3 or 0.4?" turns are wasted — hand the decision to
the human and move on to the next piece of work.
Worked example
A Rust live face-swap app's mouth-mask feature pastes the real webcam mouth
back over a swapped face, using a landmark-derived polygon expanded by a
mouth_mask_size factor and shifted by a mouth_mask_offset_y bias. Neither
value has an objectively correct answer — "does the opening sit between the
lips, and does the boundary look smooth" is answerable only by someone
watching their own live video. Rather than iterating blind (ship a guess →
wait for a screen-recording or description → guess again), the fix:
- parameterized both values in
ProcessingConfig (mechanism, not constant),
- set defaults reasoned from the known-wrong prior value (Python's
1.0/10%
padding was empirically too tight; 4.0/40% was a deliberate, reasoned
bump, not arbitrary),
- added
egui::Slider controls ("Mouth Mask Size", "Mouth Mask Position") so
the user could dial both in during a single just live session,
turning what would have been an open-ended sequence of "try 0.3 now" /
"still not quite right, try 0.35" exchanges into one code change plus the
user's own real-time tuning.
Anti-patterns
- Silent precision theater: shipping a value to three decimal places
(
0.347) with no note that it's a guess. A guessed value should read as
a starting point, not settled science — the user needs to know it's
provisional so they know to check it.
- Adding a knob nobody can reach. A config field with no UI/CLI surface
and a "rebuild to test" cycle is not a knob — it's the same guess-and-wait
loop with extra steps. The control has to land where the human already is
(the running app), not one layer removed from it.
- Knob sprawl. Not every parameter earns a slider — reserve this for
values the user has already signaled need iteration (see the "skip when"
row above). A UI cluttered with tuning knobs for values nobody disputes is
its own cost.
Relationship to sibling skills
verify-before-plan — verifies facts an orchestrator assumes before
dispatching work; this skill hands off judgment the agent structurally
cannot make itself. Different gaps, same "don't guess — get the answer from
the party who actually has it" instinct.mcp-management / configure-* skills often build the UI surface
(sliders, config files) this pattern exposes a value through — this skill
is about when to reach for that surface, not how to wire it.
