docs-update

Pre-Commit Documentation Checklist

Before every commit, verify that ALL documentation is in sync with the code changes being committed. Run git --no-pager diff --cached --name-only (or git --no-pager diff HEAD --name-only for unstaged) to identify changed files, then check each doc category below.

1. ARCHITECTURE.md

Update docs/ARCHITECTURE.md if any of these changed:

• Project structure tree — new files/directories added or removed
• Scene flow diagram — scene transitions changed
• Utility patterns — new utilities created, existing ones changed
• Lifecycle patterns — shutdown cleanup, event listener patterns changed
• Config/theme patterns — new constants, theme values, or config patterns
• Known gotchas — new Phaser quirks, browser compat issues discovered

2. ROADMAP.md

Update docs/ROADMAP.md:

• Backlog — remove completed items, add new feature ideas
• Known Issues — add new bugs discovered, remove resolved items
• Test Coverage Gaps — update if tests were added or gaps identified
• Deferred Refactors — add new debt discovered, remove resolved items

3. GAMEPLAY.md

Update docs/GAMEPLAY.md if:

• Controls changed (keyboard, gamepad, touch)
• Level mechanics changed (objectives, hazards, scoring)
• New game features added (items, mechanics, zones)

4. ART_STYLE.md

Update docs/ART_STYLE.md if:

• Visual style changed (colors, textures, pixel art patterns)
• New visual elements added (markers, buildings, effects)
• UI styling changed (button styles, fonts, theme colors)

5. TESTING.md

Update docs/TESTING.md if:

• New test helpers or fixtures added to conftest.py
• New test patterns established
• Debugging techniques discovered
• Known flaky tests identified or resolved

6. In-Game Changelog

Update the changelog entries in src/config/localization.ts if:

• Any player-visible change was made (UI, controls, gameplay, visuals)
• Look for the changelog key in each language's translations
• Add a dated entry describing the change in user-facing language

7. Copilot Instructions

Update .github/copilot-instructions.md if:

• Key files changed (new important files, renamed files)
• Critical patterns changed (localStorage keys, placeholder syntax)
• Quick commands changed (new scripts, changed test commands)
• Domain knowledge changed (new game concepts, terminology)
• Custom agents/skills added or modified
• Pre-commit checklist itself needs updating

8. Skills and Agents

Update .github/skills/ or .github/agents/ if:

• Workflow processes changed (audit steps, review criteria)
• New tools or patterns should be codified for reuse
• Visual style rules changed (update art-review skill alongside ART_STYLE.md)

9. README.md

Update README.md if:

• Features list changed — new gameplay features, input methods, accessibility
• Quick start / testing instructions changed — new commands, new setup steps
• Documentation table changed — new docs added or renamed
• Screenshots outdated — significant visual changes warrant new screenshots. Use the documentation-screenshots skill to recapture them.

The README is the public face of the project. Keep it concise — detailed content belongs in docs/. Link to docs rather than duplicating.

How to Apply

For each changed source file, ask: "Does this change affect any documentation?" Walk through categories 1–9 above. If a doc needs updating but the change is trivial (typo fix, internal refactor with no API change), skip it.

Do NOT:

• Update docs for changes that don't affect them
• Add verbose explanations — keep entries concise
• Create new doc files unless explicitly asked
• Update dates/timestamps in docs (they use git history)

Do:

• Keep the project structure tree in ARCHITECTURE.md current
• Keep ROADMAP.md as the single source of truth for work status
• Keep changelog entries in ALL 14 languages
• Keep copilot-instructions.md lean — it's injected into every prompt
• Keep docs as few, long files — Copilot CLI loads docs by file path; fewer files = fewer tool calls = faster context. Files up to ~3,000 lines are fine. Don't split a doc unless it exceeds ~5,000 lines. Related information in the same file helps the agent see connections it would miss across separate files.

Source: antoinecellerier/les-aiguilles-blanches — distributed by TomeVault.