alex
33180d6e04
AGENTS.md is now the canonical instruction file, with CLAUDE.md, .cursorrules, and .github/copilot-instructions.md as symlinks to it. This is simpler and more intuitive - the main file is at the root, not buried in .github/. Updated all references across agents, commands, skills, and .memory/.
71 lines
2.7 KiB
Markdown
71 lines
2.7 KiB
Markdown
---
|
|
name: doc-coverage
|
|
description: Documentation coverage checklist and update procedures — load when completing a feature or change set
|
|
---
|
|
|
|
## When to Use
|
|
|
|
Load this skill when a feature or change set is nearing completion. Documentation is a **completion gate** — a task is not done until docs are handled.
|
|
|
|
## Coverage Checklist
|
|
|
|
For every completed change set, verify documentation coverage:
|
|
|
|
### 1. README
|
|
- [ ] Does the README reflect the current state of the project?
|
|
- [ ] Are new features, commands, or configuration options documented?
|
|
- [ ] Are removed features cleaned up from the README?
|
|
|
|
### 2. Docs directory (`docs/*`)
|
|
- [ ] Are there relevant docs files that need updating?
|
|
- [ ] Do new features need their own doc page?
|
|
- [ ] Are API changes reflected in API documentation?
|
|
|
|
### 3. Instruction File
|
|
|
|
Check `AGENTS.md` and its symlinks:
|
|
|
|
- Does `AGENTS.md` exist and contain current project info?
|
|
- Do symlinks exist and point correctly?
|
|
- `CLAUDE.md -> AGENTS.md`
|
|
- `.cursorrules -> AGENTS.md`
|
|
- `.github/copilot-instructions.md -> ../AGENTS.md`
|
|
- Does the instruction file contain:
|
|
- Project purpose and overview
|
|
- Tech stack and architecture
|
|
- Coding conventions
|
|
- Build/test/lint commands
|
|
- Project structure
|
|
- Is the instruction file in sync with current project state?
|
|
|
|
**Anti-patterns:**
|
|
- Symlinks missing or pointing to wrong location
|
|
- Instruction file is stale or empty
|
|
- Instruction file duplicates `.memory/` tracking content (plans, research)
|
|
|
|
### 4. Inline documentation
|
|
- [ ] Are complex functions/components documented with comments explaining **why**, not **what**?
|
|
- [ ] Are public APIs documented with parameter descriptions?
|
|
|
|
## Update Procedure
|
|
|
|
1. Review the list of changed files and their purpose.
|
|
2. Identify which documentation files are affected.
|
|
3. Read the current state of each affected doc file.
|
|
4. Update docs to reflect the implemented changes — keep descriptions accurate and concise.
|
|
5. If a change removes functionality, remove or update the corresponding documentation.
|
|
6. If creating a new feature, add documentation in the most appropriate location.
|
|
|
|
## Anti-patterns
|
|
|
|
- **Never leave stale docs.** If you changed behavior, the docs must change too.
|
|
- **Never create placeholder docs.** "TODO: document this" is not documentation.
|
|
- **Never duplicate content across doc files.** Link to the canonical source instead.
|
|
- **Never wait for the user to ask.** If docs need updating, update them proactively as part of the change set.
|
|
|
|
## Delegation
|
|
|
|
- The **librarian** subagent is the specialist for documentation work.
|
|
- Lead should delegate doc coverage review to librarian after coder completes implementation.
|
|
- Librarian reads the changes, identifies doc gaps, and writes/updates documentation.
|