Two files, one repository

danielvm-git/bigpowers ships 4 formats across 40 indexed files. The question worth asking is whether the second one says anything the first does not.

CompareCLAUDE.md ↔ GEMINI.md CLAUDE.md ↔ AGENTS.md CLAUDE.md ↔ Cursor rules GEMINI.md ↔ AGENTS.md GEMINI.md ↔ Cursor rules AGENTS.md ↔ Cursor rules

A · GEMINI.md · 580 words B · .cursor/rules/audit-code.mdc · 1441 words

What each file covers, counted
Dimension	Shared	Only in A	Only in B	Overlap
Sections	0	9	26	0%
Commands	0	1	2	0%
Section tags	2	2	6	20%

What each file covers

Sections

0 shared · 9 only in A · 26 only in B

− bigpowers — Gemini CLI
− Project
− Commands
− Architecture
− Conventions
− Never
− Token Management
− Agent Rules
− bts toolchain
+ Audit Code
+ Look-here-first (churn heuristic)
+ Modes
+ Checklist
+ Supply Chain & Security
+ Provenance & Metadata
+ Law of Demeter
+ CONVENTIONS.md Compliance
+ Scope
+ Boy Scout Rule
+ Types and Safety
+ Test Coverage
+ SOLID and Heuristics
+ Refactoring Smells (Fowler)
+ Code Style (CONVENTIONS.md)
+ Red Flags
+ Output
+ Verify
+ Handoff
+ Clean Code Heuristics (Chapter 17)
+ Comments (C)
+ Environment (E)
+ Functions (F)
+ General (G)
+ Naming (N)
+ Tests (T)

Commands

0 shared · 1 only in A · 2 only in B

− npm install -g bigpowers && bigpowers setup
+ gh issue create
+ npm test

Section tags

2 shared · 2 only in A · 6 only in B

− do-not
− agent-behaviour
+ test
+ lint-format
+ types
+ testing-strategy
+ security
+ docs
setup
code-style

Line diff

+163 added−55 removed21 unchanged11.4% identical

danielvm-git/bigpowers · GEMINI.md

@@ −1 @@

1# bigpowers — Gemini CLI

3> **Auto-generated** by `sync-skills.sh` from `CLAUDE.md`. Edit CLAUDE.md, not this file.

5Read CONVENTIONS.md before any GitHub or git operation.

7## Project

9bigpowers — 58 agent skills for spec-driven, test-first software development by solo developers.

10Stack: Markdown / Bash (documentation-based; skills integrate with Claude Code, Cursor, Gemini CLI)

12## Commands

14| Action | Command |

15|---------|---------|

16| Install | `npm install -g bigpowers && bigpowers setup` |

17| Run | `bash scripts/sync-skills.sh` |

18| Test | N/A (documentation project) |

19| Build | `bash scripts/install.sh` (from source) |

20| Lint | `bash scripts/sync-skills.sh` (validates SKILL.md syntax) |

22## Architecture

24Collection of 58 verb-noun skills, each with a SKILL.md source file and supporting documentation. Includes Verify phase and profiles/. The sync-skills.sh script auto-generates artifacts for Cursor (.cursor/rules) and Gemini CLI (.gemini/extensions/bigpowers/) from SKILL.md sources. All planning and spec output goes to specs/ at the project root.

26## Conventions

28- Skill directories use verb-noun naming (two words, kebab-case)

29- Every skill has a single SKILL.md file as its source of truth

30- All planning/spec output goes to specs/ at project root

31- Artifacts in .cursor/rules and .gemini/ are auto-generated; edit SKILL.md, not artifacts

32- Run sync-skills.sh after any SKILL.md changes to regenerate artifacts

34## Never

36- Never edit .cursor/rules or .gemini/extensions/ directly — these are generated files

37- Never create a skill without a SKILL.md file and proper verb-noun naming

38- Never push changes without running sync-skills.sh first

40## Token Management

42- **Auto-Terse**: When a session exceeds 20 turns or the context window feels "heavy" (latency increasing), you MUST switch to `terse-mode` to save tokens.

43- **Context Compaction**: Every 10 turns, summarize the current session state and implementation decisions into a short, high-density note.

44- **Minimal Output**: Prefer text-only output for simple status; use `web_fetch` or `run_shell_command` only for evidence.

46## Agent Rules

48- **Workflow Mandate:** You MUST use the bigpowers skills (e.g., `plan-work`, `develop-tdd`, `craft-skill`) to perform tasks. DO NOT write code directly in response to a user prompt like "build this feature".

49- Read specs/ and CONVENTIONS.md before writing code.

50- Write the minimum code that solves the stated problem. Nothing extra.

51- Never refactor, rename, or reorganize code outside the task scope.

52- Run tests after every change. Show evidence before declaring done.

53- One clarifying question beats a wrong assumption baked into 200 lines.

54- All written output (plans, specs, investigations) goes in specs/.

56## bts toolchain

58`bts` is installed. Prefer its verbs over ad-hoc shell commands.

60| Task | Command | Avoid |

61|------|---------|-------|

62| Search code | `bts find --print <pattern>` | grep / find / cat |

63| Interactive search | `bts find <pattern>` | manual grep pipes |

65| Repo map | `bts map` | listing files by hand |

66| Library docs | `bts docs <lib>` | guessing from training data |

67| Package source | `bts src <pkg>` | git clone |

68| Toolchain health | `bts doctor` | which / command -v |

70**Rules**

71- Search with `bts find` before opening files to locate a symbol or pattern.

72- Pipe anything > 200 lines through `bts compress` before adding to context.

73- Run `bts map` when asked for a repo overview.

74- Use `bts docs <lib>` before answering questions about library APIs.

75- If a tool is missing, say so and run `bts doctor` — do not silently substitute.

danielvm-git/bigpowers · .cursor/rules/audit-code.mdc

@@ +1 @@

1---

2description: "Self-review checklist for the coding agent to run before dispatching a reviewer. Checks CONVENTIONS.md compliance, Boy Scout Rule, test coverage, types, and SOLID. Produces a pass/fail checklist. Use before request-review, before committing, or when user asks for a code quality check."

3alwaysApply: false

4---

6# Audit Code

7> **HARD GATE** — **HARD GATE** — Audit must check for: bugs (correctness), security, performance, and clarity. Do NOT skip security review if the code touches user data, auth, or external APIs.

10Run this self-review before asking anyone else to look at the code. The goal is to catch everything that is clearly wrong or missing — so the reviewer can focus on design and architecture, not hygiene.

12**Distinct from `request-review`:** This is the coding agent checking its own work. No second agent is involved. Run this first; run `request-review` after this passes.

14## Look-here-first (churn heuristic)

16Before the checklist, rank changed files by git churn and review **high-churn hotspots first** — they carry the most latent risk regardless of diff size.

18```bash

19bash scripts/bp-churn-rank.sh --since 90.days --limit 15

20```

22Apply the full checklist to churn-ranked files in descending order. Files with zero recent commits but large diffs still get reviewed; churn only sets priority, not scope.

24## Modes

26- Default: full checklist

27- --quick: Run only Supply Chain and Test Coverage. Use for changes under 50 LOC.

28- --gate: Non-interactive mode for automated CI gating (used by build-epic step 6). Exit with non-zero status code (`exit 1`) on ANY checklist failure; `exit 0` only if ALL items pass. Produces a compact pass/fail summary to stderr. On failure, list every ✗ item with reason.

29- --parallel: Run checklist sections in **isolated git worktrees** (e45s18) so concurrent checks cannot corrupt each other's working tree:

31```bash

32bash scripts/lib/parallel-review-worktrees.sh audit-code

33```

36## Checklist

38### Supply Chain & Security

40- [ ] slopcheck run for new dependencies; packages tagged in plan-work: `[OK]`, `[SUS]`, or `[SLOP]`

41- [ ] No `[SLOP]` packages without documented human approval

42- [ ] No secrets in diff (`sk-`, `ghp_`, `AKIA`, `.env` values) — see `guard-git` patterns

43- [ ] OWASP Top 10 spot-check: injection, broken auth, sensitive data exposure, misconfiguration (see `docs/references/security-threats.md`)

44- [ ] Security: diff scanned — no unaddressed HIGH findings (or deviations documented in `specs/security/EXCEPTIONS.md`)

46### Provenance & Metadata

48- [ ] New plan artefacts include `type:` and `context:` metadata

49- [ ] Implementation steps reference ADR or commit SHA where decisions were made

51### Law of Demeter

53- [ ] No method chains through unrelated objects (e.g. `a.getB().getC().doX()`)

54- [ ] Collaborators talk to immediate neighbors only; law violations need explicit justification

56### CONVENTIONS.md Compliance

58- [ ] All output files are in `specs/` (no docs written to project root)

59- [ ] No `gh issue create` calls anywhere in new/modified skills or scripts

60- [ ] `gh` used only for PRs and repo clone operations

61- [ ] No GitHub REST API called directly (no curl/fetch to api.github.com)

63### Scope

65- [ ] Changes are limited to what was asked — nothing extra refactored or reorganized

66- [ ] No speculative features added

67- [ ] No files touched outside the stated scope

68- [ ] **Discovered defects:** Reproducible gate failures (Preflight, CI, golden suite) require fix-or-log — `quick-fix` or `fix-bug` — even when "outside" the story scope. Scope-minimization does not waive Always Green.

69- [ ] Boy Scout Rule applies to files opened to fix a gate failure; it does not excuse skipping red Preflight

71### Boy Scout Rule

73- [ ] Every file I touched is cleaner than when I found it

74- [ ] No dead code left behind

75- [ ] No commented-out code blocks

77### Types and Safety

79- [ ] No `any` types introduced (TypeScript) or untyped public functions (Python/Go/etc.)

80- [ ] No `@ts-ignore` or `// eslint-disable` added

81- [ ] No `as unknown as X` casts that bypass type safety

83### Test Coverage

85- [ ] Every new function has at least one test

86- [ ] Every bug fix has a regression test

87- [ ] Tests verify behavior through public interfaces (not implementation details)

88- [ ] Tests are F.I.R.S.T compliant (per CONVENTIONS.md §Tests; use `enforce-first` if unsure)

90### SOLID and Heuristics

92- [ ] Single Responsibility: no function or module doing two unrelated things

93- [ ] Open/Closed: extended through interfaces, not by modifying stable code

94- [ ] Dependency Inversion: dependencies injected, not imported globally where avoidable

95- [ ] **Chapter 17 Heuristics**: Code is free of smells documented in `audit-code/HEURISTICS.md` (G, N, C, T)

97### Refactoring Smells (Fowler)

99Explicitly name any detected smells: Mysterious Name, Duplicated Code, Feature Envy, Data Clumps, Primitive Obsession, Message Chains, Middle Man.

100

101### Code Style (CONVENTIONS.md)

102

103- [ ] Functions: 4–20 lines; split if longer

104- [ ] Functions: descend exactly one level of abstraction (The Stepdown Rule / G34)

105- [ ] Files: under 300 lines (ideally 200–300)

106- [ ] Names: specific and unique (grep returns < 5 hits for each name)

107- [ ] No duplication — shared logic extracted (DRY / G5)

108- [ ] Early returns over nested ifs; max 2 levels of indentation

109- [ ] Conditionals: expressed as positives (G29)

110- [ ] Comments explain WHY, not WHAT

111

112### Red Flags

113

114Before reporting, name any rationalization you caught yourself making for skipping a checklist item. Silence is not acceptable — if you skipped an item, state the reason explicitly.

115

116## Output

117

118Report the checklist with ✓ / ✗ per item. For each ✗, describe what needs to be fixed.

119

120If all items pass: suggest running `request-review` for an independent second opinion.

121If any items fail: fix them before proceeding.

122

123In `--gate` mode, print one summary line per checklist section (`PASS Supply Chain` / `FAIL Provenance (2 items)`). Exit `0` only if all PASS. Write full report to `specs/verifications/AUDIT-<epic>-<story>.md`.

124

125## Verify

126

127→ verify: `test -f CONVENTIONS.md && test -d skills/enforce-first && test -d skills/request-review`

128

129## Handoff

130

131Gate: READY -> next: commit-message

132Writes: state.yaml handoff.next_skill = commit-message

133

134

135

136

137

138

139---

140

141# Clean Code Heuristics (Chapter 17)

142

143A summary of Robert C. Martin's catalogue of code smells and heuristics, used as the technical benchmark for `audit-code`.

144

145## Comments (C)

146- **C1: Inappropriate Information**: Comments should only hold technical notes. Metadata (author, change history) belongs in Git.

147- **C2: Obsolete Comment**: Update or delete comments that are no longer accurate.

148- **C3: Redundant Comment**: Don't describe code that adequately describes itself (e.g., `i++; // increment i`).

149- **C4: Poorly Written Comment**: If you write a comment, spend time making it the best it can be.

150- **C5: Commented-Out Code**: Delete it. Git remembers it.

151

152## Environment (E)

153- **E1: Build Requires More Than One Step**: Building should be a single trivial operation (e.g., `bash install.sh`).

154- **E2: Tests Require More Than One Step**: Running all tests should be one simple command (e.g., `npm test`).

155

156## Functions (F)

157- **F1: Too Many Arguments**: 0 is ideal, 1-2 is fine, 3 requires special justification. Never > 3.

158- **F2: Output Arguments**: Avoid them. If a function changes state, it should change the state of its owning object.

159- **F3: Flag Arguments**: Boolean arguments are a smell that the function does > 1 thing.

160- **F4: Dead Function**: Discard methods that are never called.

161

162## General (G)

163- **G1: Multiple Languages in One Source File**: Try to minimize the mixing of languages (e.g., HTML inside Java).

164- **G5: Duplication (DRY)**: **The root of all evil.** Every time you see duplication, it's a missed opportunity for abstraction.

165- **G6: Code at Wrong Level of Abstraction**: High-level concepts in base classes; low-level details in derivatives.

166- **G25: Replace Magic Numbers with Named Constants**: No "naked" numbers or strings.

167- **G28: Encapsulate Conditionals**: Prefer `if (shouldBePublished())` over complex boolean logic.

168- **G29: Avoid Negative Conditionals**: Prefer `if (buffer.shouldCompact())` over `if (!buffer.shouldNotCompact())`.

169- **G30: Functions Should Do One Thing**: If a function can be split into sections, it's doing too much.

170- **G31: Hidden Temporal Couplings**: If execution order matters, make the dependency explicit via arguments.

171- **G34: Functions Should Descend Only One Level of Abstraction**: The Stepdown Rule.

172

173## Naming (N)

174- **N1: Choose Descriptive Names**: Names should reveal intent and be updated as code evolves.

175- **N4: Unambiguous Names**: Names should make the working of a function/variable clear.

176- **N7: Names Should Describe Side-Effects**: Describe everything the function is or does.

177

178## Tests (T)

179- **T1: Insufficient Tests**: A test suite should test everything that could possibly break.

180- **T4: An Ignored Test Is a Question about an Ambiguity**: Document the reason for `@Ignore`.

181- **T5: Test Boundary Conditions**: Most bugs happen at the boundaries; test them exhaustively.

182- **T8: Test Coverage Patterns Can Be Revealing**: Analyze what code is *not* executed to find gaps.

183- **T9: Tests Should Be Fast**: Slow tests don't get run.

184

@@ −1 +1 @@

1−# bigpowers — Gemini CLI

1+---

2+description: "Self-review checklist for the coding agent to run before dispatching a reviewer. Checks CONVENTIONS.md compliance, Boy Scout Rule, test coverage, types, and SOLID. Produces a pass/fail checklist. Use before request-review, before committing, or when user asks for a code quality check."

3+alwaysApply: false

4+---

3−> **Auto-generated** by `sync-skills.sh` from `CLAUDE.md`. Edit CLAUDE.md, not this file.

6+# Audit Code

7+> **HARD GATE** — **HARD GATE** — Audit must check for: bugs (correctness), security, performance, and clarity. Do NOT skip security review if the code touches user data, auth, or external APIs.

5−Read CONVENTIONS.md before any GitHub or git operation.

7−## Project

10+Run this self-review before asking anyone else to look at the code. The goal is to catch everything that is clearly wrong or missing — so the reviewer can focus on design and architecture, not hygiene.

811

9−bigpowers — 58 agent skills for spec-driven, test-first software development by solo developers.

10−Stack: Markdown / Bash (documentation-based; skills integrate with Claude Code, Cursor, Gemini CLI)

12+**Distinct from `request-review`:** This is the coding agent checking its own work. No second agent is involved. Run this first; run `request-review` after this passes.

1113

12−## Commands

14+## Look-here-first (churn heuristic)

1315

14−| Action | Command |

15−|---------|---------|

16−| Install | `npm install -g bigpowers && bigpowers setup` |

17−| Run | `bash scripts/sync-skills.sh` |

18−| Test | N/A (documentation project) |

19−| Build | `bash scripts/install.sh` (from source) |

20−| Lint | `bash scripts/sync-skills.sh` (validates SKILL.md syntax) |

16+Before the checklist, rank changed files by git churn and review **high-churn hotspots first** — they carry the most latent risk regardless of diff size.

2117

22−## Architecture

18+```bash

19+bash scripts/bp-churn-rank.sh --since 90.days --limit 15

20+```

2321

24−Collection of 58 verb-noun skills, each with a SKILL.md source file and supporting documentation. Includes Verify phase and profiles/. The sync-skills.sh script auto-generates artifacts for Cursor (.cursor/rules) and Gemini CLI (.gemini/extensions/bigpowers/) from SKILL.md sources. All planning and spec output goes to specs/ at the project root.

22+Apply the full checklist to churn-ranked files in descending order. Files with zero recent commits but large diffs still get reviewed; churn only sets priority, not scope.

2523

26−## Conventions

24+## Modes

2725

28−- Skill directories use verb-noun naming (two words, kebab-case)

29−- Every skill has a single SKILL.md file as its source of truth

30−- All planning/spec output goes to specs/ at project root

31−- Artifacts in .cursor/rules and .gemini/ are auto-generated; edit SKILL.md, not artifacts

32−- Run sync-skills.sh after any SKILL.md changes to regenerate artifacts

26+- Default: full checklist

27+- --quick: Run only Supply Chain and Test Coverage. Use for changes under 50 LOC.

28+- --gate: Non-interactive mode for automated CI gating (used by build-epic step 6). Exit with non-zero status code (`exit 1`) on ANY checklist failure; `exit 0` only if ALL items pass. Produces a compact pass/fail summary to stderr. On failure, list every ✗ item with reason.

29+- --parallel: Run checklist sections in **isolated git worktrees** (e45s18) so concurrent checks cannot corrupt each other's working tree:

3330

34−## Never

31+```bash

32+bash scripts/lib/parallel-review-worktrees.sh audit-code

33+```

3534

36−- Never edit .cursor/rules or .gemini/extensions/ directly — these are generated files

37−- Never create a skill without a SKILL.md file and proper verb-noun naming

38−- Never push changes without running sync-skills.sh first

3935

40−## Token Management

36+## Checklist

4137

42−- **Auto-Terse**: When a session exceeds 20 turns or the context window feels "heavy" (latency increasing), you MUST switch to `terse-mode` to save tokens.

43−- **Context Compaction**: Every 10 turns, summarize the current session state and implementation decisions into a short, high-density note.

44−- **Minimal Output**: Prefer text-only output for simple status; use `web_fetch` or `run_shell_command` only for evidence.

38+### Supply Chain & Security

4539

46−## Agent Rules

40+- [ ] slopcheck run for new dependencies; packages tagged in plan-work: `[OK]`, `[SUS]`, or `[SLOP]`

41+- [ ] No `[SLOP]` packages without documented human approval

42+- [ ] No secrets in diff (`sk-`, `ghp_`, `AKIA`, `.env` values) — see `guard-git` patterns

43+- [ ] OWASP Top 10 spot-check: injection, broken auth, sensitive data exposure, misconfiguration (see `docs/references/security-threats.md`)

44+- [ ] Security: diff scanned — no unaddressed HIGH findings (or deviations documented in `specs/security/EXCEPTIONS.md`)

4745

48−- **Workflow Mandate:** You MUST use the bigpowers skills (e.g., `plan-work`, `develop-tdd`, `craft-skill`) to perform tasks. DO NOT write code directly in response to a user prompt like "build this feature".

49−- Read specs/ and CONVENTIONS.md before writing code.

50−- Write the minimum code that solves the stated problem. Nothing extra.

51−- Never refactor, rename, or reorganize code outside the task scope.

52−- Run tests after every change. Show evidence before declaring done.

53−- One clarifying question beats a wrong assumption baked into 200 lines.

54−- All written output (plans, specs, investigations) goes in specs/.

46+### Provenance & Metadata

5547

56−## bts toolchain

48+- [ ] New plan artefacts include `type:` and `context:` metadata

49+- [ ] Implementation steps reference ADR or commit SHA where decisions were made

5750

58−`bts` is installed. Prefer its verbs over ad-hoc shell commands.

51+### Law of Demeter

5952

60−| Task | Command | Avoid |

61−|------|---------|-------|

62−| Search code | `bts find --print <pattern>` | grep / find / cat |

63−| Interactive search | `bts find <pattern>` | manual grep pipes |

65−| Repo map | `bts map` | listing files by hand |

66−| Library docs | `bts docs <lib>` | guessing from training data |

67−| Package source | `bts src <pkg>` | git clone |

68−| Toolchain health | `bts doctor` | which / command -v |

53+- [ ] No method chains through unrelated objects (e.g. `a.getB().getC().doX()`)

54+- [ ] Collaborators talk to immediate neighbors only; law violations need explicit justification

6955

70−**Rules**

71−- Search with `bts find` before opening files to locate a symbol or pattern.

72−- Pipe anything > 200 lines through `bts compress` before adding to context.

73−- Run `bts map` when asked for a repo overview.

74−- Use `bts docs <lib>` before answering questions about library APIs.

75−- If a tool is missing, say so and run `bts doctor` — do not silently substitute.

56+### CONVENTIONS.md Compliance

57+

58+- [ ] All output files are in `specs/` (no docs written to project root)

59+- [ ] No `gh issue create` calls anywhere in new/modified skills or scripts

60+- [ ] `gh` used only for PRs and repo clone operations

61+- [ ] No GitHub REST API called directly (no curl/fetch to api.github.com)

62+

63+### Scope

64+

65+- [ ] Changes are limited to what was asked — nothing extra refactored or reorganized

66+- [ ] No speculative features added

67+- [ ] No files touched outside the stated scope

68+- [ ] **Discovered defects:** Reproducible gate failures (Preflight, CI, golden suite) require fix-or-log — `quick-fix` or `fix-bug` — even when "outside" the story scope. Scope-minimization does not waive Always Green.

69+- [ ] Boy Scout Rule applies to files opened to fix a gate failure; it does not excuse skipping red Preflight

70+

71+### Boy Scout Rule

72+

73+- [ ] Every file I touched is cleaner than when I found it

74+- [ ] No dead code left behind

75+- [ ] No commented-out code blocks

76+

77+### Types and Safety

78+

79+- [ ] No `any` types introduced (TypeScript) or untyped public functions (Python/Go/etc.)

80+- [ ] No `@ts-ignore` or `// eslint-disable` added

81+- [ ] No `as unknown as X` casts that bypass type safety

82+

83+### Test Coverage

84+

85+- [ ] Every new function has at least one test

86+- [ ] Every bug fix has a regression test

87+- [ ] Tests verify behavior through public interfaces (not implementation details)

88+- [ ] Tests are F.I.R.S.T compliant (per CONVENTIONS.md §Tests; use `enforce-first` if unsure)

89+

90+### SOLID and Heuristics

91+

92+- [ ] Single Responsibility: no function or module doing two unrelated things

93+- [ ] Open/Closed: extended through interfaces, not by modifying stable code

94+- [ ] Dependency Inversion: dependencies injected, not imported globally where avoidable

95+- [ ] **Chapter 17 Heuristics**: Code is free of smells documented in `audit-code/HEURISTICS.md` (G, N, C, T)

96+

97+### Refactoring Smells (Fowler)

98+

99+Explicitly name any detected smells: Mysterious Name, Duplicated Code, Feature Envy, Data Clumps, Primitive Obsession, Message Chains, Middle Man.

100+

101+### Code Style (CONVENTIONS.md)

102+

103+- [ ] Functions: 4–20 lines; split if longer

104+- [ ] Functions: descend exactly one level of abstraction (The Stepdown Rule / G34)

105+- [ ] Files: under 300 lines (ideally 200–300)

106+- [ ] Names: specific and unique (grep returns < 5 hits for each name)

107+- [ ] No duplication — shared logic extracted (DRY / G5)

108+- [ ] Early returns over nested ifs; max 2 levels of indentation

109+- [ ] Conditionals: expressed as positives (G29)

110+- [ ] Comments explain WHY, not WHAT

111+

112+### Red Flags

113+

114+Before reporting, name any rationalization you caught yourself making for skipping a checklist item. Silence is not acceptable — if you skipped an item, state the reason explicitly.

115+

116+## Output

117+

118+Report the checklist with ✓ / ✗ per item. For each ✗, describe what needs to be fixed.

119+

120+If all items pass: suggest running `request-review` for an independent second opinion.

121+If any items fail: fix them before proceeding.

122+

123+In `--gate` mode, print one summary line per checklist section (`PASS Supply Chain` / `FAIL Provenance (2 items)`). Exit `0` only if all PASS. Write full report to `specs/verifications/AUDIT-<epic>-<story>.md`.

124+

125+## Verify

126+

127+→ verify: `test -f CONVENTIONS.md && test -d skills/enforce-first && test -d skills/request-review`

128+

129+## Handoff

130+

131+Gate: READY -> next: commit-message

132+Writes: state.yaml handoff.next_skill = commit-message

133+

134+

135+

136+

137+

138+

139+---

140+

141+# Clean Code Heuristics (Chapter 17)

142+

143+A summary of Robert C. Martin's catalogue of code smells and heuristics, used as the technical benchmark for `audit-code`.

144+

145+## Comments (C)

146+- **C1: Inappropriate Information**: Comments should only hold technical notes. Metadata (author, change history) belongs in Git.

147+- **C2: Obsolete Comment**: Update or delete comments that are no longer accurate.

148+- **C3: Redundant Comment**: Don't describe code that adequately describes itself (e.g., `i++; // increment i`).

149+- **C4: Poorly Written Comment**: If you write a comment, spend time making it the best it can be.

150+- **C5: Commented-Out Code**: Delete it. Git remembers it.

151+

152+## Environment (E)

153+- **E1: Build Requires More Than One Step**: Building should be a single trivial operation (e.g., `bash install.sh`).

154+- **E2: Tests Require More Than One Step**: Running all tests should be one simple command (e.g., `npm test`).

155+

156+## Functions (F)

157+- **F1: Too Many Arguments**: 0 is ideal, 1-2 is fine, 3 requires special justification. Never > 3.

158+- **F2: Output Arguments**: Avoid them. If a function changes state, it should change the state of its owning object.

159+- **F3: Flag Arguments**: Boolean arguments are a smell that the function does > 1 thing.

160+- **F4: Dead Function**: Discard methods that are never called.

161+

162+## General (G)

163+- **G1: Multiple Languages in One Source File**: Try to minimize the mixing of languages (e.g., HTML inside Java).

164+- **G5: Duplication (DRY)**: **The root of all evil.** Every time you see duplication, it's a missed opportunity for abstraction.

165+- **G6: Code at Wrong Level of Abstraction**: High-level concepts in base classes; low-level details in derivatives.

166+- **G25: Replace Magic Numbers with Named Constants**: No "naked" numbers or strings.

167+- **G28: Encapsulate Conditionals**: Prefer `if (shouldBePublished())` over complex boolean logic.

168+- **G29: Avoid Negative Conditionals**: Prefer `if (buffer.shouldCompact())` over `if (!buffer.shouldNotCompact())`.

169+- **G30: Functions Should Do One Thing**: If a function can be split into sections, it's doing too much.

170+- **G31: Hidden Temporal Couplings**: If execution order matters, make the dependency explicit via arguments.

171+- **G34: Functions Should Descend Only One Level of Abstraction**: The Stepdown Rule.

172+

173+## Naming (N)

174+- **N1: Choose Descriptive Names**: Names should reveal intent and be updated as code evolves.

175+- **N4: Unambiguous Names**: Names should make the working of a function/variable clear.

176+- **N7: Names Should Describe Side-Effects**: Describe everything the function is or does.

177+

178+## Tests (T)

179+- **T1: Insufficient Tests**: A test suite should test everything that could possibly break.

180+- **T4: An Ignored Test Is a Question about an Ambiguity**: Document the reason for `@Ignore`.

181+- **T5: Test Boundary Conditions**: Most bugs happen at the boundaries; test them exhaustively.

182+- **T8: Test Coverage Patterns Can Be Revealing**: Analyze what code is *not* executed to find gaps.

183+- **T9: Tests Should Be Fast**: Slow tests don't get run.

76184