**TL;DR:** Point the ref command at the exact documented name. "unable to resolve reference to" means the ref names something doxygen never documented - a typo, a missing namespace qualifier, or a target excluded from the build. Use the fully qualified name, confirm the target page exists in the output, and fall back to plain text when the target is intentionally undocumented.

```text
warning: unable to resolve reference to 'ConfigParser' for ref command
```

1. Find every broken reference:
   ```
   doxygen Doxyfile 2>&1 | grep "unable to resolve reference"
   ```
   Expected: one line per broken ref, naming the target doxygen could not find.
2. Check whether the target is documented at all: search the generated HTML output for the symbol name. If nothing matches, the target was never documented.
3. Fix the ref to the fully qualified name, for example `docs::ConfigParser` instead of the bare `ConfigParser`.
4. Re-run:
   ```
   doxygen Doxyfile
   ```
   Expected: the warnings are gone, and the link in the HTML output points at the target's page.
5. If the target lives in excluded code (an `EXCLUDE` pattern or an undocumented file), replace the ref with plain text - linking at an undocumented target will never resolve.

## Use this when
- doxygen warns "unable to resolve reference to" for a ref command
- A cross-reference in the docs renders as dead text
- You renamed or moved a class and the old references broke

## Not for this skill when
- The warning is "documented symbol was not declared or defined" - that is a stale comment block, a different fix
- The target should be documented but is not - fix the target's own documentation first
- Automatic linking already handles the name - plain words that match documented symbols link without an explicit ref

## Variant phrasings
- "doxygen unable to resolve reference"
- "doxygen ref command unresolved"
- "warning: unable to resolve reference to"

## Why it happens
A ref is an explicit link: doxygen looks up the exact name you give it in the documented symbol table. A typo, a missing namespace qualifier, or a target that was never documented (or was excluded) leaves the lookup with nothing to point at.

## Edge cases
- Overloaded names can resolve to the wrong overload; qualify with the class or namespace to disambiguate.
- Members of undocumented classes cannot be reference targets even if the member itself has a comment.
- Case matters: `ConfigParser` and `configParser` are different targets.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_xGlyufiyU_Z_QeB2saSp7A