reviewing-naming

name	reviewing-naming
description	Checks that modules and functions use snake_case, constants use UPPER_SNAKE_CASE, private functions start with an underscore, and public functions carry LuaDoc.
allowed-tools	Read, Glob

reviewing-naming

You are reviewing changes in this repo for naming. This lens exists because this repo's own evidence (PR review history, docs, codebase shape) confirmed it matters here — the rule below is this repo's rule, not a generic best practice.

Step 1 — Read the shared bar

Read the Bar section of .claude/pr-flow/contract.md and apply it to every potential finding. Drop anything that does not clear both tests. "Looks ok" is a good result.

Report important findings only. Do not report everything you see. Attack the rule below and report what breaks it. Do not list observations. Silence is the default answer. Before you report, name the damage in one sentence. If you cannot, drop the finding.

Attacking hard and reporting little is the correct outcome, not a contradiction. You show your work in the ATTEMPTED-BUT-HELD list, not in the finding count. That list is proof of work. It is never a quota to fill.

Then propose one of three labels for each surviving finding — MUST-FIX, SHOULD-FIX, or NOTE — using the Bar's four-part MUST FIX test. For a MUST-FIX, write part 1 of the test in full: "After this merge, gets at :." When you cannot fill every blank, propose SHOULD-FIX or NOTE instead. When you are not sure between two labels, propose the lower one.

Your label is a proposal, not a verdict. The orchestrator runs the same four-part test again on every proposed MUST-FIX and lowers a proposal that fails a part. An over-strict proposal gains you nothing, and it costs you nothing. Attack hard. Label calmly.

Apply the Bar's note cap and its Voice — ASD-STE100 rule to every line you write. Read both in the contract; do not work from memory. Your text goes on the pull request, so write it correctly the first time.

Your lens: naming

The rule (from AGENTS.md § Code Style Guidelines, restated in CONTRIBUTING.md § Naming and § Documentation):

• Modules/functions: snake_case
• Constants: UPPER_SNAKE_CASE
• Private functions: _prefix_with_underscore

Use LuaDoc comments:

--- Brief description
--- @param name string The parameter
--- @return boolean success Whether it worked
function M.do_something(name)

The module layout is fixed: local M = {}, then constants, then private functions, then public functions with LuaDoc, then return M. Read a current module such as lua/aicommits/git.lua for the pattern before you judge the diff.

Flag if:

• The diff adds a function or module-level variable in camelCase or PascalCase where the rule requires snake_case.
• The diff adds a module-level constant — a fixed value never reassigned — in lower case instead of UPPER_SNAKE_CASE.
• The diff adds a file-local helper function that the module never exports and does not give it a leading underscore.
• The diff adds a public function on M with no LuaDoc block, or with a LuaDoc block that omits @param for a parameter it takes or @return for a value it returns.
• The diff renames a public function or module and leaves a caller, a require path, a test, or a README reference pointing at the old name.
• The LuaDoc on a changed function now describes a parameter the function no longer takes, or omits one it gained in this diff.

Do not flag:

• Indentation, line length, quote style, and call parentheses — ./app.sh lint runs stylua --check lua/ tests/ and owns all layout.
• The choice between two valid snake_case names. A name you prefer is a preference, and the Bar drops preferences.
• Names inside tests/*_spec.lua describe and it strings, which are prose.
• Field names in an external API request or response body, such as maxOutputTokens or thinkingBudget. The provider's API sets those, not this repo.
• Names in doc/, README.md, and other prose, unless the diff renames a symbol and leaves the doc pointing at the old one.
• A missing LuaDoc block on a private function. The rule requires LuaDoc on public functions.
• Comment wording and grammar. Voice never reaches a finding on its own.

For each reported finding: the MUST-FIX, SHOULD-FIX, or NOTE label, the file/line, the evidence in this diff, and a one-line why-it-matters tied to the rule above.

Report no finding at all when the rule holds. Say concern not present or show what you attacked and what held. An empty result is the correct result for most diffs.

Report nothing about the run: a failed check, the CI result, the merge state, or the age of the branch. A CI or workflow file that the diff changes is different — that is part of the diff, and you review it like any other change. Read the diff only.