---
name: github-seo-evaluation-loop
description: Use when running recurring GitHub repository SEO evaluation, comparing broad Chinese search visibility over time, producing metrics evidence, weekly summaries, manual Baidu/Bing/AI search tasks, or deciding whether an SEO experiment should trigger another optimization round.
---

# GitHub SEO Evaluation Loop

## Overview

Use this skill to run the measurement half of an SEO loop: measure, compare, classify evidence, and recommend the next experiment. It is read-only for online repositories by default; it may write local metric files and summaries inside the SEO lab.

For detailed fields, templates, and automation prompts, read `references/evaluation-playbook.md`.

## Project Root Resolution

Resolve `<github-seo-lab-root>` from the current workspace or a path supplied by the user. Confirm it contains `06_METHOD/measurement-framework.md` and `07_METRICS/tracking-config.json` before running. If no matching root can be found, report the missing-root blocker or ask the user for the path; never assume a personal drive or username.

## Output Language

Write all human-facing outputs in Simplified Chinese by default.

- Use Chinese headings, explanations, conclusions, and recommendations in `weekly-summary.md`.
- Keep machine-readable column names, enum values, paths, repository names, command names, and API names unchanged when needed.
- In `manual_tasks.csv`, keep headers and enums stable, but write `skip_reason` and `notes` in Chinese.
- JSON keys may remain machine-readable English; if human interpretation is needed, add a Chinese Markdown companion such as `query-validation.zh.md` or `comparison.zh.md`.

## Mode Gate

Default to `audit_only`.

Allowed in `audit_only`:

- Read local method docs, tracking config, previous runs, and public search results.
- Run local tracking scripts if they already exist and match the project format.
- Write local evidence, metrics, manual task CSVs, and weekly summaries.
- Recommend candidate experiments.

Forbidden unless the user explicitly authorizes implementation:

- Editing README, README_zh, Description, Topics, releases, or profile pages.
- Creating branches, commits, PRs, issues, discussions, or external content.
- Claiming a causal fix when evidence is insufficient.

If an optimization action is needed, output a proposed next experiment and route implementation through `github-repo-seo-standard`.

## Cloud Runner Boundary

When the task runs through `github-seo-cloud-runner`, GitHub Actions is only the monitoring and fact-package layer.

Allowed for GitHub Actions scripts:

- Start on a schedule.
- Collect GitHub search ranking, stars, traffic, clones, release downloads, and raw evidence.
- Save CSV / JSON / Markdown monitor results.
- Generate `07_METRICS/fact-packs/<fact_pack_id>/` with facts and rule-level anomaly flags.
- Commit those artifacts back to the cloud-runner repository.

Forbidden for GitHub Actions scripts:

- Generate a "best action plan".
- Judge SEO causality.
- Edit README, Description, Topics, releases, profile pages, branches, commits, PRs, issues, discussions, skills, automation, or external pages.

Codex/ChatGPT model automations own the analysis and optimization layer: read the latest fact package, interpret signal versus noise, design experiments, audit risk, draft concrete copy, and implement only when the automation prompt contains explicit implementation authorization and scope.

## Core Loop

1. Read the project context:
   - `github-seo-lab/06_METHOD/measurement-framework.md`
   - `github-seo-lab/06_METHOD/keyword-methodology.md`
   - `github-seo-lab/06_METHOD/repo-seo-standard.md`
   - `github-seo-lab/06_METHOD/channel-seo-strategy.md`
   - `github-seo-lab/07_METRICS/tracking-config.json`
2. Create a `run_id` using UTC time and create `github-seo-lab/07_METRICS/runs/<run_id>/`.
   - When working in the GitHub SEO lab, first try the fixed local entrypoint: `python 03_CODEX/scripts/run_seo_tracking.py --no-diagnostic-gh-search`.
   - Do not stop after a protocol audit or script mismatch observation. Every scheduled monitor run must create `run-status.json`.
   - If collection succeeds, write `status=completed`; if collection is blocked, write `status=blocked`, `weekly-summary.md`, and a Chinese blocker reason.
   - Post-monitor analysis may analyze only runs whose `run-status.json` has `status=completed`; blocked runs require blocker analysis, not optimization proposals.
3. Run an automation capability audit:
   - Check `gh auth status`.
   - Check whether required environment variables are configured without printing secret values.
   - Save `automation-capability.json` and `automation-capability.zh.md`.
   - Classify blockers as `missing_credentials`, `invalid_auth`, `insufficient_permission`, `no_official_api`, `no_legal_automated_path`, `network_error`, or `rate_limited`.
4. Validate the query set:
   - Every query has `keyword_width`.
   - At least 60% of baseline GitHub queries are `broad_category` or `scenario_problem`.
   - Chinese-user projects use Chinese-first queries.
   - Brand and exact-long-tail queries are marked as supporting diagnostics, not real discovery proof.
5. Collect GitHub business proxy metrics for every configured repo:
   - Stars, forks, watchers/subscribers if available, open issues, pushed_at, updated_at.
   - Traffic views, clones, popular referrers, and popular paths through GitHub API when auth permits.
   - Release asset download counts through GitHub API.
   - Save raw evidence under `github_business/`, write `business-metrics.csv`, and write `business-metrics.zh.md`.
   - If a call fails, record the exact blocker; do not collapse it into "not measured."
6. Run or queue channel checks:
   - GitHub top100 repo search: use unauthenticated public GitHub Search REST API as the canonical ranking protocol when possible.
   - Use authenticated `gh search repos` only as a secondary diagnostic or fallback; record `logged_in=true` and do not compare it directly with unauthenticated runs without marking protocol differences.
   - Baidu, Bing, and AI search: execute only when the environment has a stable legal path; otherwise create blocked/manual tasks with exact blocker type.
   - Record whether each repo is `github_repo_only`, has docs/GitHub Pages, has an external site, or has site work `deferred_by_user`.
   - If a controllable site exists, track sitemap, robots, schema/JSON-LD, canonical URL, `llms.txt`, webmaster access, and URL submission status as asset-readiness fields, not ranking proof.
7. Record one row per query with protocol fields:
   - timestamp, run_id, channel, engine, repo, query_group, keyword_width, query, target, rank, score, status, evidence path, query method, locale, region, login state, sort mode, result type, device, endpoint, reviewer, raw hash.
8. Compare against the previous compatible run:
   - New Top10/Top20/Top50 appearances.
   - Lost Top10/Top20/Top50 appearances.
   - Broad/scenario movement separately from brand/exact movement.
   - Query protocol changes that make comparisons unreliable.
   - Save `run-compatibility.zh.md` listing comparable runs, excluded runs, and exclusion reasons.
9. Classify conclusions:
   - `validated_signal`: repeated weekly evidence, especially broad/scenario improvement.
   - `watch`: smoke-test-only, single-run, small sample, or AI mention without citation.
   - `no_signal`: repeated not found or worse without compensating query groups.
   - `unverified`: plausible but not yet supported.
   - Exclude `post_change_smoke` rows from `validated_signal` decisions unless a later compatible weekly run confirms them.
   - If a repo has fewer than five stable broad/scenario GitHub queries, mark group-level trend conclusions as `小样本未证实`.
10. Output:
   - Append or create `07_METRICS/metrics.csv`.
   - Append or create `07_METRICS/business-metrics.csv` when practical.
   - Save `evidence-registry-delta.zh.md`; update `07_METRICS/evidence-registry.csv` only when evidence level changes are supported by compatible weekly evidence.
   - Save `asset-readiness.csv` for release, profile, docs/site, package registry, issue/discussion, external content, and AI citation target readiness.
   - Save `weekly-summary.md`.
   - For post-monitor analysis runs, save `executive-summary.zh.md`: a 600-1000 Chinese-character self-contained plain-language decision summary. The user must be able to decide without opening any other file. Do not use internal experiment IDs as action labels; if an ID is unavoidable, put it after a plain Chinese action. Each proposed action must name the repo/product, exact field, intended change, reason/evidence, risk or unverified status, and whether user approval is required.
   - Save `manual_tasks.csv` when required.
   - List candidate next experiments and concrete next actions without editing repos.

## Automation-First Rule

Maximize automation before creating manual tasks. Manual tasks are the last resort.

Every blocked/manual task must include:

- `automation_possible`
- `blocker_type`
- `blocker_reason`
- `required_credential_or_tool`
- `next_action`

Do not write vague reasons like "needs manual" when the real blocker is missing credentials, invalid GitHub auth, insufficient permission, lack of an official API, legal/TOS risk, or missing browser/session capability.

## GitHub Search Bias Control

For ranking measurement, prefer the public unauthenticated GitHub Search REST API with `logged_in=false`. This reduces possible owner/account/session bias when measuring the user's own repositories.

Authenticated `gh search repos` is acceptable for:

- spot checks
- fallback when unauthenticated API is blocked
- business proxy metrics that require authentication

When authenticated search is used, record `query_method=gh_cli_authenticated`, `logged_in=true`, and the protocol difference. Do not compare authenticated and unauthenticated ranks as if they were the same protocol.

## Evidence Rules

- Do not present high rank on `brand` or `exact_long_tail` as proof of real exposure.
- Do not add GitHub, Baidu/Bing, and AI scores into one combined score.
- Treat `visibility_score` as a diagnostic only, not platform weight or traffic proof.
- Treat GitHub traffic, clones, stars, release downloads, referrers, and paths as business proxy metrics. They must be collected when API access allows, but they do not prove SEO causality by themselves.
- Treat sitemap submission, URL submission, IndexNow, Baidu push, schema/JSON-LD, and `llms.txt` as asset or indexing observations, not ranking proof.
- If only precise terms rank and broad/scenario terms do not, write: `真实曝光未验证`.
- If evidence is insufficient, output only known facts, candidate hypotheses, validation paths, temporary mitigations, and unverified conclusions.

## Success Criteria

An SEO experiment is effective only when all are true:

- At least two compatible weekly runs support the signal.
- At least one `broad_category` or `scenario_problem` query improves.
- The improvement is not explained solely by protocol changes.
- Supporting movement appears in related query groups or downstream business metrics.
- The signal is not based only on `post_change_smoke`.

If only brand/exact terms improve, classify the result as precision recall, not discovery growth.

## Next Actions

Every `weekly-summary.md` must include next actions grouped as:

- `可以直接自动执行`
- `需要配置凭证后自动执行`
- `需要用户人工完成`
- `暂缓/不建议执行`

Do not leave the next-action section empty.