Qkeymapper Workflow

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

QKeyMapper workspace memory routing

When self-improving-agent is invoked for QKeyMapper work, the repository is the only persistence location for QKeyMapper-specific experience. Do not create or modify the global self-improving-agent installation's memory/ directory.

1. Read .agents/context/project-memory.md before recording a lesson.
2. Record durable, reusable QKeyMapper decisions, pitfalls, and verified patterns in .agents/context/lessons/. Keep task transcripts, temporary status, and sensitive data out of the repository memory.
3. Add every new lesson to .agents/context/lessons/MEMORY.md so future QKeyMapper sessions can discover it.
4. Update .agents/context/project-memory.md only when the shared memory routing or other high-level project guidance changes.

The .agents/context/ directory is version-controlled workspace knowledge and must be the source used for remote synchronization.

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.