# Expose Tunable Knob > 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. - Skill: `laurigates/expose-tunable-knob` (Agent Skill) - Install (CLI): `npx skillmds@latest add laurigates/expose-tunable-knob` - Raw SKILL.md: https://api.skillmd.com/api/skills/laurigates/expose-tunable-knob/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: laurigates (https://skillmd.com/u/laurigates) - Updated: 2026-09-09 - Page: https://skillmd.com/skills/laurigates/expose-tunable-knob --- # 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 1. **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. 2. **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. 3. **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**. 4. **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.