tools-only Freshness Checklist
For use by the
docs-writerskill. Defines audit targets and auto-fix rules for detecting stale documentation.
How to Run a Freshness Audit
- Read
VERSION.mdto get the canonical version number. - Walk through each audit target below.
- For each issue found, note: file path, line, issue, suggested fix.
- Present all issues in a summary table.
- Apply fixes after user confirmation (or immediately if told "fix all").
Audit Targets
1. Version Number Sync
Source of truth: VERSION.md → Current Version: X.Y.Z
Files to check:
| File | What to look for |
|---|---|
docs/*.md |
> Version X.Y.Z in header line |
.github/instructions/docs.instructions.md |
Version in header template example |
Auto-fix: Replace old version string with current from VERSION.md.
2. Agent Count and Table
Source of truth: List .github/agents/*.agent.md files
(exclude _subagents/ directory).
Expected count (as of 2026-02-26): 13 agents
Files to check:
| File | What to verify |
|---|---|
docs/README.md |
## Agents (N + 3 Subagents) heading and table rows |
.github/instructions/docs.instructions.md |
### Agents (N total) and table |
docs/README.md project structure |
# N agent definitions comment |
Auto-fix: Update count in heading. Add missing agents to table matching the existing column format. Remove entries for agents that no longer exist.
3. Skill Count and Table
Source of truth: List .github/skills/*/ directories
(exclude README.md file).
Expected count (as of 2026-02-26): 14 skills
Files to check:
| File | What to verify |
|---|---|
docs/README.md |
## Skills (N) heading and table rows |
.github/instructions/docs.instructions.md |
### Skills (N total) and table |
docs/README.md project structure |
# N skill definitions comment |
Auto-fix: Update count in heading. Add missing skills to the appropriate category table. Remove entries for deleted skills.
4. Prompt Guide Currency
Source of truth: docs/prompt-guide/README.md agent/skill tables.
Files to check:
| File | What to verify |
|---|---|
docs/prompt-guide/README.md |
Agent and skill tables match filesystem |
docs/README.md |
Prompt Guide section links are valid |
Auto-fix: Update tables to match current agent/skill inventory.
5. Prohibited References
Rule: Removed agents must not be referenced in live docs.
Banned patterns:
diagram.agent.mdadr.agent.mddocs.agent.mddocs/guides/docs/reference/docs/getting-started.md
Files to check: All docs/**/*.md, README.md, CONTRIBUTING.md.
Auto-fix: Replace with the correct skill reference
(see references/doc-standards.md → Prohibited References table).
6. Deprecated Path Links
Rule: No live doc should link to removed directories.
Check: Grep all in-scope markdown files for links to non-existent paths.
Auto-fix: Remove the link or replace with the current equivalent.
7. Instruction File Table Sync
Source of truth: List .github/instructions/*.instructions.md files.
Expected count (as of 2026-02-26): 25 instruction files
Files to check: Only relevant if docs/README.md or the root
README.md lists instruction files.
Auto-fix: Update count and table entries.
8. Template Inventory Sync
Source of truth: List .github/skills/azure-artifacts/templates/*.template.md files.
Expected count (as of 2026-02-09): 16 templates
Files to check: Only relevant if documentation references template counts.
Auto-fix: Update count reference.
9. Project Health Files
Source of truth: Filesystem agent/skill counts + CI validation results.
Files to check:
| File | What to verify |
|---|---|
QUALITY_SCORE.md |
Grades reflect current state; change log up to date |
docs/exec-plans/tech-debt-tracker.md |
Active items still relevant; resolved items moved |
Auto-fix: Update grades and log entries in QUALITY_SCORE.md. Mark resolved debt items
as resolved with the current date.
Summary Table Template
When reporting audit results, use this format:
| # | File | Line | Issue | Fix |
| --- | -------------------- | ---- | --------------------------------------- | -------------- |
| 1 | docs/README.md | 42 | Agent count says 6, actual is 8 | Update heading |
| 2 | docs.instructions.md | 34 | Missing `design` and `conductor` agents | Add table rows |
Known Issues
No known issues. Last audit: 2026-02-26.
All 21 discrepancies identified during the initial audit have been resolved (Tasks A–D). Fixes included:
- Version headers migrated to
[Current Version](../VERSION.md)links - Agent counts corrected to 8, skill counts to 8
- Conductor model corrected to Claude Opus 4.6, approval gates to 5
- MCP path fixed, broken link removed
- Glossary cross-references fixed, keyboard shortcut corrected, new terms added
- Scenarios directory removed; replaced by docs/prompt-guide/