SKILL.md · 24000
qualifiers (skip these)
- Survey at the end of its scheduled window — natural tail-off in responses; not a regression. Check
schedule.end_datebefore flagging. - NPS / CSAT drift on < 30 responses in the recent window — sample too small to trust; memory entry only.
- Themes evenly split between positive and negative — they cancel each other; no single direction to surface.
- Theme matching an
addressed:scratchpad entry — the team already saw it and acted; re-filing wastes inbox space. - One-off rant or off-topic response — a single user typing "AAAA" or quoting song lyrics isn't signal. Themes need ≥ 3 distinct respondents.
- Internal test / placeholder responses —
TEST,TEST FEEDBACK DELETE!,qwe,asdf, single-character submissions, repeated submissions from the survey author or the host org's own users. These are endemic on real projects and will skew theme counts if you don't strip them. AWHERE length(response) > 5 AND lower(response) NOT IN ('test', 'qwe', 'asdf')guard plus anemail NOT LIKE '%@<host_org_domain>%'person-property filter catches most of it. - Survey paused or in draft — not user-facing right now; check
archived/ status /start_datebefore treating zero responses as a regression. - PII or sensitive content in responses — never put verbatim PII in a report. Quote the themed claim, not the raw text, if responses contain personal data.
When in doubt, write a memory entry instead of filing a report.
MCP tools
Direct calls (read-only):
surveys-global-stats— project-wide aggregate. Start here every cold start; cheap sanity check on overall survey health before any per-survey work.survey-stats— per-survey response statistics:shown/dismissed/sentcounts, unique respondents, conversion rates, timing. Date-filterable.survey-get— full survey config for a candidate: questions (with ids and types),type(popover / widget / api — affects howsurvey shownsemantics read), targeting (linked_flag_id/targeting_flag_id/linked_insight_id/conditions), schedule (start_date,end_date), iteration config,updated_at. Read this before drawing conclusions about score changes — question wording changes invalidate trend comparisons.surveys-get-all— last-resort discovery. Each survey object is 30–50 KB and busy projects have 100+ active surveys; calling this withlimit > 5will blow your token budget. Prefersurveys-global-stats+ anexecute-sqlranking query (see "Get oriented" above) to find the candidate set, thensurvey-getper id. Usesurveys-get-all {"search": "..."}if you need to resolve a name from a memory entry.execute-sqlagainstevents— for raw response analysis (rating trends, theme aggregation). The property reference, the dual response-key coalesce, and the$survey_submission_iddedupe SQL are all inreferences/response-querying.md.read-data-schema event_property_values— sample response values to confirm property keys exist and have the shape you expect before running heavy aggregations.query-trends— confirmsurvey shown/survey sentvolume trends with weekly comparisons. Cheaper than a full SQL aggregation when you just need the shape.advanced-activity-logs-list— correlate themes / score drops with recent product changes.inbox-reports-list/inbox-reports-retrieve— the reports already in the inbox; check before authoring so you edit instead of duplicating (ordering=-updated_at).inbox-report-artefacts-list— a comparable report's artefact log, where the routedsuggested_reviewerslive (the report record doesn't expose them) — reviewer precedent.scout-members-list— this project's members with theiruser_uuidand resolvedgithub_login. Route withuser_uuidwhengithub_loginis null. The org-scoped resolver tools are not available in a scout run.
Harness-level:
scout-project-profile-get/scout-scratchpad-search/scout-runs-list/scout-runs-retrieve— orientation + dedupe.scout-emit-report/scout-edit-report/scout-scratchpad-remember— author a report / edit an existing one / remember.
When to stop
- No active surveys + no recent survey events → close out empty (after writing the
not-in-use:scratchpad entry). - Profile + scratchpad show a stable picture (known baselines, no recent inflection) → close out empty.
- A candidate matches a scratchpad entry with
noise:/addressed:/dedupe:key prefix → skip. - You've validated some hypotheses and filed (or edited) reports for what's solid → close out, even if there's more you could look at. Themes especially — fewer, sharper reports beat a long list of weak clusters.
"Looked but found nothing meaningful" is a real outcome.