[self-care:agent-discoverability] Fix stale MCP wording and missing CAO skill routes for agent discovery

Abierto Apto para principiantes
  • ¿Algo no está bien?
#20,928 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
2/5
Tiempo estimado
1-3 horas
Aptitud para principiantes
62/100
Tipo de issue
Documentación
Claridad
Bastante claro
Estado de actividad
Activo
Stack tecnológico
github-actions, go
Área
cli, documentation

Línea de trabajo

Empieza por los cuatro puntos indicados: el párrafo «Node snapshot MCP server» en docs/agent-analysis.md (alrededor de la línea 183), el punto Targeted references en skills/cao-cli/SKILL.md (alrededor de la línea 101), el paso 2 de Shell procedure y la sección Data contract en skills/analyze-cao/SKILL.md, y la redacción sobre la actualidad del paso 4. Antes de editar, revisa la lista de herramientas en internal/cli/native_mcp.go y el comportamiento de la ruta de caché en internal/cli/native_download.go. Está terminado cuando los enlaces se resuelven, ya no queda texto sobre el servidor MCP de Node y npm run docs:build y node --test tests/unit/agent-docs-validation.test.mjs pasan.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

self-care self-care:agent-discoverability

Summary: The agent-discoverability audit of canonical CAO routes found no clean pass across its seven tasks. Source review at revision 185fd262b shows four routing defects and two gaps: stale "Node" MCP wording, a skill entry that promises cache-path content the referenced file lacks, no ingestion command in the analysis skill, and no link from the analysis skill to schema authority. Freshness semantics and the debug route are also undocumented for agents.

Action: A maintainer should assign this issue to Copilot, or apply the four documentation fixes below. Acceptance: all canonical links resolve, no Node MCP wording remains, and re-running the seven-task audit routes every task without repository search.

Agent prompt

In githubnext/gh-cao, make documentation-only routing fixes. Do not change code, policy, query semantics, schema, or workflow lock files.

  1. docs/agent-analysis.md, the paragraph beginning "The Node snapshot MCP server exposes exactly these two tools": replace "Node snapshot MCP server" with the Go gh cao mcp server. Keep the "exactly these two tools, in that order" claim only after verifying the registered tool list in internal/cli/native_mcp.go.
  2. skills/cao-cli/SKILL.md, the Targeted references bullet for workflow-runtime.md says "cache paths, fallback behavior". Either correct that description to what the file covers, or add the cache-path content to skills/cao-cli/references/workflow-runtime.md after verifying it in internal/cli/native_download.go.
  3. skills/analyze-cao/SKILL.md, Shell procedure step 2 says an operator "must ingest" the artifact without a command. Add cao-dashboard ingest --source .cao (as documented in docs/cao-cli.md and docs/dashboard-data-ingestion.md). In the Data contract section, link specs/dashboard-data.md as schema authority and specs/dashboard-gh-aw-jsonl-mapping.md for the activity shard mapping, replacing the unlinked phrase "the activity shard schema".
  4. skills/analyze-cao/SKILL.md, step 4 tells agents to "establish freshness" without a stale threshold. Either link where stale is defined, or state that no threshold exists and that agents must compare as-of against the analysis window.

Optional: add a debug-cao row to the Common routes table in skills/cao-cli/SKILL.md, pointing deployment and campaign failure diagnosis to skills/debug-cao/SKILL.md.

Validate with npm run docs:build and node --test tests/unit/agent-docs-validation.test.mjs. Keep the change set to these skill and doc files.

Critical findings
  • docs/agent-analysis.md:183 calls the MCP server "Node snapshot", but docs/agent-analysis.md:245 says the former Node MCP is removed. The live endpoint is the Go gh cao mcp command.
  • skills/cao-cli/SKILL.md:101 says references/workflow-runtime.md covers "cache paths". That file contains no cache-path content.
  • skills/analyze-cao/SKILL.md requires an operator ingest step with no command. The cao-dashboard ingest --source DIRECTORY command appears only in docs/cao-cli.md and docs/dashboard-data-ingestion.md.
  • skills/analyze-cao/SKILL.md names "the activity shard schema" and "the dashboard data specifications" without links. The authoritative files are specs/dashboard-data.md and specs/dashboard-gh-aw-jsonl-mapping.md.
  • No stale threshold was found in the canonical docs searched. Agents are told to establish freshness with no rule.
  • debug-cao is linked only from operator docs, not from the agent entry points.
Task table
Task Success Entry point discovered Skill used Precomputed artifact used MCP used PostgreSQL used UI scraping attempted Repository search required Navigation hops Evidence
1. Disabled campaigns Partial analyze-cao, then agent-analysis analyze-cao No No No No No 3 Route found. No snapshot or service in this run, so evidence is unavailable.
2. Snapshot freshness Fail analyze-cao step 2, cao-cli analyze-cao, cao-cli No No No No Yes 3 Skill says to establish freshness. No stale threshold in the canonical docs searched.
3. Named campaign failure Partial Not from analyze-cao or agent-analysis. Found in docs/operations.md debug-cao (via operator docs) No No No No Yes 4 debug-cao exists but has no agent-entry link.
4. Recent failures via catalog Fail agent-analysis, "without a shell" none No No. cao_catalog not exposed No No Yes 2 Stale "Node snapshot MCP" text contradicts the removal note.
5. Historical analysis Fail analyze-cao step 2 analyze-cao No No No No Yes 4 Ingest step has no command. The command lives in cao-cli.md and dashboard-data-ingestion.md.
6. Schema authority Partial cao-cli guardrails, then specs/dashboard-data.md cao-cli No No No No Yes 3 analyze-cao names the shard schema without a link.
7. Activity download and default path Partial analyze-cao step 2 analyze-cao, cao-cli No No No No Yes 3 The artifact is JSONL with no database file. Default .cao is in the flag help and docs/cao-cli.md, not in the skills.
Evidence and limits
  • Checkout revision 185fd262b. Published Pages URLs were not fetched; findings come from repository source.
  • gh cao --version was denied by the sandbox, so no CLI query ran.
  • cao_catalog and cao_query were not exposed to this run. MCP calls: 0. HTTP fetches: 0.
  • No PostgreSQL or operational snapshot access. No UI scraping.
  • Repository search was needed for tasks 2 through 7 because the canonical entry points lack those links. Recorded as a defect.

cao: githubnext/gh-cao, correlation: 43637313167-4046

Generated by SelfCare / Agent Discoverability · copilot · routed: haiku55 xhigh · ~16 AIC · ⌖ ~2 AIC · ⊞ 8.7K · ◷

  • expires on Nov 28, 2026, 8:41 PM UTC
Lenguaje dominante
JavaScript
Estrellas
19
Forks
4
Merge medio
4 h
PR fusionados (30 d)
708

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de githubnext/gh-cao

Todos los issues de githubnext/gh-cao

Issues similares

Más issues de JavaScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.