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

Open Beginner friendly
  • Is something wrong?
#20,928 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
62/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Active
Tech stack
github-actions, go
Domain
cli, documentation

Research direction

Start with the four named spots: the "Node snapshot MCP server" paragraph in docs/agent-analysis.md (around line 183), the Targeted references bullet in skills/cao-cli/SKILL.md (around line 101), Shell procedure step 2 and the Data contract section of skills/analyze-cao/SKILL.md, and step 4's freshness wording. Check the tool list in internal/cli/native_mcp.go and the cache-path behaviour in internal/cli/native_download.go before editing. Done when the links resolve, no Node MCP wording remains, and npm run docs:build and node --test tests/unit/agent-docs-validation.test.mjs pass.

Written by the indexing model from the issue text.

Description

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
Dominant language
JavaScript
Stars
19
Forks
4
Avg merge
4h
Merged PRs (30d)
708

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from githubnext/gh-cao

All issues in githubnext/gh-cao

Similar issues

More JavaScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.