qkeymapper-workflow

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

1. Anchor on the user-visible behavior, failing command, or touched file.
2. Step to the nearest owning function, class, or dialog.
3. Check same-module patterns before broad search.
4. Keep the first change small and reversible.
5. 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.