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::Slidercontrols ("Mouth Mask Size", "Mouth Mask Position") so the user could dial both in during a singlejust livesession,
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.