missing_docs: fix audit for Astro layout & document Kitty keyboard protocol#52
Open
hongyi-chen wants to merge 1 commit intomainfrom
Open
missing_docs: fix audit for Astro layout & document Kitty keyboard protocol#52hongyi-chen wants to merge 1 commit intomainfrom
hongyi-chen wants to merge 1 commit intomainfrom
Conversation
…nt Kitty keyboard protocol The audit script assumed a `docs/` subdirectory layout and `.md` filenames, so on the current Astro Starlight tree (`src/content/docs/`, `.mdx`) every mapped doc resolved as missing. This refreshes the skill so it produces useful signal again. - audit_docs.py: resolve doc paths from the repo root, accept .md/.mdx interchangeably (and README.md → index.mdx), add --weak-coverage flag for the strict keyword check, broaden keyword extraction to handle slash-command flags (RewindSlashCommand → /rewind) and UI-suffix flags. - feature_surface_map.md: update every entry to the actual `.mdx` paths, fix `agent-platform/warp-agents/*` mappings that should be either `local-agents/*` or `capabilities/*`, add ListSkills/SyncAmbientPlans to the ignore list (server-side). - SKILL.md: document `--weak-coverage` and the `.md`/`.mdx` resolution. - full-screen-apps.mdx: add a Kitty keyboard protocol section so the newly-shipped flag is documented where TUI users will look. Default audit now runs clean for features/CLI/API; `--weak-coverage` surfaces ~30 mapped pages where the feature isn't named verbatim, for follow-up review. Co-Authored-By: Oz <oz-agent@warp.dev> Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The
missing_docsskill's audit script was producing false negatives because it assumed a legacydocs/subdirectory layout and.mdfilenames. On the current Astro Starlight tree (src/content/docs/,.mdx), the script resolved every mapped doc as missing and surfaced 71+ high-severity "Mapped doc does not exist" findings.This PR makes the audit useful again, adds keyword-matching logic for slash-command flags, and patches a real coverage gap that surfaced during triage.
What changed
audit_docs.pysrc/content/docs/(Astro layout) with a fallback to legacydocs/..md↔.mdxinterchangeably, plusREADME.md↔index.mdx, when checking surface-map entries.--weak-coverage(low-severity, noisier).camel_to_search_termsto handle slash-command flags (RewindSlashCommand→/rewind,ForkFromCommand→/fork-from), UI-suffix flags (ContextWindowUsageV2), and first-N-words prefixes.feature_surface_map.md— fully refreshed:.mdxfile. The previous map referenced ~40 paths underagent-platform/warp-agents/*that don't exist; those features actually live underagent-platform/local-agents/*oragent-platform/capabilities/*.AskUserQuestion,OzChangelogUpdates,KittyKeyboardProtocol,WarpPacks,SharedWithMe,BundledSkills,SkillArguments,OpenCodeNotifications,CodexNotifications, etc.) to their respective pages.ListSkillsandSyncAmbientPlansto the ignore list (server-side wiring, not user-facing).SKILL.md— documents--weak-coverage, the.md/.mdxresolution behavior, and corrects the script invocation path.terminal/more-features/full-screen-apps.mdx— adds a Kitty keyboard protocol section. The flag is GA, was unmapped previously, and the feature is most relevant to users running TUI apps that need progressive-enhancement key reporting.Audit results
Before: 71 high + 47 stale findings (almost all stale-map false positives).
After: default mode reports 0 feature/CLI/API gaps and 47 staleness candidates.
--weak-coveragesurfaces ~30 mapped pages whose target file exists but where the feature name doesn't appear verbatim — a useful follow-up list for the docs team to review.Test plan
npm run build— clean (316 pages built in ~58s)python3 .agents/skills/missing_docs/scripts/audit_docs.py --warp-internal /workspace/warp-internal --warp-server /workspace/warp-server— runs without errorspython3 .agents/skills/missing_docs/scripts/audit_docs.py --weak-coverage --category features— produces the expected weak-coverage listThis PR was created by Oz (running Claude Code).