Survey

Survey

Use this skill when the job is discovering the landscape before committing to a plan.

survey stays portable by doing four things well:

1. freeze one bounded research question,
2. run the same 4 research lanes every time,
3. save reusable .survey/{slug}/ artifacts with fixed headings,
4. validate the artifact contract before handing off to planning or execution.

Read these support docs before running unfamiliar survey work:

• references/evidence-recovery-ladder.md
• references/platform-adapter-and-artifact-contract.md
• references/output-templates-and-validator.md
• references/keyword-sweep-and-relevance-rescue.md
• references/gh-search-empty-lane-recovery-playbook.md

When to use this skill

• The user asks what exists, what people actually use, or what the current solution landscape looks like.
• A feature, workflow, tooling choice, or operational pain needs context before planning or implementation.
• The topic spans multiple platforms or vendors and needs a vendor-neutral comparison.
• Repo maintenance needs one bounded research pass before rewriting a skill, SOP, or reusable workflow.
• The right next step depends on understanding workarounds, repeated complaints, and structural gaps rather than writing code immediately.

When not to use this skill

• The solution is already known and the user wants implementation now → implement or route to the execution skill directly.
• The task is a small bug fix, narrow code change, or single-file edit → do not force a survey first.
• The user needs an architecture plan, task plan, or immutable spec more than market/workflow discovery → plan, jeo, or ralph.
• The request is mainly a live browse-and-click task → use a browser/operator skill instead of pretending the work is a survey.

Artifact contract

Keep the output package stable:

.survey/{slug}/
├── triage.md
├── context.md
├── solutions.md
└── platform-map.md    # required for agent/tooling/platform topics

Required meanings:

• triage.md = problem, audience, why now
• context.md = workflow context, affected users, workarounds, adjacent problems, user voices
• solutions.md = solution list, categories, actual behavior, frequency, gaps, contradictions, key insight
• platform-map.md = settings, rules, hooks, platform gaps normalized across Claude / Codex / Gemini when relevant

Do not invent alternate filenames or free-form artifact shapes unless the user explicitly asks. Use python3 .agent-skills/survey/scripts/validate_survey_artifacts.py <path> after writing files whenever the survey output is meant to be reusable.

Instructions

Step 1: Classify one primary survey mode

Normalize the request before researching:

survey_run:
  primary_mode: market-landscape | workflow-landscape | repo-maintenance | platform-comparison
  scope: narrow | medium | broad
  evidence_floor: primary-pages-first | indexed-snippets-allowed | thin-evidence-ok
  output_language: repo-default | user-language
  needs_platform_map: true | false
  reuse_existing: true | false | unknown

Mode guide:

• market-landscape → products, categories, competitors, packaging, complaints
• workflow-landscape → how people do the job now, workarounds, operational rituals
• repo-maintenance → bounded research to improve an existing skill, SOP, or reusable workflow
• platform-comparison → normalize Claude / Codex / Gemini differences into settings, rules, hooks

Choose one primary mode even if the topic touches more than one.

Step 2: Freeze the evidence contract

Before searching, make the rules explicit:

• search broadly in English unless the user requires another language
• write artifacts in the repo default or user language
• keep claims source-backed
• label downgraded evidence clearly: direct page retrieval, indexed snippet, browser-rendered indexed snippet, feed recovery, or thin evidence
• keep the task in research mode only

Use the cheap-first recovery order from references/evidence-recovery-ladder.md:

1. direct primary-page retrieval
2. stable official substitution
3. feed recovery
4. browser-rendered retrieval
5. indexed snippets
6. thin-evidence stop

Step 3: Triage the request and check reuse

Parse:

• what — the pain point, idea, or capability to survey
• who — who feels it or operates the workflow
• why — why it matters now

Then check whether .survey/{slug}/triage.md already exists.

• If it exists and the user is present, ask whether to reuse or overwrite.
• In unattended loops, reuse when the existing artifact still matches the same question; overwrite only when the scope has clearly changed.

Write triage.md with:

• # Triage
• - Problem:
• - Audience:
• - Why now:

Step 4: Run the 4 lanes in parallel

Keep the lanes separate even if one is thinner.

Lane A — Context

Return:

• ## Workflow Context
• ## Affected Users
• ## Current Workarounds
• ## Adjacent Problems
• ## User Voices

Lane B — Solutions

Return:

• ## Solutions
• ## Frequency Ranking
• ## Categories
• ## Curated Sources

Lane C — Actual behavior

Return:

• ## What People Actually Use
• ## Common Workarounds
• ## Pain Points With Current Solutions
• ## Sources

Lane D — Alternatives or platform map

Default mode:

• JTBD alternatives
• indirect substitutes
• cross-industry parallels

For agent/tooling/platform topics, replace that with:

• ## Settings
• ## Rules
• ## Hooks
• ## Platform Gaps

Use settings / rules / hooks as the common layer whenever Claude / Codex / Gemini differences are relevant.

Step 4.5: Apply a relevance gate for repo-maintenance surveys

When primary_mode: repo-maintenance, do not trust keyword hits at face value.

Run a compact gate before writing final recommendations:

• Positive signals (keep): clear relation to the target capability, recent maintenance, explicit license, concrete docs/examples.
• Negative signals (drop or mark risk): spam-like description, irrelevant domain despite keyword match, assessment/homework-only repos, stale/archived repos without strong justification, missing basic metadata, or unknown license without explicit justification.
• Metadata minimum: capture license, pushed_at, archived, open_issues, forks, and one-line fit rationale for every candidate you keep. If first-pass metadata returns null/unknown license (for example GraphQL licenseInfo), retry once via GitHub REST (gh api repos/<owner>/<repo> --jq .license.spdx_id) before classifying unknown-license. Unknown/missing license after fallback should be excluded by default unless a concrete exception rationale is documented. If open_issues/forks are unavailable from the first pass, hydrate once via gh api repos/<owner>/<repo> --jq '{open_issues: .open_issues_count, forks: .forks_count}' and record retrieval provenance.
• Freshness floor (recommendation-grade keep list): exclude candidates whose latest pushed_at is older than 24 months by default. Keep stale candidates only with explicit exception rationale and risk note.

If search/extract tooling is degraded, fallback to direct GitHub API retrieval and mark provenance/risk explicitly instead of pretending confidence.

Step 4.6: Hourly candidate sweep (repo-maintenance cron loops)

When the survey is part of a recurring skill-maintenance loop, run one explicit keyword sweep before final recommendations.

Required keyword families:

• agentic ai skill
• web frontend skill
• web backend skill
• cli open source skill
• game development skill

Execution rules: