| name | doc-read-navigate |
| description | Before writing new code — search existing implementations, topical audits, READMEs, file-header caveats |
Before You Write — Check What Exists
- Search topical audits:
doc/TopicalAudit/*.md — one file per scientific topic, lists all implementations across languages with status and parity
- Search CODEMAP.md (if exists): file locations and module relationships
- Grep codebase: search for function/class names matching your planned implementation
- Read README.md in the target folder — may describe what's already there
- Read file/module headers you will extend — especially Open issues / caveats (design rationale, duplicate variants, ordering deps, known limitations)
Decision
- Found exact match: reuse it. Don't duplicate.
- Found similar: generalize it instead of writing new. If generalization risks breaking existing code: stop and report for approval.
- Found duplicate variants (noted in headers/caveats): use the one your app already uses; don't unify without approval.
- Found nothing: proceed, but document post-implementation (see
doc-task-summary skill).
Separation of Concerns Check
Before writing, verify your plan doesn't mix:
- Compute logic with plotting/diagnostics
- Backend with GUI/CLI
- Test scripts reimplementing shared module functions
If you need plotting/debugging: check for shared utilities first (e.g., pyBall/plot_utils.py, TestUtils.py).
Where to Find Things
doc/TopicalAudit/ — cross-language implementation maps per scientific topicdoc/AGENTs/skills/ — task-specific skills (debugging, OpenCL, parity, etc.)doc/AGENTs/protocols/ — domain-specific protocols (forcefields, topology, QM)README.md in any folder — local index of contents- Source file headers — essence, design notes, and caveats at top of modules you touch
