---
name: panopainter-code-navigation
description: Use when working in the PanoPainter repository and Codex needs to follow C++ symbols, inspect declarations/definitions/hover info, list matching symbols, use regex symbol/detail/path filters, or reduce broad rg searches during refactors. Prefer this before text search for symbol navigation, regex symbol-family lookup, service-interface wiring, override/implementation lookup, or legacy-to-component boundary tracing.
---

# PanoPainter Code Navigation

Use the repo's clangd helper before broad text searches when a task depends on C++
symbol identity rather than plain text. This is required for PanoPainter C++
refactors that depend on symbol families, declarations/definitions, override
groups, service/interface wiring, or platform/backend boundaries.

## Workflow

1. Confirm the current workspace is `D:\Dev\panopainter`.
2. Use this skill before broad text search when a C++ refactor depends on
   symbol identity, a symbol family, signatures, override groups, or
   platform/backend boundary paths.
3. Prefer reliable lookups:
   - `symbols`
   - `definition`
   - `declaration`
   - `implementation`
   - `hover`
4. Use regex filters when looking for symbol families, generated-style names, or
   backend/platform boundary patterns:
   - `--name-regex` filters flat symbols by `qualifiedName`.
   - `--detail-regex` filters flat symbols by detail/signature text.
   - `--path-regex` filters definition/declaration/implementation/reference
     locations by path or URI.
   - Regex matching is case-insensitive by default; add `--no-ignore-case` for
     case-sensitive checks.
   - Run `python scripts/dev/clangd_nav.py self-test` if the helper changed or
     regex output looks surprising.
5. Use `references` only as advisory:
   - Pass `--background-index` for broader best-effort references.
   - Pass `--allow-incomplete-references` only for explicitly current-translation-unit-only references.
   - Never treat incomplete reference output as proof that no other users exist.
6. Keep output small with `--name`, regex filters, and `--max-results`.

## Commands

```powershell
python scripts/dev/clangd_nav.py symbols --file src/app_core/brush_ui.h --name execute_brush
python scripts/dev/clangd_nav.py symbols --file src/app_core/brush_ui.h --name-regex "execute_.*preset"
python scripts/dev/clangd_nav.py symbols --file src/app_core/document_export.h --detail-regex "Export.*Plan"
python scripts/dev/clangd_nav.py definition --file src/node_panel_brush.cpp --line 511 --column 39
python scripts/dev/clangd_nav.py hover --file src/app_core/brush_ui.h --line 783 --column 60
python scripts/dev/clangd_nav.py references --file src/app_core/brush_ui.h --line 783 --column 45 --path-regex "src[\\/]app_core"
python scripts/dev/clangd_nav.py self-test
```

The helper uses `PP_CLANGD_COMPILE_COMMANDS_DIR` when set, otherwise it checks
known Ninja build trees such as `out/build/windows-clangcl-asan` and
`out/build/android-arm64`. Pass `--compile-commands-dir` when using another
configured build tree.

Use normal `rg` for non-symbol text, docs, build files, generated command names,
or when clangd cannot parse the relevant file.
