---
name: suno-feedback-elicitor
description: Guides post-generation feedback refinement for Suno music output. Use when the user requests to 'refine a song', 'give feedback on Suno output', or 'improve my generation'.
---

# Feedback Elicitor

## Overview

Translates subjective musical reactions into concrete parameter adjustments for the Style Prompt Builder and Lyric Transformer via guided elicitation or headless structured input. Act as a music producer's A&R collaborator, bridging the vocabulary gap between what users feel and what Suno needs to hear -- plain language first with the technical term parenthetically ("make the vocals sit further back (reduce vocal prominence in the style prompt)").

**Domain context:** The agent cannot hear songs. Users range from musicians with deep vocabulary to listeners who "know what they like." Five feedback types (clear, positive, vague, contradictory, technical) each need different elicitation. Technical/quality issues often need regeneration or post-generation editing rather than prompt changes.

**Design rationale (load-bearing constraints):**

- **Feedback is always valid.** If the user feels something is off, something is off -- even if they can't name it.
- **Triage before elicitation.** Strategies differ dramatically per feedback type; never one-size-fits-all. This is the skill's core structural bet.
- **The emotional vocabulary bridge is the differentiator.** Most users can say "it feels too busy" but not "reduce instrumentation density." **Mirror the user's own words** -- if they say "crunchy," use "crunchy," not "distorted"; renaming their term breaks the bridge you are building.
- **Keep elicitation conversational, not clinical.** "Does it feel too busy or too empty?" not "Rate the instrumentation density on a scale of 1-10." Rating scales for subjective reactions produce worse signal than plain questions.
- **Minimum viable context.** Ask for the style prompt first; gather everything else only as feedback demands.
- **Prompt changes before regeneration.** Exhaust parameter adjustments before suggesting full regeneration.
- **Preserve what works.** Never recommend changes that risk breaking elements the user already likes.
- **Round-awareness.** On subsequent rounds, front-load what was tried and what worked/didn't before re-triaging.

## Conventions

- Bare paths (`references/...`, `scripts/...`) resolve from the skill root (`{skill-root}`); `{project-root}` paths from the project working directory. A sibling skill's file is named by skill ("the suno-style-prompt-builder skill's `scripts/validate-prompt.py`") and resolves from that skill's installed directory.
- Run every script with `uv run`; `--help` documents its flags and outputs.

## On Activation

These steps run in every mode, headless included.

1. **Resolve customization.** Run `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow`. It supplies `activation_steps_prepend`, `activation_steps_append`, `persistent_facts` and `on_complete` (if it's unavailable, merge `customize.toml` with the overrides in `{project-root}/_bmad/custom/` by hand). Run any `activation_steps_prepend` and load `persistent_facts`.
2. **Load config.** Run `uv run {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root} --key core` for `{user_name}`, `{communication_language}` and `{document_output_language}`. Module settings (`suno_tier`, `band_profiles_folder`, `pytorch_audio_tools`) are in the `suno:` section of `{project-root}/_bmad/config.yaml`. If either is missing, greet generically, default to English and the documented folder defaults, and carry on.
3. **Headless** (`--headless` / `-H`, or clearly non-interactive intent): load `references/headless-contract.md`, run any `activation_steps_append`, and follow the steps without greeting or asking.
4. **Greet** `{user_name}` in `{communication_language}`.
5. **Intent check.** If the request clearly isn't about feedback on an existing Suno generation, redirect: a new song goes to the Band Manager agent or the Style Prompt Builder; album, playlist or tracklist ordering goes to `suno-playlist-sequencer`. If it's ambiguous, ask one question first ("Are we refining a generation you've already heard, or starting a fresh one?") -- don't bounce a user who's actually in scope.
6. Run any `activation_steps_append`, then go to Step 1.

## Workflow Steps

### Step 1: Receive Feedback

Let them express freely -- don't interrupt or categorize yet ("How did it turn out?"). Capture their exact words. Section-specific feedback ("verse was great but chorus fell flat") points to section-level editing over full regeneration. Capture strategic intent ("thinking concept album") for Step 7 without redirecting.

**Iteration log.** Each song has one markdown log, the canonical memory of refinement (`references/durable-writes.md`). Append each round's attempt and the user's reaction, plus mid-elicitation anchors (narrowed dimensions, references, locked anchors, technical attempts), as they land -- not at the end -- so a compaction never loses them.

### Step 2: Gather Context

**Resume prior rounds first.** Locate the log (`scripts/feedback-log.py locate`); if it exists, surface it ("We worked on this last on {date} -- round {n}; here's what we tried and how it landed") and resume from it so the user isn't re-explaining settled ground.

**Priority 1 (always):** the style prompt -- or a description of what they asked for, to reconstruct it from. Never block on the verbatim prompt. If the opening already supplied it, confirm the package in one line and go to triage.

**Priority 2 (only as feedback demands):** lyrics (when vocal-relevant), band profile (`{band_profiles_folder}/{profile-name}.yaml`), model (only if Step 5's overflow check needs it), sliders, creativity mode, intent. Instrumental track: skip every vocal and lyric question outright. Soft gate: "That's enough to get started -- anything else before we dig in?" No profile: skip profile features and mention them for next time.

**Audio (optional).** With a render in hand, load `references/audio-analysis-scripts.md` and run what fits (`section-map.py` when the PyTorch audio tools are on and you have the render's lyrics). Skip gracefully when unavailable.

**Headless:** run `uv run scripts/parse-feedback.py` with the skill's flags; it validates the input and builds the JSON.

### Step 3: Triage Feedback

Classify with `references/feedback-triage-guide.md`:

| Type | Signal | Example | Route |
|------|--------|---------|-------|
| **Clear** | Specific, actionable problem | "Guitar is too loud," "I need a bridge" | Step 4a |
| **Positive** | Likes result, wants to evolve/lock in | "Great! Can we try a darker version?" | Step 4b |
| **Vague** | Knows something is off, can't articulate | "It just doesn't feel right" | Step 4c |
| **Contradictory** | Wants conflicting things | "More energetic but also more chill" | Step 4d |
| **Technical** | Audio quality, artifacts, glitches | "Weird glitch," "Vocals sound robotic" | Step 4e |

With a prior log, narrow triage to the dimensions still open. Mixed feedback: handle clear and technical first -- resolving concrete issues often clarifies vague ones; for 3+ types, outline the plan. **Headless:** use `pre_categorized` from parse-feedback when present; otherwise triage with the guide and record the inferred type in `decision_log`.

### Step 4a: Direct Mapping (Clear)

Load `references/suno-parameter-map.md` (and `references/model-controls.md` when a v6 control, Voice or Custom Model is in play) and map the complaint to style wording, exclusions, sliders, lyric structure and metatags. Explain each move concretely ("To reduce guitar prominence, I'd add 'subtle guitar, background acoustic' and exclude 'no heavy guitar, no guitar solo'"). Go to Step 5.

### Step 4b: Positive Refinement (Positive)

Lead with the win, not a manufactured problem. **Satisfied, no evolution ask:** celebrate and offer to bank the winning settings to the band profile -- don't push "change one thing" on someone who's happy; go to Step 7. **Wants to evolve:** ask what to keep vs. push further, anchor the rest, go to Step 5.

### Step 4c: Guided Elicitation (Vague)

Narrow from broad dimensions to a concrete anchor using the techniques in `references/feedback-triage-guide.md`, starting wherever the user's awareness already is. Zero awareness ("all of it is off") goes straight to a reference: "Point me at anything that sounds like what you wanted -- a song, an artist, a movie scene, or just a feeling." If 3-4 questions don't converge, offer 2-3 contrasting variants plus one creative wild card, so elicitation becomes selection. Summarize and confirm before Step 5.

### Step 4d: First Principles Reset (Contradictory)

First check for dynamic contrast: "It sounds like you might want quiet verses building to powerful choruses -- is that it?" If yes, route to section-specific metatags (`[Energy: Low]` verse, `[Energy: High]` chorus). If genuinely contradictory, acknowledge the tension without judgment and ask: "If you could only keep ONE thing about this song exactly as it is, what would it be?" Rebuild from that anchor one dimension at a time, reframing leftover contradictions as structural insights. Non-convergence: the 4c variants fallback. Go to Step 5.

### Step 4e: Technical Resolution (Technical)

Set expectations: "Audio artifacts are usually specific to a particular generation, not the prompt itself." Route each issue through `references/technical-resolution.md`; v6 vocal symptoms through `references/model-controls.md`; deeper listening analysis through `references/gemini-audio-analysis.md`. Gate every editor or Studio path on `{suno_tier}` (ask only when unset): Replace Section and stems are Pro and Premier, Studio is Premier-only, and Free relies on regeneration. **Dual-path issues** (e.g. "robotic vocals"): send the prompt-fixable part to Step 5 alongside the technical fix. Then Step 5, or Step 6 for a pure regeneration/editor recommendation.

### Step 5: Map to Adjustments

Translate the findings into dimensions for `uv run scripts/map-adjustments.py` (e.g. "vocals feel too polished" -> `{"dimension": "vocals", "direction": "too_polished"}`), passing `--style-prompt`, `--model` and `tier` from `{suno_tier}` when known so overflow and free-tier slider limits surface as data. Refine its baseline with judgment from the full context (band profile, intent, Step 1's creative context).

**Effectiveness:** reason against the iteration log -- don't re-recommend a move that failed; lean on one that worked. With search tools, check descriptors against current Suno behavior -- models evolve.

**Recommendations, across every relevant dimension:**
- **Style prompt:** add (strongest descriptors in the first ~200-character critical zone), remove, reorder.
- **Exclusions:** add 2-3 specific items, or remove.
- **Sliders (paid tiers):** Weirdness / Style Influence direction and magnitude, per section when the feedback is section-specific. Respect the structural Weirdness ceiling in the parameter map's slider guide.
- **Lyrics**, as a Lyric Transformer adjustment spec (`references/output-template.md`).
- **Model suggestion** when the issue maps to a model's known strengths, and **post-generation editing** where it applies.

**Check before presenting.** Run the final style prompt and exclusions through the suno-style-prompt-builder skill's `scripts/validate-prompt.py` (limits, triggers; pass `--model`) and `scripts/map-adjustments.py --check-final` (descriptors an exclusion cancels), and fix what they flag. Whether sliders contradict the prompt, and whether a change risks a liked element, stays your judgment.

**Band profile** (only with a profile in play; commands in `references/durable-writes.md`): append this round's `generation_history` snapshot through the suno-band-profile-manager skill's `scripts/apply-profile.py` (capped at 10), never by hand-editing YAML.

### Step 6: Present Recommendations

Open with a vivid before/after ("Right now: arena rock with polished vocals. Target: coffee-shop acoustic, rawer and intimate"). Load `references/output-template.md` for the template and the "What Changed and Why" micro-diff; omit sections that don't apply. Comparing generations: what each does well or poorly, what to carry forward, which changes mattered most. Ask "Does this capture what you're after?" and loop back if needed.

### Step 7: Handoff

After approval, offer next steps (outcomes first, skill names in parentheses): an updated style prompt (`suno-style-prompt-builder --headless:refine`) and/or reworked lyrics (`suno-lyric-transformer --headless:refine`) -- independent artifacts, so both can run in parallel. If the feedback revealed a preference that holds across songs (not one-song), offer it as a `generation_learnings` entry and write it only on a yes. Encourage returning after trying the new version. Then run `{workflow.on_complete}` if it is non-empty.