alex
e9074646b7
Replace 4 separate instruction files with 1 real file + symlinks: - .github/copilot-instructions.md is the canonical instruction file - CLAUDE.md and .cursorrules are symlinks to it - AGENTS.md stays as global config (not a project instruction file) This eliminates all sync/merge logic - changes propagate automatically. Changes: - AGENTS.md: rewrite Cross-Tool Instruction Files section for symlink convention - librarian.md: simplify to maintain single instruction file + verify symlinks - lead.md: simplify PHASE-WRAP and Documentation Completion Gate - commands (init, bootstrap-memory, save-memory): update for symlink model - doc-coverage skill: verify symlinks exist and point correctly
71 lines
2.8 KiB
Markdown
71 lines
2.8 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 `.github/copilot-instructions.md` and its symlinks:
|
|
|
|
- Does `.github/copilot-instructions.md` exist and contain current project info?
|
|
- Do symlinks exist and point correctly?
|
|
- `AGENTS.md -> .github/copilot-instructions.md`
|
|
- `CLAUDE.md -> .github/copilot-instructions.md`
|
|
- `.cursorrules -> .github/copilot-instructions.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.
|