| name | docs-product-alignment |
| description | Audit and update docs/copilot/ documentation to accurately reflect current VS Code AI capabilities. Use when: competitive analysis reveals gaps, product launches new features, docs use outdated framing, or keyword coverage needs strengthening for discoverability by users and AI agents. Produces a gap analysis plus targeted edits across affected files. |
Documentation Product Alignment
Audit VS Code Copilot documentation against current product capabilities and produce targeted, style-compliant edits. Follow the docs-writing style guide for all writing rules.
Guardrails
- Factual only. Every claim must map to something the product does today. No superlatives, no competitive comparisons, no invented terminology.
- Content framing. Establish each page's primary persona, reader intent, and article purpose by following the content-framing guidance. Ask the writer before editing when the framing is ambiguous and would change the audit or recommendations.
- Two consumers. The primary persona reads the prose; AI agents and search crawlers index Keywords, MetaDescriptions, and opening paragraphs. Both matter.
- Minimal edits. Change only what is inaccurate, outdated, or missing. One precise sentence beats a rewritten section.
- Verifiable. If you cannot point to a UI element, setting, or documented behavior, do not write it.
Workflow
- Gather context and frame each page. Read the latest release notes, check github.com/features/copilot, and review any competitive claims or feature matrices the user provides. For each page, record its primary persona, reader intent, and article purpose before proposing edits.
- Audit high-traffic pages. Read each page and compare against current product truth. Focus on MetaDescriptions, Keywords, opening paragraphs, and terminology.
- Gap analysis. List what is inaccurate, outdated, or missing. Map each gap to a file and location. Include the page framing in the analysis, and prioritize by page traffic and impact on the primary persona's intent.
- Edit. Apply targeted changes that support the recorded framing. Vary phrasing across pages to avoid repetition.
- Verify. Search changed files for banned words, em-dashes, and MetaDescription length violations. Confirm that each changed page still serves its recorded primary persona and reader intent.
High-traffic pages to always check:
Terminology
Use these terms consistently. The "Avoid" column lists terms that creep in but should not.
| Concept | Use | Avoid |
|---|
| Autonomous coding sessions | agents | agent mode, agentic workflows |
| Running without user interaction | background agents | background agent mode |
| Code suggestions as you type | inline suggestions | code completions, autocomplete |
| Predicted next edit location | next edit suggestions (NES) | predictive edits |
| Understanding code across files | workspace context, cross-file reasoning | deep semantic understanding (overuse) |
| GitHub's search for code context | GitHub's code search | remote search |
| VS Code's type/symbol analysis | language intelligence (IntelliSense, LSP) | code intelligence |
| Multiple AI model options | multiple AI models | leading AI models |
| Plan then implement workflow | Plan agent, implementation agent | planning mode |
Capability areas
When auditing, ensure docs accurately cover these areas:
- Agents: plan, implement, verify, parallel sessions, local/background/cloud, third-party support
- Context: semantic search, language intelligence (LSP), GitHub code search, cross-repo awareness
- Multi-file editing: coordinated changes, architecture-level refactoring, framework migrations
- Enterprise: organization policies, model access controls, content exclusions, trust boundaries
- SDLC workflow: Plan agent, implementation agent, Copilot code review, background/cloud handoff
- Scale: large codebases, monorepos, multi-root workspaces, remote indexing
