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

Đang mở Phù hợp với người mới
  • Có gì không ổn?
#20,928 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
2/5
Thời gian dự kiến
1-3 giờ
Mức phù hợp với người mới
62/100
Loại issue
Tài liệu
Độ rõ ràng
Khá rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
github-actions, go
Lĩnh vực
cli, documentation

Hướng nghiên cứu

Bắt đầu từ bốn vị trí đã nêu: đoạn «Node snapshot MCP server» trong docs/agent-analysis.md (khoảng dòng 183), mục Targeted references trong skills/cao-cli/SKILL.md (khoảng dòng 101), bước 2 của Shell procedure và phần Data contract trong skills/analyze-cao/SKILL.md, cùng câu chữ về độ mới ở bước 4. Trước khi chỉnh sửa, hãy kiểm tra danh sách công cụ trong internal/cli/native_mcp.go và hành vi của đường dẫn cache trong internal/cli/native_download.go. Việc được coi là xong khi các liên kết hoạt động, không còn nội dung nào về MCP server Node, và npm run docs:build cùng node --test tests/unit/agent-docs-validation.test.mjs đều chạy thành công.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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
Ngôn ngữ chính
JavaScript
Star
19
Fork
4
Merge trung bình
4 giờ
Pull request đã merge (30 ngày)
708

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của githubnext/gh-cao

Tất cả issue của githubnext/gh-cao

Issue tương tự

Thêm issue về JavaScript

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.