diff --git a/.agents/agents/autostory-code.md b/.agents/agents/autostory-code.md index b057d80034..d41ea7329f 100644 --- a/.agents/agents/autostory-code.md +++ b/.agents/agents/autostory-code.md @@ -83,7 +83,21 @@ being restated. - **Your stage ends at the PR.** Never wait for CI or any other event after pushing: report the PR number and tip SHA and stop; the dispatcher waits for CI (`.agents/rules/long-chain-ownership.md`). +## Simplicity + +Before writing code, read AGENTS.md "Code conventions for PR branches", Simplicity. In short: + +- Write the smallest version's shape (functions, types, rough line count) in the first commit + message; if `git diff --stat` passes about 1.5x that, stop and cut. +- Free functions unless there is state to own; one constructor; nothing that exists only for tests. +- No result, match or wrapper type for one caller: the existing type or `std::optional`. +- No branch no caller can reach; no null check on what the caller guarantees. +- Move, don't copy-and-keep: an extracted site loses the code in the same PR. +- Each test names the bug it catches; a refactor or extraction gets 1-3 tests. +- Before push, list every new type, function and parameter with why it can't be removed, and put + the estimate and the actual `--stat` in your report. + ## Report -PR number, tip SHA, code-health failure count, which files you compiled and the exit codes, the CI +PR number, tip SHA, size estimate vs `git diff --stat`, code-health failure count, which files you compiled and the exit codes, the CI run started (or dispatched). Nothing else. diff --git a/.agents/agents/reviewer.md b/.agents/agents/reviewer.md index f07bc55408..f9e8b2ba95 100644 --- a/.agents/agents/reviewer.md +++ b/.agents/agents/reviewer.md @@ -67,6 +67,18 @@ being restated. `gh pr review -R dayfine/Arduino-Source --comment --body-file ` and verify with `gh pr view -R dayfine/Arduino-Source --json reviews`. +## Simplicity + +Check the diff against AGENTS.md "Code conventions for PR branches", Simplicity, and put a +`## Simplicity` part in every review: + +- a size estimate of the simplest version that does the job (`+N/-M`) next to the PR's actual; +- every removable type, function, constructor, overload, parameter, branch and test, one line each + with what replaces it: a class where free functions do, a test-only constructor, a one-caller + result type, an unreachable null check, code copied instead of moved, a test that names no bug. + +When the actual diff is more than about 1.5x the estimate, the verdict is `NEEDS_REWORK`. + ## Report -PR number, reviewed SHA, verdict, the review's URL, and the count of findings by severity. +PR number, reviewed SHA, verdict, size estimate vs actual, the review's URL, and the count of findings by severity. diff --git a/AGENTS.md b/AGENTS.md index 71fbc7b1b8..7466ab3b53 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -222,6 +222,33 @@ See [pokemon_sv/PR_WORKFLOW.md](pokemon_sv/PR_WORKFLOW.md). In short: ## Code conventions for PR branches +- **Simplicity: read before writing code.** Write the smallest change that does the job; every + extra type, overload and test is review time someone spends for free. (Trigger: fork PR #660 + came out +526/-82 where about +240/-60 did the job.) + - **Shape first.** Before coding, write the smallest version's shape (functions and types, rough + line count) in the plan or the first commit message: it gives the diff a budget. + - **Budget.** When `git diff --stat` passes about 1.5x the estimate, stop and cut before going on: + growth past the budget is almost always extras, not need. + - **Free functions over a class** unless there is state to own: a class with no state is two + functions plus ceremony. + - **One constructor.** No constructor, overload or parameter that exists only for tests; inject + the fake through the one real constructor, so tests run the code callers run. + - **No new types for one caller.** No result, match or wrapper type with a single user; return + the existing type or `std::optional`, so readers learn nothing new. + - **No unreachable branches.** No defensive check no caller can reach and no null check on a + reference or pointer the caller guarantees: dead branches read as real cases. Guard input + that really comes from outside (screens, files, users). + - **Move, don't copy-and-keep.** When code is extracted, the old site loses it in the same PR; + two copies drift. + - **No forward declarations** (see Dependencies): include the real header. + - **Tests earn their place.** Each test names the bug it catches. No tests of getters, the + standard library, or the code's own arithmetic or constants restated; a test that passes for + any implementation is not added. A refactor or extraction PR gets 1-3 tests: behavior is + unchanged, so most cases are already covered. + - **No header widened for tests.** Test through the public function, or keep the helper in the + .cpp's anonymous namespace (code health `test_only_api`). + - **Self-check before push.** List every new type, function and parameter with why it can't be + removed, and compare `git diff --stat` with the estimate; cut what has no answer. - **Match the repo's style:** - comments explain why, at the density of the surrounding code - `virtual ... override` diff --git a/skills/cpp-style-review/SKILL.md b/skills/cpp-style-review/SKILL.md index 02b0ccef12..ad7e50732a 100644 --- a/skills/cpp-style-review/SKILL.md +++ b/skills/cpp-style-review/SKILL.md @@ -81,6 +81,13 @@ number in the references file): nesting the change adds (T10). 11. **Placement** - single-use helper exported to a shared module, game code in shared code, include order (T9); forward declarations (strict ban). +12. **Simplicity** (AGENTS.md "Code conventions for PR branches", Simplicity) - + a class with no state where free functions do; a second constructor, + overload or parameter only tests use; a result/match/wrapper type with one + caller; a branch or null check no caller can reach; extracted code also + kept at the old site; a test that names no bug, or more than 1-3 tests on + a refactor. Estimate the simplest version's size (`+N/-M`) and list every + removable type, function and test with what replaces it. ## Step 4: Verify every finding before reporting it @@ -117,6 +124,9 @@ Rank by severity, cap at about 10 findings; say how many minor ones you dropped. ### nit ... +### simplicity +Simplest version: about +N/-M (actual +X/-Y). Removable: -> . + Not checked here: correctness (run /code-review), code_health limits, CI. ```