| name | doc-refresh |
| description | Refresh a repo's documentation for a live production system — audit stale docs, rebuild a focused doc set with diagrams, update AI-agent knowledge bases, and improve code-level docstrings |
Documentation Refresh Skill
Use this skill when asked to overhaul, refresh, modernize, or clean up a
repository's documentation — especially for a system that is already in
production and has accumulated stale README content, dead analysis docs,
outdated AI-agent knowledge bases (AGENTS.md, CLAUDE.md, etc.), or
misleading code comments.
This skill is repo-agnostic. It does not assume any particular language,
framework, or doc tool. It encodes a phased process, a reusable checklist,
and a set of anti-patterns learned from running this refresh on real
production repos.
When to use this skill
- The user says something like "our docs are out of date," "refresh the
README," "clean up AGENTS.md," "audit our documentation," or "set up a
docs/ folder with architecture diagrams."
- A repo has legacy analysis files, dead feature references, or docs that
no longer match the live code.
- The user wants a repeatable framework they can reuse across repos.
How to use this skill
- Read
CHECKLIST.md in this skill directory for the phase-by-phase
process (Phase 0 through Phase 6).
- Read
ANTI-PATTERNS.md for common mistakes to avoid while auditing and
rewriting docs.
- Adapt the checklist to the target repo:
- Confirm with the user which phases apply (a small repo may not need
every phase; a large one may want each phase in its own session to
protect context windows).
- Identify the repo's actual doc tooling (Markdown + Mermaid is the
default assumption below, but adjust if the repo uses something else,
e.g. Sphinx, Docusaurus, or a wiki-only workflow).
- Always produce (or update) a running "roadmap" file in the repo root
(e.g.
DOCUMENTATION_ROADMAP.md) that captures the plan, audit
findings, and a "Lessons Learned" scratchpad. This gives future sessions
(human or agent) a clear handoff point and turns the current refresh
into reusable material for the next one.
- At natural session boundaries, write or update a
HANDOFF.md summarizing
what was done, what was verified, and exactly what the next session
should do next. Treat this as mandatory when the work will span more
than one session.
- Before declaring any phase complete, run the repo's actual lint/test
command (discover it from
AGENTS.md, README.md, justfile,
package.json, Makefile, or CI config) to make sure doc-only changes
didn't break anything, and re-check for stale references introduced by
the phase's own edits.
Core principles (apply unless the user overrides them)
- Repo docs are the source of truth. Any external wiki mirrors the
repo, never the reverse.
- Diagrams as code. Prefer Mermaid (or another text-based diagram
format already used in the repo) so diagrams stay version-controlled
and diffable.
- Separate, focused guides over one monolithic doc. Split by audience
and purpose: architecture, data flow, developer onboarding, operations,
deployment, etc.
- Delete stale docs outright rather than leaving them "for reference."
Git history is the archive.
- Update code-level docs (docstrings/comments) alongside Markdown.
A refreshed README next to a misleading docstring is a half-finished job.
- Phase the work and hand off explicitly. Long doc refreshes should be
broken into independently reviewable phases, each with its own commit(s)
and a handoff note for whoever (or whatever) picks up next.
See CHECKLIST.md for the concrete phase breakdown and ANTI-PATTERNS.md
for pitfalls to avoid.
