Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 15 additions & 1 deletion .agents/agents/autostory-code.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
14 changes: 13 additions & 1 deletion .agents/agents/reviewer.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,18 @@ being restated.
`gh pr review <PR> -R dayfine/Arduino-Source --comment --body-file <file>` and verify with
`gh pr view <PR> -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.
27 changes: 27 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand Down
10 changes: 10 additions & 0 deletions skills/cpp-style-review/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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: <type/function/test> -> <replacement>.

Not checked here: correctness (run /code-review), code_health limits, CI.
```

Expand Down
Loading