documentation-maintenance

name	documentation-maintenance
description	Workflow skill for proactively updating stale docs and fixing docs path/layout drift. Use when: docs in README.md or docs/** are outdated, command usage has changed, or documentation file/folder placement changed.

Documentation Maintenance Skill

Overview

This skill standardizes how to keep repository documentation accurate when command usage, setup steps, or file placement changes over time.

Primary goals:

• Detect stale command examples and outdated explanations
• Update references when docs files/folders move
• Keep README.md, docs/**, .github guidance, and guidance assets aligned
• Prefer minimal, surgical edits; only reorganize structure when necessary to resolve path/layout drift or duplicated/conflicting instructions

Scope:

• README.md
• docs/**
• .github/copilot-instructions.md
• .github/prompts/review.prompt.md
• docs/guidance/assets/**

---

Trigger Timing

Run this workflow when any of the following happens:

1. PR creation or PR update
2. Commands in setup/build/test flow changed
3. Documentation file/folder placement changed
4. Broken links or path resolution issues are reported

---

Workflow Phases

Phase 1: Drift Detection

Objective: Find where docs are stale or paths are invalid.

Checks:

1. Compare documented commands with current executable sources:
   • package.json scripts
   • .devcontainer/postCreateCommand.sh
   • CI or review checklists in .github
2. Verify docs links and relative paths from each markdown file location
3. Detect folder placement drift (moved/renamed docs files)
4. Identify duplicated instructions that should point to a shared source file

Output format:

Drift Report
- Command drift: [file + section + expected command]
- Path drift: [file + broken link + corrected link]
- Structure drift: [old path -> new path]

Phase 2: Scope Confirmation

Objective: Confirm update boundaries before editing.

Default inclusion:

• README.md, docs/**, .github guidance docs, guidance assets

Default exclusion:

• Runtime source code behavior changes
• Dependency upgrades unrelated to doc accuracy

If uncertainty remains, ask focused clarification before editing.

Phase 3: Update Strategy

Objective: Decide how to update docs safely and consistently.

Rules:

1. Prefer a single source of truth for examples (such as docs/guidance/assets/*)
2. In guides, prefer links to shared examples over duplicated code blocks
3. Keep edits minimal where possible, but allow section reorganization when readability improves
4. Preserve bilingual parity for paired docs when applicable
5. When adding locale-specific docs with untranslated bodies, add a clear placeholder note near the top to avoid misleading readers
6. Use native language labels in locale document headings where practical (for example, हिन्दी, 한국어, 简体中文, 繁體中文)

Phase 4: Implementation

Objective: Apply changes and keep references coherent.

Execution checklist:

1. Update stale command text and explanations
2. Rewrite outdated file links using valid relative paths
3. Move or add example files when needed (docs/guidance/assets/**)
4. Replace duplicated inline examples with links to shared example files
5. Update cross-references in .github docs if docs paths changed

Phase 5: Validation

Objective: Confirm documentation is internally consistent.

Validation checklist:

1. Run production build check when docs mention Hugo workflows:

   cd exampleSite && hugo --gc --minify
   

2. Verify no broken internal links in edited docs
3. Confirm referenced files actually exist
4. Confirm no unintended files were modified (git status)

Phase 6: PR Preparation

Objective: Present changes with clear reasoning.

Include in PR description:

1. What drift was detected (commands/paths/structure)
2. Which files were updated and why
3. Whether sections were reorganized and rationale
4. Any remaining manual follow-up tasks

---

Practical Patterns

Pattern A: Command usage drift

When a documented command differs from actual workflow:

1. Update command in docs
2. Update explanation text that depends on the old command
3. Update troubleshooting guidance if symptoms changed

Pattern B: File placement drift

When docs path changes:

1. Move/rename docs file
2. Update all inbound references
3. Update contributor guidance that cites old paths

Pattern C: Shared setup examples

When setup snippets repeat in multiple guides:

1. Move canonical snippets to docs/guidance/assets/*
2. Link from each guide section to the canonical file
3. Keep local guide text concise and task-oriented

Pattern D: Locale docs with placeholder content

When adding language-specific guide files before full translation is ready:

1. Keep heading language label consistent with native naming conventions
2. Add a short note near the top that the body is currently an English placeholder
3. Reflect this status in README.md documentation index if relevant

---

Example Run

User request:
"README.md and docs setup commands are outdated, and docs folders changed."

Skill output summary:
- Updated stale setup commands in README/docs
- Repointed broken links to new docs paths
- Consolidated devcontainer examples under docs/guidance/assets
- Replaced duplicate snippets with references in prerequisites sections

---

When This Skill Does NOT Apply

• Implementing runtime features unrelated to documentation
• Fixing application bugs without documentation impact
• Broad dependency migration not tied to docs accuracy

---

References

• Conventional Commits
• README.md
• docs/develop/project-structure.md
• copilot-instructions.md