From a87644666a744c3126d9d2e224f0afef4969843c Mon Sep 17 00:00:00 2001 From: Krzysztof kuhy Rudnicki Date: Fri, 14 Aug 2026 14:25:42 +0200 Subject: [PATCH] Add refactor_claude_todo.md: 250-line file-length cap A ready-to-use prompt describing the goal (every file at most 250 lines, code and prose alike), this repo's actual violations ranked by Fowler ROI (lines x commits/yr), how to split each kind, and the requirement to wire in the shared pre-commit gate so files stay small permanently. Generated from a measured survey of every repo; the gate itself lives in ~/utils (file_length/ + scripts/check_file_length.sh). Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01C7yZz45ezmzCB89Cv5gAtZ --- refactor_claude_todo.md | 96 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 96 insertions(+) create mode 100644 refactor_claude_todo.md diff --git a/refactor_claude_todo.md b/refactor_claude_todo.md new file mode 100644 index 00000000..55732a95 --- /dev/null +++ b/refactor_claude_todo.md @@ -0,0 +1,96 @@ +# Refactor TODO — enforce the 250-line file cap + +> **This file is a ready-to-use prompt.** Paste it to Claude, or open this repo +> and say "do refactor_claude_todo". It is self-contained: everything needed to +> execute is below. Generated 2026-08-14 from a measured survey of every repo. + +## Goal + +Every file in this repo must be **at most 250 lines** — source, tests, and +prose (`.md`/`.txt`/`.rst`/`.tex`) alike — and must **stay** that way forever, +enforced by a gate that fails the commit, not by a note anyone can ignore. + +Why: a file that cannot be read in one piece forces re-reads and partial edits, +which is the single largest avoidable cost in an LLM-assisted workflow. Aim by +churn, not size alone — refactoring pays where code is read and changed often +(Fowler, _refactoring economic benefit_). + +## Scope in this repo + +- **200 files** currently exceed 250 lines (of 807 eligible files). +- **88,451 lines** sit in violation; longest file is **2053 lines**. + +Exempt (do NOT split these): + +- generated files — `*.g.dart`, `*.freezed.dart`, `*.gr.dart`, `**/l10n/generated/**`, + anything with a `GENERATED` header +- markup — `.html`, `.css`, `.scss` +- data files — `.json`, `.yaml`, `.csv`, wordlists and other data-ish `.txt` + (mean line length under 25 chars) + +## Violations, highest ROI first + +ROI = lines x commits in the last year. Work top-down; a long file nobody edits +has near-zero payoff and should not be first. + +| lines | commits/yr | kind | file | +| ----: | ---------: | :---- | :--------------------------------------------------------------------------------------------- | +| 556 | 41 | code | `phone_focus_mode/config.sh` | +| 1734 | 9 | code | `linux_configuration/scripts/periodic_background/digital_wellbeing/setup_midnight_shutdown.sh` | +| 833 | 15 | code | `phone_focus_mode/deploy.sh` | +| 1337 | 8 | code | `linux_configuration/scripts/periodic_background/check_and_enable_services.sh` | +| 1091 | 9 | code | `phone_focus_mode/focus_ctl.sh` | +| 543 | 12 | code | `phone_focus_mode/focus_daemon.sh` | +| 929 | 6 | code | `linux_configuration/scripts/periodic_background/digital_wellbeing/pacman/pacman_wrapper.sh` | +| 564 | 9 | code | `focus_owner/android/app/src/main/kotlin/com/kuhy/focus_owner/EnforcementRunner.kt` | +| 918 | 5 | code | `linux_configuration/scripts/periodic_background/digital_wellbeing/setup_night_lockdown.sh` | +| 912 | 5 | code | `linux_configuration/scripts/periodic_background/hosts/install.sh` | +| 258 | 16 | prose | `CLAUDE.md` | +| 698 | 5 | code | `reverse_survivors/src/core/sim.test.ts` | +| 620 | 5 | code | `linux_configuration/scripts/lib/common.sh` | +| 415 | 7 | code | `focus_owner/android/app/src/main/kotlin/com/kuhy/focus_owner/DevicePolicyBridge.kt` | +| 912 | 3 | code | `linux_configuration/scripts/single_use/features/setup_searxng.sh` | + +_(185 further files over 250 lines not listed — re-run the survey for the full set.)_ + +## How to split + +- **Python** — extract cohesive helpers into sibling modules; keep the public + API and imports stable. +- **Shell** — split into `lib/*.sh` sourced by a thin entry script. Keep + `set -euo pipefail` in each. +- **Dart / TypeScript** — extract widgets/components into their own files. +- **Tests** — split by test-group into sibling files + (`foo.test.ts` -> `foo.parsing.test.ts`, `foo.render.test.ts`). Coverage must + not drop. +- **Docs** — split into topic files under `docs/` with an index. For an + oversized `CLAUDE.md`, move detail into referenced docs so the + always-loaded part shrinks. + +**Do not** game the cap: no one-lining, no deleting tests, no moving code into +an exempt extension, no `# noqa`-style suppressions. + +## Make it permanent (required — this is the point) + +A refactor without a gate silently regrows. Before this task is done: + +1. Wire the shared gate `~/utils/scripts/check_file_length.sh` into this repo's + `.pre-commit-config.yaml` as a local hook. If the repo has no pre-commit + config, add a minimal one. +2. The hook checks **files in the commit** (not the whole tree), so unrelated + commits never break, and it **fails** — exit 1, not a warning. +3. No baseline file and no allowlist. Those are suppressions. +4. If this repo has CI (`.github/workflows`), add the same check there so it + also fails on push. + +## Done condition + +- `bash ~/utils/scripts/check_file_length.sh --all` from this repo root exits 0. +- The repo's own test suite and coverage bar are still green. +- `pre-commit run --files ` passes. +- A deliberately over-250-line test file, staged, makes `git commit` **fail**. +- For a deployed daemon/app: the entry point still actually runs. + +## Verify + +Many scripts here run from systemd timers and the working tree. After splitting a script, run it directly and confirm the timer unit still resolves its path.