launchdarkly-flag-qualitative-feedback-setup

Before asking any questions, present this intro message to the user (you may lightly adapt the wording, but keep the structure):

Qualitative Feedback Setup

I'll walk you through adding a feedback widget to your app in a few short steps:

1. Verify your setup — I'll check your SDK, framework, and design system.
2. Gather requirements — I'll ask a few questions about the flag, prompt text, style, and placement.
3. Verify the flag — I'll confirm or create the flag in LaunchDarkly.
4. Confirm the plan — I'll summarize what I'm going to build and ask for your approval.
5. Generate the code — I'll create the feedback utility and widget matching your project's patterns.
6. Verify — I'll make sure everything builds and is wired up correctly.

Let's get started!

Then proceed immediately to Step 1.

Before gathering requirements, verify that this project can support qualitative feedback. Run these checks in order — each is a gate.

Search for LaunchDarkly SDK imports:

• launchdarkly-js-client-sdk — vanilla JS/TS client SDK (v3.x)
• @launchdarkly/js-client-sdk — vanilla JS/TS client SDK (v4.x, renamed scoped package)
• @launchdarkly/react-sdk — React Web SDK (current; provides hooks and providers)
• launchdarkly-react-client-sdk — older React Web SDK package name (renamed to @launchdarkly/react-sdk)

Also search for SDK initialization (initialize( for v3.x, or createClient(/start( for v4.x, plus React provider signals <LDProvider, asyncWithLDProvider, or createLDReactProvider). If not found, ask the user where LDClient is initialized or accessible.

• If no LD SDK is found at all → inform the user that qualitative feedback requires a LaunchDarkly client-side SDK to be installed and initialized → STOP. Do not proceed.
• If found → continue to Check 2.

Qualitative feedback is a client-side only feature. Verify the SDK found in Check 1 is a client-side SDK. Refer to references/client-side-sdk-list.md and references/server-side-sdk-list.md for the complete lists.

If the SDK is server-side only with no client SDK present → explain that qualitative feedback requires a client-side SDK and cannot be sent from server code → STOP. Do not proceed.

If unclear, ask the user whether their SDK is client-side or server-side before continuing.

Check package.json for the exact version. The $ld:feedback event requires v3.0+ of the JavaScript/React SDK.

• If version < 3.0 → inform the user they need to upgrade before feedback can be added → STOP. Do not proceed.
• If version >= 3.0 → continue to Check 4.

Search for $ld:feedback, sendFeedback, FeedbackPopover, or Give feedback to check for existing feedback integration.

• If a sendFeedback function exists that calls client.track('$ld:feedback', ...) → reuse it. Record its import path — Step 5 will be skipped. Continue to Step 2.
• If a feedback widget exists but not the sendFeedback utility → note the widget pattern for consistency.
• If nothing found → continue normally.

After the checks above pass, gather the remaining context:

1. Find the SDK initialization. Search for:

   • initialize( from launchdarkly-js-client-sdk (v3.x)
   • createClient( / start( from @launchdarkly/js-client-sdk (v4.x)
   • <LDProvider, asyncWithLDProvider, or createLDReactProvider from the React SDK
   • How the LDClient instance is accessed (direct reference, React context, custom hook, etc.)

2. Check for observability. Search for @launchdarkly/observability and @launchdarkly/session-replay. If present, feedback can be linked to session replays.

3. Detect the UI framework and design system.

   Signal	Framework
   react, react-dom in deps	React
   vue in deps	Vue (adapt vanilla JS pattern to Vue component)
   @angular/core in deps	Angular (adapt vanilla JS pattern to Angular component)
   svelte in deps	Svelte (adapt vanilla JS pattern to Svelte component)
   None of the above	Vanilla JS/TS

   Then check for a design system or component library:

   • @mui/material, @emotion/react → MUI
   • @chakra-ui/react → Chakra UI
   • antd → Ant Design
   • @radix-ui/* or @shadcn/* → Radix/shadcn
   • tailwindcss in deps or tailwind.config.* → Tailwind CSS
   • bootstrap or react-bootstrap → Bootstrap
   • Custom design system → look for a components/ directory with shared primitives (Button, Modal, Popover, etc.)

   If a design system is detected, use its primitives (Button, Popover, TextArea, IconButton) instead of the inline-styled template component. The template components in references/ are a starting point — always adapt them to match the project's existing patterns.

STOP. Do not proceed to Step 3 until you have answers to ALL of the following. Check the user's request — if it already answers a question, you don't need to re-ask it. For anything not covered, ask the user and wait for their response before continuing.

Ask only one question at a time. Wait for the user's answer before asking the next. Do not list multiple questions in one message. When presenting options, use AskUserQuestion to render interactive selectors in the agent console. For free-text questions (like prompt text), ask as a normal text message.

1. Which feature/flag? Feedback is always tied to a flag key. Search the codebase for existing flag keys, then use AskUserQuestion with the discovered flags as options (plus a "Create a new flag" option). If no flags are found, ask as a text question.
2. What question do you want to ask the user? This becomes the prompt text shown in the feedback widget (e.g., "How do you feel about this view?" or "Did this work as expected?"). Ask this as a normal text message since it requires free-text input.
3. What type of feedback? Use AskUserQuestion with header "Type" and these options:
   • label: "Sentiment + text (Recommended)", description: "Sentiment buttons with a text area for comments, in a popover"
   • label: "Sentiment only", description: "One-click sentiment buttons inline — no popover, no text input"
   • label: "Text only", description: "Just a text area for written feedback in a popover, no sentiment buttons" If the user selects "Sentiment + text" or "Sentiment only", follow up with AskUserQuestion header "Icons" and these options:
   • label: "Thumbs up / down", description: "Two buttons: positive / negative"
   • label: "Smiley faces", description: "Three buttons: positive / neutral / negative"
4. Where should the feedback widget go? Before asking, search the codebase for pages, routes, or main components. Then use AskUserQuestion with header "Placement" and 2–4 concrete placement options that make sense for this repo (e.g., "Next to the results heading on the Simulator page", "In the page header", "Below the main content area"). Prefer page-level placement — don't bury feedback in small sub-components unless it's workflow-specific confirmation.

Use get-flag to confirm the target flag exists and is configured for client-side use.

• If the flag doesn't exist, use create-flag (or direct the user to the flag create skill).
• If the flag exists but doesn't have client-side SDK availability enabled, inform the user they need to enable it in the flag's Advanced Controls section.
• If the flag was created or verified, provide the user with a direct link to the flag in the LaunchDarkly dashboard.
• Optionally use update-flag-settings to add a feedback tag.

STOP. Do not write any code until the user explicitly confirms the plan. This applies every time — including when the user provides all details upfront, when re-running for a second flag in the same conversation, or when reusing existing utilities. A detailed user request is not implicit approval.

Summarize the planned changes using future tense (e.g., "Files to create", "Files to modify") — no code has been written yet:

• Flag key and whether it exists or needs creation
• The sendFeedback utility: where it will live, whether it will be reused from a prior step, and whether it includes session replay
• The feedback widget: component name, UI style, placement location
• Which files will be created or modified

Then use AskUserQuestion with header "Confirm" and these options:

• label: "Looks good", description: "Proceed with the plan as described"
• label: "Change something", description: "I want to adjust part of the plan before you start"

If the user selects "Change something" (or provides custom input), address their feedback and re-present the updated plan with the same confirmation prompt. Do not proceed to Step 5 until the user selects "Looks good".

If Check 4 found an existing sendFeedback function, skip this step entirely. Use the recorded import path from that check and proceed directly to Step 6.

This is the core integration. Create a utility function that sends the $ld:feedback tracking event.

Start from the template in references/sendFeedback.ts. For JavaScript projects, adapt by removing type annotations.

The essential contract:

client.track('$ld:feedback', {
    feedback_answer: string,  // required — the user's written feedback
    flag_key: string,         // required — the flag this feedback is about
    sentiment: "positive" | "neutral" | "negative",  // defaults to "neutral"
    feedback_prompt: string,  // optional — the question shown to the user
    o11y_session_id: string,  // optional — links to session replay
    custom_properties: Record<string, any>,  // optional — extra metadata to attach to the feedback event
});
client.flush();

Key decisions:

• Match the LDClient type import to the project's SDK version: launchdarkly-js-client-sdk for v3.x, @launchdarkly/js-client-sdk for v4.x. The templates import from launchdarkly-js-client-sdk — update it if the project is on v4. (The client.track / client.flush calls are the same across both.)
• If @launchdarkly/session-replay is in the project, include the session ID via LDRecord.getSession()?.sessionSecureID. If not, remove the session replay import and o11y_session_id logic from the template.
• Place the utility where the project keeps its LD-related code (alongside existing flag helpers, in a lib/ or utils/ directory, etc.)
• Export the LDFeedbackSentiment type if using TypeScript

Verification: After creating the file, search the codebase to confirm it exists and contains the expected content — a sendFeedback export that calls client.track('$ld:feedback', ...) followed by client.flush(). If not found, fix before proceeding.

Build the UI using the project's existing design system and component patterns.

Start from the appropriate template in references/. For JavaScript projects, adapt by removing type annotations.

• Sentiment + text → PopoverFeedback.tsx with icons="thumbs" or icons="smileys"
• Text only → PopoverFeedback.tsx with icons="none"
• Sentiment only → InlineFeedback.tsx with icons="thumbs" or icons="smileys"

These templates use inline styles and SVG icons so they work without any CSS framework or icon library. When the project has a design system, replace template elements with its primitives:

Always use fill="currentColor" (not hardcoded hex colors) in SVG icons so they inherit the parent's text color.

Do NOT use find-and-replace for PROMPT_TO_REPLACE. Instead, make prompt a string prop on the component. This makes the widget reusable across flags without code duplication. Pass the user's prompt text from Step 2 as a prop when rendering.

Standard UX pattern (follow this regardless of design system):

• A trigger button with a speech-bubble icon and "Give feedback" label (for popover styles)
• A popover that opens on click, containing:
  • A text area with the prompt text as its placeholder
  • Sentiment controls matching the style chosen in Step 2:
    • Thumbs up / thumbs down — two icon buttons toggling positive/negative
    • Smiley-face scale — three icon buttons for positive (smile), neutral (meh), negative (frown)
    • Text-only — no sentiment buttons; omit the sentiment field from sendFeedback
  • A submit button
• After submission: Track a submitted state. Replace the widget with a "Thanks for your feedback!" confirmation message. Do not just close the popover silently — the user needs to know their feedback was received.
• Quick thumbs / inline smileys (no popover): inline prompt text with sentiment buttons; sends feedback immediately on click with no text input. After click, replace with a thank-you message.

Placement: Use the location chosen in Step 2. Do not add multiple feedback entry points on the same screen.

After building the widget, add it to the target location from Step 2:

1. Find the target file. Search the codebase for the page or component matching the placement chosen in Step 2. State the file path you found and ask the user to confirm it's correct before modifying it. If they say no, ask for clarification and try again.
2. Import and render. Import the feedback component into the confirmed target file. Render it and pass the required props: flagKey string and prompt string. For React SDK projects, the component should use the useLDClient() hook internally rather than accepting ldClient as a prop.
3. Verification: Search the target component to confirm it imports and renders the feedback component with the required props (flagKey, prompt). If the import or render is missing, fix before proceeding.

React — Start from the template, then adapt to the project's design system using the table above.

Vanilla JS/TS — Wire up DOM elements to the sendFeedback function:

submitButton.addEventListener('click', () => {
    sendFeedback(client, flagKey, feedbackInput.value, selectedSentiment, promptText);
});

Vue / Angular / Svelte — Translate the React component pattern into the framework's idiom. The sendFeedback function is framework-agnostic; only the UI wrapper changes.

Pre-condition check: Before verifying, confirm that all prior steps produced their expected outputs:

• (a) The sendFeedback utility file exists (or an existing one was reused from Check 4).
• (b) The feedback widget component file exists.
• (c) The widget is imported and rendered in the target location with the required props.

If any are missing, go back and complete the relevant step before proceeding.

Walk the user through validation step by step:

1. Run the build. Execute the project's build or lint command. If it fails, fix the errors before continuing.
2. Start the app locally. Ask the user to run their dev server (or run it yourself if you can). Confirm it starts without errors.
3. Navigate to the feedback location. Tell the user to open the page where the widget was placed. Ask them to confirm the "Give feedback" button (or inline thumbs) is visible and styled correctly.
4. Submit test feedback. Walk the user through: click the trigger → enter test text → select a sentiment → click Send. Ask them to open the browser's Network tab and confirm a POST to the LaunchDarkly events endpoint fired containing $ld:feedback.
5. Check the dashboard. Provide a direct link to the flag's Feedback tab in the LaunchDarkly dashboard. Tell the user to wait ~1 minute and then refresh — their test feedback should appear.
6. Session replay (if applicable). If @launchdarkly/session-replay is configured, ask the user to check for a Replay button next to the feedback entry in the dashboard.

After the user confirms everything works, mention:

• They can subscribe Slack channels to receive feedback notifications: go to the flag's Feedback tab → Subscribe → select Slack channels (requires the LaunchDarkly Slack app).
• Provide the direct link to the flag's Feedback tab so they can bookmark it for monitoring.