| name | qkeymapper-workflow |
| description | QKeyMapper playbook for planning, implementation, debugging, and validation in this repo. |
| when_to_use | When planning a change, implementing a feature, debugging an issue, or validating a fix in this project. Also when the user asks about floating button behavior, key mapping logic, Forza mode, dialog UI changes, serialization, or mentions QKeyMapper. |
QKeyMapper Workflow
Use this skill for repo-specific work in QKeyMapper. Keep scope narrow, reuse existing architecture, and validate the smallest slice that proves the change.
Start here
- Anchor on the user-visible behavior, failing command, or touched file.
- Step to the nearest owning function, class, or dialog.
- Check same-module patterns before broad search.
- Keep the first change small and reversible.
- Before editing, identify a unique anchor for the exact snippet; if the file has repeated similar blocks, do not patch until the target is uniquely disambiguated by nearby literal text or line context.
Core files
- qkeymapper.cpp / qkeymapper.h
- qkeymapper_worker.cpp / qkeymapper_worker.h
- qkeymapper_constants.h
- qitemsetupdialog.cpp / qitemsetupdialog.h
- qfloatingbuttonsetupdialog.cpp / qfloatingbuttonsetupdialog.h
- qkeymapper.ui
- qkeymapper_qt_compat.h
- QKeyMapper.pro
Module guidelines
- Dialog/UI: update load, apply, save, and restore together; if generated UI members are involved, check for a source-tree ui_*.h shadow file first.
- Floating Button: treat constants, worker state, dialog load/apply, runtime visuals, and save/restore as one pipeline; watch resize loops; validate the smallest slice.
- Forza/runtime mapping: keep legacy and new syntax on the same runtime path; verify press/release ordering and per-player state transitions; add DEBUG_LOGOUT_ON only at the exact transition point.
- Serialization/settings: keep keymapdata.ini and Save Setting paths in sync; check load/apply/save/recover paths together.
Qt version compatibility
- Code must compile on both Qt 6.8.3 and Qt 5.12.10 from a single source tree. When an API differs between versions, add a compatibility wrapper in
qkeymapper_qt_compat.h — avoid scattering #if QT_VERSION checks throughout the codebase.
Validation
- Use the build directory under QKeyMapper/build/ (e.g., Desktop_Qt_6_x_x_MSVC2022_64bit-Release) for Qt/MSVC validation. Check the actual directory name at build time — it varies with the Qt version.
- Prefer targeted object builds over full rebuilds.
- If compile errors mention Ui::QKeyMapper members, first check for stray source-tree ui_qkeymapper.h.
- Use build-directory generated ui_*.h.
- If qkeymapper.cpp compiles but behavior is still suspect, do one follow-up link build or the smallest runtime check.
- Do not spend multiple iterations inventing new jom commands; use the known build-directory workflow first. If a jom failure is due to environment, path, or quoting uncertainty, stop after one retry and hand the validation back to the user.
- After any patch, verify the edit took effect in the right place before moving on — for example, grep for the changed line or check that a related symbol reference resolves correctly. If the edit landed wrong, repair it in the same slice; do not widen scope or touch other files.
Style
- Keep scope narrow.
- Reuse existing architecture.
- New comments in English.
- No .ts edits unless asked.
- Keep Qt/C++ source UTF-8 without BOM.
Translation
- When adding or modifying
tr(...) strings, provide Chinese and Japanese translation recommendations alongside the English original. Present each string as a three-row table for readability: | English | <original> | / | 中文 | <translation> | / | 日本語 | <translation> |.
Continuous improvement
After completing a task in this skill — especially when the user corrects you, a command fails, or you discover a better approach — invoke the self-improving-agent skill to extract patterns and update memory. This closes the loop so future sessions benefit from what was learned.
