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:

• Use a recency-first query window for hourly runs: default to pushed within the last 24h~7d, then widen only through documented recovery stages.
• 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, open_issues, forks, 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.
• Apply a negation-aware intent guard before recommendation-grade promotion: when lane-intent token overlap appears only inside explicit negation phrases (for example no cli, without cli, not a cli, non-cli), classify as low-fit by default, keep in raw discovery evidence, and require an explicit exception rationale to promote.
• 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.
• Guard for GH CLI JSON-field drift in unattended loops: prefer gh search repos --json fullName,... (or compose identity from owner + name) instead of unsupported fields like nameWithOwner; if a field mismatch occurs, preserve stderr in evidence and rerun with supported fields before final lane status.
• Guard for gh search repos empty-success payloads in unattended loops: if exit code is 0 but payload is unexpectedly [] (or trivially empty) for a known-populated probe/query, treat this as degraded transport and rerun via GitHub REST search before final lane status.
• For the REST fallback path, prefer endpoint form gh api "search/repositories?q=<query>&per_page=<n>&sort=updated&order=desc" and capture stderr artifacts; avoid relying on incompatible forms that can 404 in some environments.
• In markdown artifacts validated with --require-provenance, map GitHub search result evidence to validator-supported labels (indexed snippet for search-result listings, direct page retrieval for repo/API detail fetches) instead of ad-hoc labels like github search api.
• 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.
• Metric integrity gate (mandatory): after each recovery query selection, recompute lane metrics from the final selected result set before writing artifacts (raw_count, zero_star_raw, median_stars_raw, kept_count). Never emit impossible combinations like kept_count > raw_count.
• 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.
• For noisy lanes where raw hits exist but recommendation-grade keeps remain kept_count == 0 after stage-1 recovery, run exactly one documented stage-2 recovery query before finalizing degraded status.
• If a lane still ends with raw_count == 0 after documented recovery, set/report degraded_causes with explicit no-results (do not leave it empty).
• 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, no-results) plus examples/counts.
• When a lane remains raw_count == 0 even after the documented stage-2 recovery query, set and report degraded_causes including no-results (do not leave degraded causes empty).
• 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.
• Add a cross-lane concentration check for recommendation-grade keeps: if recommended_lane_count < 2, mark the run as single_lane_concentration: true, keep degraded-lane evidence explicit, and avoid claiming broad coverage health.
• Add a cross-lane recommendation dedup gate before final ranking: preserve raw discovery evidence unchanged, but compute a deduplicated recommendation-grade set keyed by repository identity (fullName or owner/name) and report both raw and dedup coverage metrics.

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, and deduplicate recommendation-grade repositories across lanes before final ranking while preserving raw evidence.
• 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

Evidence Recovery Ladder for survey

Use this note when a survey lane cannot rely on normal web-search or page-extract tooling.

1. Direct primary-page retrieval

Start with the canonical or most likely primary URL.

Recover at least:

• final URL / redirect target
• <title>
• meta description (if present)
• exact keyword presence for the claim you want to make

Recommended lightweight pattern:

• python3 + urllib.request
• browser-like User-Agent
• note the recovery as direct page retrieval

Good for:

• vendor docs
• standards pages
• product/use-case pages
• stable reference material

2. Stable official substitution

If a cited blog/resource URL 404s or drifts:

• prefer a durable official page that still covers the same workflow
• record that the original URL drifted
• do not pretend the substitute is the same document

Good for:

• product overview pages replacing dead announcement posts
• stable docs replacing drifted blog links

3. Structured publication fallback

If the site exposes a feed:

• check RSS / Atom autodiscovery or common feed endpoints
• recover canonical links, timestamps, and summaries
• treat feed summaries as weaker than the full page unless they include the full content

Record as:

• feed recovery
• direct page retrieval via feed-discovered URL

4. Browser-rendered retrieval

Escalate here when:

• direct fetch returns incomplete HTML
• the page is JS-rendered
• anti-bot noise hides the real content
• redirect/cookie behavior matters

Use a browser view to recover:

• visible title/snippet text
• rendered result blocks
• network/API endpoints if needed

Record as:

• browser-rendered retrieval

5. Indexed snippet recovery

Use when the primary page or social post is not directly recoverable but search results still expose useful text.

Rules:

• label explicitly as indexed snippet or browser-rendered indexed snippet
• include confidence: high, medium, or low
• use snippets for existence/topic/workflow phrasing, not as a perfect substitute for the full source

Confidence hints:

• high — URL + snippet recovered in the same run
• medium — platform/page inferred but original page not opened
• low — generic snippet with little workflow detail

6. Thin-evidence stop

If all recovery paths remain weak:

• say the evidence is thin
• preserve what was recovered
• continue the survey without inventing certainty
• downgrade the claim to a hypothesis if needed

Provenance labels

Use one of these labels in the survey artifact:

• direct page retrieval
• feed recovery
• browser-rendered retrieval
• indexed snippet
• browser-rendered indexed snippet
• thin evidence

Practical reminders

• Cheap-first escalation beats going straight to a full browser.
• Prefer primary sources over tertiary summaries when the claim matters.
• Stable official pages are often better than dead blog guesses.
• Snippets are useful, but they must stay visibly lower-confidence than direct retrieval.

GitHub-heavy survey fallback (keyword scans)

When the survey topic is mostly GitHub repositories and search reliability drops (API auth failure, secondary rate limits, noisy keyword matches): 1. Keep keyword-search evidence, but label it as browser-rendered retrieval and treat it as discovery, not final truth. 2. Re-verify shortlisted candidates via direct repo pages/API (direct page retrieval) for stars, license, archived status, and recent updates. 3. Prefer authenticated gh api retrieval when available to reduce unauthenticated rate-limit failures. 4. If one keyword surface is too noisy (common for frontend/backend/game "skill" queries), use stable seed repos that match the workflow intent and state that this is a quality filter, not keyword-only ranking. 5. If sandbox TLS trust is broken (CERTIFICATE_VERIFY_FAILED), use an unverified SSL context only for non-destructive metadata retrieval, and explicitly flag this as risk in artifacts/reports.

Keyword sweep quality rescue matrix (hourly maintenance)

When hourly runs require fixed keyword coverage (agentic ai skill, web frontend skill, web backend skill, cli open source skill, game development skill), use this matrix before selecting a candidate:

Mandatory metadata + fit rationale before proposing

For each kept candidate, record:

• license (or explicit missing-license risk)
• pushed_at
• archived
• open_issues
• forks
• one-line fit rationale tied to the exact skill scope
• if open_issues/forks are missing on first pass, hydrate once via gh api repos/<owner>/<repo> --jq '{open_issues: .open_issues_count, forks: .forks_count}'

Do not promote a candidate to TOP proposals when it fails metadata minimums unless the report labels it explicitly as risk/experimental.

GH Search Empty-Lane Recovery Playbook

Use this playbook in hourly survey runs when gh search repos returns an empty list for a mandatory lane.

Trigger

• Lane query exit code is 0 but payload is []
• Or lane has raw_count == 0 after the primary query

Mandatory recovery sequence

1. Keep original lane output as discovery evidence. 2. Run stage-1 recovery query with stars/freshness constraints. 3. If still raw_count == 0, run exactly one stage-2 query for the lane. 4. If GH search remains empty/noisy, run REST fallback:

• gh api "search/repositories?q=<query>&per_page=20&sort=updated&order=desc"

5. Recompute lane metrics from the final selected result set before writing evidence.json.

Required evidence notes

• lane_status: degraded with cause no-results when lane remains empty after documented recovery.
• transport_status note only when all five lanes are zero due to retrieval degradation.
• Provenance label must use validator-supported terms (indexed snippet, direct page retrieval, etc.).

Validation checklist

• raw_count >= kept_count
• if raw_count == 0: set zero_star_raw = 0 and median_stars_raw = 0
• run validate_survey_artifacts.py --platform-topic --require-provenance

Keyword Sweep and Relevance Rescue (Hourly Repo-Maintenance)

Use this guide when a survey run is part of recurring skill maintenance (for example, hourly cron loops).

Required keyword families (hourly maintenance loop)

Run all five keyword families before final recommendations:

1. agentic ai skill 2. web frontend skill 3. web backend skill 4. cli open source skill 5. game development skill

Keep the raw sweep output as discovery evidence.

Why this exists

Broad keyword sweeps improve recall but can produce noisy or sparse results. Without a relevance gate, low-fit repositories pollute recommendations. Without a rescue path, empty lanes can be misread as ecosystem absence.

Compact relevance gate

For each candidate you keep, capture at minimum:

• license (normalize payload shapes first: license.spdx_id, license.spdxId, license.key, license.name; if still null/unknown or empty-object like {"key":"","name":""}, enrich once with gh repo view <owner>/<repo> --json licenseInfo and then fallback to gh api repos/<owner>/<repo> --jq .license.spdx_id)
• pushed_at or updated_at
• archived
• open_issues
• forks
• one-line fit rationale
• if open_issues/forks are unavailable in first-pass metadata, hydrate once via gh api repos/<owner>/<repo> --jq '{open_issues: .open_issues_count, forks: .forks_count}'

Positive keep signals:

• Clearly related to the target capability
• Recently maintained
• Explicit license
• Concrete docs/examples

Freshness default for recommendation-grade keeps:

• Keep if pushed_at is within the last 24 months.
• Compute and record months_since_push (or equivalent age bucket) for each recommendation-grade keep candidate so stale filtering is auditable.
• Otherwise, drop by default or keep only with an explicit exception rationale and risk note.
• If a lane loses keeps primarily due to freshness, include stale in degraded_causes with a count/example in markdown.

Signal floor default for recommendation-grade keeps:

• Preserve broad discovery evidence, but do not promote low-traction candidates by default.
• Require at least one traction signal for keeps (for example, stars >= 3, or explicit maintainer/community adoption evidence with rationale).
• If a lane is sparse and a low-signal keep is still needed, document the exception rationale and risk note explicitly in markdown.

Drop or risk-mark signals:

• Keyword-only match but wrong domain
• Lane-intent token appears only in explicit negation phrases (for example no cli, without cli, not a cli, non-cli) and no exception rationale is documented
• Generic personal catch-all repos (especially */skills) without concrete workflow docs and traction
• Assessment/homework/demo-only repos with low transferability
• Archived/stale without strong reason
• Missing basic metadata or unknown license without exception note
• Spam-like or boilerplate descriptions
• CLI negation patterns (no cli, without cli, not a cli, non-cli) unless explicit exception rationale is documented

Lane-intent token-overlap gate (recommendation promotion guard):

• Build a compact lane token set (for example: agentic|ai|skill, frontend|ui|design|component, backend|api|framework|observability, cli|terminal|command, game|engine|gamedev|pipeline).
• For recommendation-grade keeps, require at least one lane-intent token (or documented synonym) in fullName or repository description.
• If no overlap, keep the repository in raw discovery evidence but classify it as low-fit for promotion decisions.
• Record at least one concrete off-topic example when this guard filters candidates, so reviewers can audit why precision improved.

Rescue path for sparse/noisy lanes

Trigger a recovery pass when any of the following is true after the primary keyword query:

• raw_count < 8
• kept_count == 0
• zero_star_raw / raw_count >= 0.70 (for raw_count > 0)
• aggregate_zero_star_ratio >= 0.50 across all five keyword lanes (cross-lane raw-quality collapse trigger)
• query transport degrades (auth/rate-limit/empty payload)

If direct web search/extract is degraded or returns mostly noise:

1. Switch to GitHub-native retrieval (gh search repos, gh api, gh repo view). 2. For gh search repos --json, prefer supported fields like fullName (or compose identity from owner + name) instead of unsupported fields such as nameWithOwner; when schema mismatch happens, persist stderr in evidence and rerun with supported fields before final lane status. 3. Guard for gh search repos empty-success payloads ([] with exit 0) using a known-populated probe/query; when triggered, mark lane retrieval as degraded and rerun via GitHub REST search endpoint form (gh api "search/repositories?q=<query>&per_page=<n>&sort=updated&order=desc"). 4. Add curated seed repositories relevant to the target capability. 5. Apply the same relevance gate to seed candidates. 6. Label provenance explicitly (direct page retrieval, browser-rendered retrieval, etc.). 7. Preserve raw discovery evidence even when all recommendation-grade keeps are filtered.

Lane-level recovery templates (hourly default)

Use these as fallback queries after the primary keyword family returns sparse/noisy matches.

Before running fallback queries, compute a rolling freshness floor once per run (24 months) and reuse it in every pushed: qualifier:

ROLLING_CUTOFF=$(python3 - <<'PY'
from datetime import datetime, timedelta
print((datetime.utcnow() - timedelta(days=730)).strftime('%Y-%m-%d'))
PY
)

Then substitute ${ROLLING_CUTOFF} in templates:

• agentic ai skill lane
• ai agent framework skills automation stars:>200 pushed:>=${ROLLING_CUTOFF}
• web frontend skill lane
• Stage 1: frontend ui component design system stars:>300 pushed:>=${ROLLING_CUTOFF}
• Stage 2 (deterministic escalation when Stage 1 keeps remain kept_count == 0 due to noisy/low-signal hits): frontend engineering workflow design system toolkit stars:>120 pushed:>=${ROLLING_CUTOFF}
• web backend skill lane
• Stage 1: backend api framework observability stars:>300 pushed:>=${ROLLING_CUTOFF}
• Stage 2 (deterministic escalation when Stage 1 still has raw_count == 0): backend developer platform api template stars:>150 pushed:>=${ROLLING_CUTOFF}
• cli open source skill lane
• command line tool developer productivity stars:>200 pushed:>=${ROLLING_CUTOFF}
• github cli terminal tool stars:>200 pushed:>=${ROLLING_CUTOFF}
• game development skill lane
• game engine tooling pipeline stars:>150 pushed:>=${ROLLING_CUTOFF}

Stage-2 escalation rule:

• If a lane remains raw_count == 0 after stage-1 recovery, run exactly one stage-2 query template for that lane before finalizing lane_status.
• For lanes that are noisy (raw hits exist but recommendation-grade keeps remain kept_count == 0 after stage-1), run exactly one stage-2 query template before finalizing degraded status.
• Keep provenance labels and apply the same relevance + metadata + signal/freshness gate to stage-2 hits.
• If raw_count == 0 after Stage 2, set degraded_causes to include no-results (alongside other causes) so empty lanes remain explicit in run reports.

Minimum recommendation thresholds (after relevance gate)

• At least 1 recommendation-grade keep per lane where feasible.
• cli open source skill lane target: 3+ kept entries for spotlight quality.
• For each lane, emit explicit lane_status in markdown: pass or degraded.
• If a lane is below threshold, keep discovery evidence and report degraded_causes using a compact taxonomy: license, stale, low-fit, archived, low-signal, no-results (include counts or concrete examples).
• If a lane still has raw_count == 0 after stage-2 recovery, include no-results explicitly (never leave degraded causes empty for degraded lanes).
• Add cross-lane concentration metrics for recommendation-grade keeps: recommended_lane_count and single_lane_concentration (true when recommended keeps are concentrated in a single lane).
• Before final ranking, compute a deduplicated recommendation-grade set keyed by repository identity (fullName or owner/name) and report both raw and dedup recommendation coverage metrics.

Open-PR first gate (hourly hard rule)

Apply this sequence at run start before any new branch/PR work:

• Query open PRs immediately (gh pr list --state open).
• If open PR count is >=1, do not create a new branch/PR in that run.
• Instead, triage existing PRs first: checks, conflict status, review state.
• If a PR is mergeable and checks are green, merge it first.
• If a PR is conflicting/duplicate, leave a blocker comment, close it, and clean its remote branch.
• Only when open PR count becomes 0 may the run create a new branch and PR.

Checks-degraded escalation (PR lifecycle guard)

Use backlog-aware handling before opening a new hourly PR:

• Sample at least the two most recent carry-forward PRs with gh pr checks before deciding mode.
• If open PR backlog is high (default threshold: >=10) and sampled carry-forward PRs show no checks reported, switch to checks-degraded mode for this run: generate artifacts + blocker report only, and do not open an additional PR.
• If backlog is below the threshold, continue normal PR creation cadence, but keep merge gating strict.
• If sampled carry-forward PRs are also DIRTY or CONFLICTING while checks are absent, keep this run in blocker-report mode and avoid same-run conflict resolution churn.

When survey artifacts are valid but GitHub reports no checks reported on the current PR branch:

• Treat as hard blocker for merge in unattended hourly runs.
• Post a PR comment with exact blocker string and remediation steps (enable required checks or re-run workflows).
• Keep this run in merge-blocked state; do not force-merge.
• Record merge_blocked_reason: no-checks-reported in the final run report.

Graphify compatibility note for unattended runs:

• graphify save-result currently requires --question and --answer; do not pass unsupported flags such as --input.
• If command contract mismatch occurs, persist stderr under the run folder and generate graphify-refined.json fallback from evidence.json so PR packaging still contains auditable knowledge artifacts.

Reporting checklist

Before final recommendations:

• [ ] All five keyword families executed
• [ ] Raw discovery evidence saved
• [ ] Relevance gate applied to kept candidates
• [ ] Metadata minimum recorded for each kept candidate
• [ ] Lane-level lane_status (pass|degraded) included in markdown summary
• [ ] For degraded lanes, degraded_causes (license|stale|low-fit|archived|low-signal|low-signal-saturation|no-results) reported with examples/counts
• [ ] Recommendation section reports both raw and deduplicated cross-lane coverage metrics
• [ ] Provenance labels present
• [ ] Risks for noisy or sparse lanes stated explicitly

Output Templates and Validator for survey

Use this note when writing or checking .survey/{slug}/ artifacts.

Required output package

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

Required headings

triage.md

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

context.md

# Context: {project name}

## Workflow Context
...

## Affected Users
| Role | Responsibility | Skill Level |
|------|----------------|-------------|
| ... | ... | ... |

## Current Workarounds
1. ...

## Adjacent Problems
- ...

## User Voices
- "..." — source

solutions.md

# Solution Landscape: {project name}

## Solution List
| Name | Approach | Strengths | Weaknesses | Notes |
|------|----------|-----------|------------|-------|
| ... | ... | ... | ... | ... |

## Categories
...

## What People Actually Use
...

## Frequency Ranking
1. ...

## Key Gaps
- ...

## Contradictions
- ...

## Key Insight
...

platform-map.md

# Platform Map: {project name}

## Settings
| Concern | Claude | Codex | Gemini | Common Layer |
|---------|--------|-------|--------|--------------|
| ... | ... | ... | ... | ... |

## Rules
| Concern | Claude / OMC | Codex / OMX | Gemini / OHMG | Common Layer |
|---------|---------------|-------------|---------------|--------------|
| ... | ... | ... | ... | ... |

## Hooks
| Lifecycle | Claude | Codex | Gemini | Common Layer |
|-----------|--------|-------|--------|--------------|
| ... | ... | ... | ... | ... |

## Platform Gaps
1. ...

Validator commands

Default survey artifact check:

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

Require platform-map.md plus its headings:

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

Require at least one survey provenance label somewhere in the artifacts:

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

Emit JSON for automation:

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

What the validator checks

• target folder exists
• required files exist
• required headings exist in triage.md, context.md, and solutions.md
• platform-map.md exists and contains Settings / Rules / Hooks / Platform Gaps when --platform-topic is used
• provenance labels appear somewhere when --require-provenance is used

Provenance labels accepted by the validator

• direct page retrieval
• feed recovery
• browser-rendered retrieval
• indexed snippet
• browser-rendered indexed snippet
• thin evidence

Scope guardrails

• The validator checks structure and basic provenance only.
• It does not score whether the research is strategically good.
• Keep strategic judgment in the survey lanes and the frozen evaluation harness, not in the script.

Run-slug guard (hourly automation)

• Always persist the current run slug once (for example .survey/LATEST_SLUG) and pass it explicitly to every generator script via environment variable or argv.
• Do not discover slug by listing .survey/ directories; mixed historical folders can silently target the wrong run and contaminate artifacts.
• After generation, verify git status --short only touches .survey/<current-slug>/ paths before proceeding to PR.

Platform Adapter and Artifact Contract for survey

Use this note when the survey topic involves agent tooling, hooks, permissions, or cross-platform orchestration.

Why this reference exists

survey must stay portable across Claude / Codex / Gemini, but those platforms do not expose identical runtime features. The durable layer is the survey artifact contract, not the platform runtime.

Common abstraction layer

Normalize vendor-specific behavior into three buckets:

• settings — model/config/project-level defaults, output mode, MCP enablement, approval defaults
• rules — allow/deny policy, instruction files, subagent boundaries, sandbox/approval posture
• hooks — pre/post/error callbacks, notification handlers, validation wrappers, lifecycle automation

If a vendor feature maps cleanly into one of these, do not describe it as a one-off concept.

Portable baseline

Treat this as the portability floor:

1. Repo-local instructions are the source of truth

• Keep survey behavior in checked-in markdown or skill files.
• Do not duplicate the whole survey rubric into per-platform config blobs.

2. Assume least privilege

• The survey should still work in read-only or approval-heavy environments.
• Prefer one deterministic final write of the artifact files.

3. Hooks are optional accelerators

• Claude and Gemini have richer hook systems than the Codex docs in scope here.
• Validation must still be runnable as an ordinary post-generation step when no hook parity exists.

4. Subagents improve execution, not artifact shape

• Claude and Gemini both have strong subagent stories.
• Codex portability should not depend on first-class subagents.
• The 4-lane structure still matters, but the filenames and section headings must stay identical even when the runtime differs.

5. Project settings may be missing or untrusted

• Project-local config is useful, but the survey skill should not break when it is absent, ignored, or considered untrusted.

Artifact contract

Keep the same files everywhere:

.survey/{slug}/
├── triage.md
├── context.md
├── solutions.md
└── platform-map.md   # only when the topic is platform/tooling related

Keep the same headings everywhere:

• triage.md → # Triage
• context.md → ## Workflow Context, ## Affected Users, ## Current Workarounds, ## Adjacent Problems, ## User Voices
• solutions.md → ## Solution List, ## Categories, ## What People Actually Use, ## Frequency Ranking, ## Key Gaps, ## Contradictions, ## Key Insight
• platform-map.md → ## Settings, ## Rules, ## Hooks, ## Platform Gaps

Do not let platform-native output modes replace the markdown artifact schema.

Platform notes

Claude

• Strong project-level settings and hook surfaces.
• Subagents are a first-class way to run specialized lanes.
• Good fit for parallel lanes and hook-backed validation.
• Still keep the artifact contract in repo-local instructions, not only in .claude/ config.

Codex

• Treat config/instruction files, sandbox mode, approvals, and MCP settings as the main documented portability surface.
• Do not rely on hook parity or undocumented subagent behavior.
• The artifact contract must survive plain instruction-file execution.

Gemini

• Strong settings layering, subagents, and command-based hooks.
• Good fit for lane specialization and post-generation validation.
• Still keep the markdown artifact schema explicit instead of assuming JSON output mode solves portability.

Recommended validation pattern

Use the same validation logic everywhere: 1. create the artifact files 2. check required headings and filenames 3. check citations / provenance labels exist where needed 4. verify that platform-map files use the settings / rules / hooks layer for platform topics

Default repo-local validator:

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

If a platform supports hooks, wrap the validator there. If it does not, run the validator as a normal command after writing files.

Anti-patterns

• Putting the only copy of survey behavior in platform-specific settings
• Using hook-specific magic as if all platforms support it
• Letting a platform-native output mode replace the markdown artifact contract
• Expanding platform-map into vendor trivia that does not map back to settings, rules, or hooks
• Treating thin evidence as if it were direct primary-source verification