survey（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

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, and one-line fit rationale for every candidate you keep. Unknown/missing license should be excluded by default unless a concrete exception rationale is documented.
• 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:

• Keep the raw keyword scan as discovery evidence (usually browser-rendered retrieval when done through search pages).
• Apply the Step 4.5 relevance gate before keeping any candidate.
• For each kept candidate, record at least: license, pushed_at/updated, archived, and one-line fit rationale.
• For recommendation-grade keeps, apply a default freshness floor (pushed_at within the last 24 months). If kept despite staleness, document exception rationale and explicit risk.
• Apply a default signal floor for recommendation-grade keeps: require at least one traction signal (for example, stars >= 3, or explicit maintainer/community adoption evidence with rationale). Keep broad discovery evidence even when the recommendation-grade list is stricter.
• For the agentic ai skill lane, treat generic personal catch-all repositories named only like */skills as low-fit by default unless there is explicit workflow documentation + traction; keep them in raw evidence but do not promote to TOP recommendations without an exception rationale.
• If direct web search/extract tooling fails (auth/rate-limit/transport), switch to GitHub-native retrieval (gh search + gh api or gh repo view) and label provenance clearly.
• If keyword hits are noisy or sparse, run lane-specific recovery templates from references/keyword-sweep-and-relevance-rescue.md before finalizing recommendations.
• Use objective recovery triggers after the primary query (raw_count < 8, kept_count == 0, or zero_star_raw/raw_count >= 0.70) so lane rescue is deterministic in unattended cron loops.
• If a lane still has raw_count == 0 after stage-1 recovery, run exactly one documented stage-2 recovery query for that lane before finalizing lane_status.
• Recommendation thresholds after relevance gate: aim for at least 1 keep per lane where feasible, and cli open source skill should target 3+ kept entries for spotlight quality.
• Emit explicit lane-level status in markdown (lane_status: pass|degraded). If thresholds are missed, keep evidence and report degraded_causes with compact taxonomy (license, stale, low-fit, archived, low-signal) plus examples/counts.
• Alongside lane_status, include compact lane-health metrics (kept_count, raw_count, median_stars_raw, zero_star_raw) so reviewers can track quality drift across hourly runs.

Reference: references/keyword-sweep-and-relevance-rescue.md

Step 5: Synthesize the artifacts

Keep the written files compact and schema-stable.

• Use the exact markdown templates in references/output-templates-and-validator.md.
• Keep the required filenames and headings unchanged.
• Preserve honest provenance labels when evidence is weak.
• For platform topics, make platform-map.md explicit instead of burying platform differences in solutions.md.
• For repo-maintenance, show why each kept candidate passed the relevance gate (fit + metadata + risk).

Step 6: Validate the artifact contract

Run the validator after writing the files:

python3 .agent-skills/survey/scripts/validate_survey_artifacts.py .survey/<slug>
python3 .agent-skills/survey/scripts/validate_survey_artifacts.py .survey/<slug> --platform-topic

Use --platform-topic when platform-map.md is required. If provenance labels matter for the run, also use:

python3 .agent-skills/survey/scripts/validate_survey_artifacts.py .survey/<slug> --require-provenance

If the validator fails, fix the artifact files before handing off to planning or implementation.

Step 7: End with a factual survey summary

Return a short summary only after files are written and validated:

• ## Survey complete: {slug}
• 1-2 context bullets including the main workaround
• 1-2 solution-landscape bullets including the key insight and key gap
• file list for the generated artifacts

Do not slide into planning or implementation unless the user explicitly asks for the next step.

Output rules

• Facts first, recommendations second only if requested.
• One bounded question per survey artifact.
• Keep solution names deduplicated.
• Preserve evidence labels when sources are weak or indirect.
• Keep the output artifact schema identical across platforms.
• Route architecture/planning/execution work outward once the survey is done.

Examples

Example 1: Repo-maintenance survey

Input

survey which existing skill in this repo is the best bounded maintenance target next

Good output direction

• mode: repo-maintenance
• checks existing .survey/{slug} first
• uses repo-local graph/wiki evidence plus any necessary primary-source retrieval
• writes triage/context/solutions and a factual summary
• validates the output folder before any skill rewrite starts

Example 2: Platform comparison

Input

survey how Claude Code, Codex, and Gemini CLI differ for hooks, approvals, and research workers

Good output direction

• mode: platform-comparison
• writes platform-map.md
• normalizes differences into settings, rules, hooks
• validates with --platform-topic
• records portability gaps without treating vendor-specific features as the artifact contract

Best practices

1. Keep the front door small: classify mode, freeze evidence rules, run the 4 lanes, validate, and save the artifacts.
2. Push slow-changing retrieval/platform/template detail into references instead of bloating the main skill.
3. Prefer direct primary sources, but label every downgrade honestly.
4. Preserve the same artifact filenames and headings across Claude / Codex / Gemini runs.
5. If evidence is thin, narrow the claim instead of bluffing certainty.
6. Treat hook systems as accelerators around the validator, not replacements for checked-in artifact rules.

References

• references/evidence-recovery-ladder.md — fallback ladder and provenance labels for weak search/extract environments
• references/platform-adapter-and-artifact-contract.md — portability rules for settings, rules, hooks, and identical artifact output across platforms
• references/output-templates-and-validator.md — exact file templates plus validator usage for .survey/{slug}/
• references/keyword-sweep-and-relevance-rescue.md — required five-keyword sweep and noisy-query rescue gate for recurring repo-maintenance loops
• scripts/validate_survey_artifacts.py — artifact-contract validator for survey output folders