docs update

Documentation Community

Skill notes

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

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. ARTSTYLE.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)

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
Domain
Documentation
Author-declared agents
No explicit declaration found; this is not inferred or tested compatibility
Static check
88 / 100 · heuristic scan, not runtime safety proof
Runtime evidence
Not run; no isolated runtime test evidence is currently recorded
Author / version / license
@tomevault-io · no license declared
Token usage
Lean
Setup complexity
Plug-and-play
External API key
Not required
Operating systems
Unspecified (assume cross-platform)
Runtime requirements
No explicit requirements detected
Detected file/system behavior
  • Read-only
  • Write / modify
Network behavior
Local-only
Install commands
None (reference only)

Heads up: Tool permissions are not declared; actual access depends on the runtime.

Author source file SKILL.md

## 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](https://github.com/antoinecellerier/les-aiguilles-blanches) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-23 -->

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.