run-survey — Claude Code command: what it does, how to install
run-survey orchestrates customer surveys with target sampling, structured question banks, and distribution steps.
Apache-2.0 ★ 450 updated 2026-04-03
.claude/commands/run-survey.mdWhat run-survey does
This command sets up end-to-end customer surveys across specific segments. It structures the initial brief, constructs questions with branching logic, manages distribution lists, and tracks fielding progress.
The process logs plan schemas into .claude/plans/plan-<timestamp>.json with clear dependency trees and error handling. It coordinates specialized agents like research-lead and cs-analyst, enforcing a default retry limit of 2 for delivery failures before triggering escalations.
What it helps with
- orchestrate targeted user research surveys with specific goals
- generate branching question banks with recommended scales
- build distribution plans across email, in-app, or CS channels
- record execution blueprints in plan JSON files for auditing
Example prompts for the agent
- /customer-feedback-orchestration:run-survey --audience "admins" --goal adoption --channels "email,in-app" --deadline 2025-12-15
- /customer-feedback-orchestration:run-survey --audience "champions" --goal satisfaction --channels "community" --sample_size 150
- /customer-feedback-orchestration:run-survey --audience "exec sponsors" --goal "roadmap validation" --channels "CS-led" --deadline 2026-01-30
How to install run-survey
Manually: put the files in place
.claude/commands/run-survey.mdCall it with /run-survey. For all projects use ~/.claude/commands/
Manually: put the files in place
~/.codex/prompts/run-survey.mdCall it with /prompts:run-survey. Codex marks this format deprecated in favour of skills
Manually: put the files in place
.github/prompts/run-survey.prompt.mdManually: put the files in place
.gemini/commands/run-survey.tomlGemini stores commands as TOML: the prompt text goes into the prompt field
Questions about run-survey
How to install run-survey in Claude Code?
Place the command specification file at .claude/commands/run-survey.md.
What does run-survey do?
It manages survey preparation from brief assembly and question design to sampling, tracking, and handoff to feedback synthesis.
Which parameters are supported by run-survey?
It accepts audience, goal, channels, and deadline, alongside optional sample_size and incentive options.
Source text
run-survey.md · Apache-2.0
--- name: run-survey description: Launches customer surveys with sampling plans, question sets, and automation hooks. usage: /customer-feedback-orchestration:run-survey --audience "admins" --goal adoption --channels "email,in-app" --deadline 2025-12-15 --- # Command: run-survey ## Inputs - **audience** – persona or segment target (admins, champions, exec sponsors). - **goal** – objective (adoption, roadmap validation, satisfaction, messaging test). - **channels** – comma-separated distribution methods (email, in-app, community, CS-led). - **deadline** – fielding end date or fixed duration. - **incentive** – optional reward description or budget. - **sample_size** – desired number of responses (numeric). ### GTM Agents Pattern & Plan Checklist > Mirrors GTM Agents orchestrator blueprint @puerto/plugins/orchestrator/README.md#112-325. - **Pattern selection**: Survey orchestration typically runs **pipeline** (brief → question design → sampling → monitoring → handoff). If question design + sampling prep run in parallel, note a **diamond** block with merge gate in the plan header. - **Plan schema**: Save `.claude/plans/plan-<timestamp>.json` capturing audience, goals, sampling logic, dependency graph (legal, CS, research ops), error handling, and success metrics (response rate, completion %, demographic balance). - **Tool hooks**: Reference `docs/gtm-essentials.md` stack—Serena for MAP automation diffs, Context7 for research SOPs + historic surveys, Sequential Thinking for pre/post-readouts, Playwright for survey QA. - **Guardrails**: Default retry limit = 2 for distribution/QA failures; escalation ladder = Research Lead → Customer Marketing → Exec sponsor. - **Review**: Run `docs/usage-guide.md#orchestration-best-practices-puerto-parity` before launch to confirm dependencies, approvals, deliverables. ## Workflow 1. **Brief Assembly** – capture goals, personas, hypotheses, and stakeholder approvals. 2. **Question Design** – generate question bank with logic, scales, and branching recommendations. 3. **Sampling & Distribution** – build target lists, dedupe suppression lists, schedule sends. 4. **Monitoring** – track response rates, data quality, and audience balance; trigger boosts if needed. 5. **Handoff** – package clean dataset + metadata for `synthesize-feedback` command. ## Outputs - Survey plan (audience, sample, channels, incentive, timeline). - Question set with logic map and translation/localization notes. - Distribution checklist + automation steps for MAP/CS tooling. - Plan JSON entry stored/updated in `.claude/plans` for audit trail. ## Agent/Skill Invocations - `research-lead` – validates methodology and question quality. - `cs-analyst` – ensures sampling + data integrity. - `survey-design` skill – provides templates and guardrails. - `stakeholder-ops` skill – outlines approvals + comms. ## GTM Agents Safeguards - **Fallback agents**: document substitutes (e.g., CS Analyst covering Research Lead) when leads unavailable. - **Escalation triggers**: if response rate misses guardrail twice or sampling bias detected, escalate via GTM Agents rip-cord and log corrective actions in plan JSON. - **Plan maintenance**: update plan JSON/change log when audiences, question sets, or tooling stacks change to preserve audit parity. ---
© gtmagents · Apache-2.0 · gtmagents/gtm-agents