aiwaku.nvim lua.instructions.md

Lua Code Generate and Review Instructions

Simplicity and minimal changes

• Prefer the simplest correct solution. Flag over-engineering, unnecessary abstraction, or boilerplate.
• Change only what the task requires. Do not refactor, rename, or reorganise unrelated code in the same commit.
  • Exception: refactor only when it removes genuine duplication or directly supports the requested change. Follow the KISS principle.
• Remove unnecessary intermediate variables when the expression is already readable.
• Flatten nested conditionals: prefer multiple early returns over deeply nested if blocks.
• An extra line of code is not automatically better than a dense one; judge by comprehension, not line count.
• DO not do any breaking changes if anyway possible, if NOT always confirm first.

No redundant guards

• If a value is validated earlier in the same function, do not re-check it again further down.
• Trust established invariants: once state.config, a buffer handle, or a window handle is confirmed valid at entry, deeper callees in the same execution path need not repeat that nil-check.
• Each guard must appear exactly once per execution path. Duplicate guards are noise and obscure the real logic.
• When a guard makes a subsequent check structurally impossible (e.g., early return on nil), remove the redundant check rather than leaving it as defensive dead code.

Execution path coverage

• Every branch must be reachable and intentional. Dead code after a return statement is a bug.
• Trace all guard/early-return combinations and verify the happy path is clear and direct.
• For async flows wrapped with plenary.async.void, ensure every error path either returns cleanly or notifies the user — coroutines must not be silently abandoned.
• When adding a new code path, verify existing guards still cover it or add the appropriate guard once at the right point.

LuaDoc annotations

Annotations drive type-checking and IDE support. Keep them accurate.

• All public module functions (every key returned in M) must carry ---@param and ---@return annotations.
• When constructing a table that satisfies a ---@class definition, add ---@type ClassName on the line before the return statement.
• Functions wrapped in plenary.async.void must be annotated ---@async.
• Optional fields use the ? suffix: ---@field foo? string.
• lua/aiwaku/types.lua is the single source of type truth. Do not duplicate class shapes inline in implementation files; reference the types instead.
• Module-level ---@class or ---@module doc blocks describe the module's public surface.
• Do not add annotations for private/local functions unless their signatures are non-obvious.