Skip to content

Delete every code comment: important decisions to feature ADRs, a comment ratchet, /delete-comment - #559

Merged
stevyhacker merged 5 commits into
masterfrom
claude/comment-ratchet
Nov 21, 2026
Merged

stevyhacker merged 5 commits into
masterfrom
claude/comment-ratchet

Conversation

@stevyhacker

@stevyhacker stevyhacker commented Nov 20, 2026 •

Copy link
Copy Markdown
Owner

Summary

Code no longer carries comments. All 28,606 comment blocks (about 52,500 lines) in the Swift, Rust, Kotlin, Python, shell and JS/TS code were classified, then deleted from the code:

Kind Blocks Where it went
Important, non-obvious decision 1,770 Condensed into 1,083 decisions in ADRs 0002–0024, one per feature. A decision the Swift and Rust code share is written once, with every location.
Description of the code (first taken for a decision record) 16,716 Deleted
Tautology 10,046 Deleted
Stale 23 Deleted
Excuse for a hack 51 Deleted; 42 issue drafts below (not filed)

The first pass kept 18,486 comments as "decision records" and copied them verbatim into 123 per-folder ADRs (84k lines, more than the code lost). A stricter re-screen kept an entry only if all three hold:

  1. It records a real decision or hard-won fact.
  2. Someone reading only the code would likely get it wrong.
  3. Getting it wrong has a real cost.

That kept 1,770 (6% of all comments). Each feature's ADR states every decision in a few sentences with its numbers and a Where: line.

  • ADR 0001 records the decision.
  • Scripts/ci/comment-ratchet.py runs as the new Comment ratchet job in lint.yml. It fails when a file has more comment lines than Scripts/ci/comment-baseline.json allows, or fewer without the baseline being lowered. The baseline is empty after this PR, but the ratchet works the same when a later pass leaves comments behind.
  • /delete-comment (.claude/skills/delete-comment/SKILL.md) repeats the process with the strict bar.
  • Not counted as comments, so not deleted: lint and formatter directives, shebangs, swift-tools-version, PEP 723 metadata, license and copyright notices (the AGPL "ported from Cotabby" headers in 39 files), and the /// doc comments clap turns into lokalbot-cli --help.
  • Scripts/test/ui-tests.sh --help printed its own header comment, so its usage text is now a heredoc (same output).

Lines shed: −54,835 / +8,810 against master, −46,025 net. In code, the 755,212 in-scope lines lose 54,225 net (7.2%): 52,523 comment lines, plus ~2,300 blank lines left doubled, less ~600 lines rustfmt rewrapped. The ADRs add 7,270 lines.

Every comment was classified by 103 agents, one per batch of about 300, each shown the comment in its code. 31 agents ran the strict re-screen, and 23 wrote the feature ADRs.

Validation

Swift (local, worktree build with DerivedData outside the checkout):

xcodebuild … -scheme LokalBot -only-testing:LokalBotTests build-for-testing
# ** TEST BUILD SUCCEEDED **, 0 errors
xcodebuild test-without-building … (skipping the model-loading classes: EmbeddingIndexIntegrationTests,
  LlamaCotypingRuntimeTests, LocalLlamaCotypingEngineTests, QwenASREngineTests,
  TranscriptionLanguageReplayTests, CotypingMemoryRelevanceTests)
# Executed 5191 tests, with 49 tests skipped and 0 failures
swiftlint lint --strict --quiet      # 0.65.1, exit 0, no output

Windows and Linux app (Ubuntu box, fresh target dir):

cargo fmt --all -- --check                                      # exit 0
cargo clippy --workspace --all-targets --locked -- -D warnings  # exit 0 after the shortcuts.rs let-chain
cargo test --workspace --locked                                 # 2754 passed, 0 failed (36 test binaries)
python3 -m unittest discover -s scripts/tests                   # 9 tests OK (localization parity reads Rust sources)

Scripts, website and the ratchet:

python3 -m unittest discover -s Scripts/tests        # 266 tests OK (15 new ratchet tests)
python3 Scripts/ci/comment-ratchet.py --check         # Comment lines: 0 (baseline 0)
python3 Website/generator/render_web.py --check      # 51 generated web files up to date
node --test Website/generator/test_*.mjs             # 8 pass
python3 -m py_compile / bash -n / node --check / bun build --no-bundle on every changed .py/.sh/.js/.mjs/.ts/.tsx  # clean
Scripts/test/ui-tests.sh --help                      # same text as before

Before deleting anything, a dry run on a throwaway worktree deleted every comment and parse-checked every language (swiftc -parse, rustfmt, the script checkers). Relative links in all changed docs and ADRs resolve.

Changed test expectations

None. Test files lost their comments only. Scripts/tests/test_comment_ratchet.py is new.

Linked issues

None filed. Excuse comments are below as drafts, for you to file.

Risk / rollout notes

  • Every open branch will conflict. 2,090 code files change, so other open PRs need a merge from master after this lands. Afterwards any comment they add fails the Comment ratchet. The fix is to move it per the skill, not to raise the baseline.
  • Behavior: none intended. Only comment text and the whitespace around it changed, apart from the ui-tests.sh usage heredoc and one clippy let-chain in lokalbot-platform/src/shortcuts.rs. Deleting the comment between two nested if lets exposed collapsible_if.
  • Not verified locally: Windows-only (cfg(windows)) Rust under clippy, and the Kotlin build. The Windows and Companion Android CI jobs cover them.
  • Xcode's jump bar loses its MARK: sections. Rust and Swift doc comments no longer show in Quick Help or rustdoc. Searching an ADR for the symbol replaces both.
  • YAML, TOML, project.yml, .strings and Markdown are out of the ratchet's scope.

Issue drafts (not filed)

42 drafts from the 51 excuse comments. Comments about the same hack share a draft. Nearly all are fixed sleeps or polls that stand in for a readiness signal.

Show the 42 drafts
  1. Target SDK 37 and add the local network access runtime permission
    • Companion/android/app/build.gradle.kts (android.lint OldTargetApi). Deleted comment: “Targeting 37 makes local network access a runtime permission (ACCESS_LOCAL_NETWORK); that move is planned separately.”
      OldTargetApi lint is disabled because targeting SDK 37 makes local network access a runtime permission (ACCESS_LOCAL_NETWORK) and that migration is deferred. Implement the permission flow, raise targetSdk to 37 and re-enable the lint.
  2. Replace fixed 5 s sleep after scanner opens with a readiness check
    • Companion/e2e/android_trip.py (android_trip.open_the_scanner). Deleted comment: “The camera and ML Kit start after the screen appears.”
      The test sleeps a fixed five seconds so the camera and ML Kit can start before checking for crashes. Wait for an observable ready signal such as a UI element or log line instead.
  3. Replace fixed sleep in test pump with a signal for timeout-thread responses
    • LinuxWindows/crates/lokalbot-agent/src/session_tests.rs (Harness::pump). Deleted comment: “Responses can arrive from the timeout thread; give it a moment.”
      The test harness sleeps 5 ms hoping responses from the timeout thread have arrived before draining the inbox. A proper fix is to block on the receiver with a timeout or an explicit completion signal.
  4. Wait for the llama.cpp stderr reader with a signal, not sleep polling
    • LinuxWindows/crates/lokalbot-ai/src/runtime.rs (ServerInner::launch). Deleted comment: “Let the reader catch the last lines of an exited process.”
      After a server exits the code polls up to ten times with 20 ms sleeps for the reader thread to mark finished. A proper fix is to join the reader thread or wait on a condvar signalled at EOF.
    • LinuxWindows/crates/lokalbot-ai/src/runtime.rs (ServerInner::launch). Deleted comment: “The stderr reader may trail the health response briefly.”
      After the health check the code polls 20 times at 25 ms for the stderr reader to record GPU offload, because the reader may trail. A proper fix is a condvar or channel from the reader when offload is seen or the stream ends.
  5. Replace once-a-second file polling for setup, wake and expiry requests
    • LinuxWindows/crates/lokalbot-app/src/control/mod.rs (control::start). Deleted comment: “Setup requests, wakes and expiries have no notification to arrive by, so a once-a-second look at two files finds them.”
      A one-second timer polls two control files because there is no notification for setup requests, wakes and expiries. A file watcher or an IPC message from the CLI would remove the polling.
  6. Replace the 50x200 ms poll for the shortcut manager with a ready signal
    • LinuxWindows/crates/lokalbot-app/src/desktop.rs (sync_shortcuts_later). Deleted comment: “The manager may still be starting (Wayland asks the user first).”
      The worker thread polls up to 10 seconds, sleeping 200 ms, until the shortcut manager exists because Wayland may still be asking the user. Wait on a channel or condvar signalled when the manager is created.
  7. Replace the 600 ms dismissal timer with a proper outside-click signal
    • LinuxWindows/crates/lokalbot-app/src/pages/ask/passage.rs (AskPage.toggle_passage). Deleted comment: “The press that reached this number already closed its passage.”
      The code remembers the last dismissed passage and ignores a re-open if it happens within 600 ms, a time-based guess at whether the same press closed it. A proper fix would let the outside-click handler and the number click share one event so no timing window is needed.
  8. Stop counting optional CUDA libraries in runtime size once system reuse exists
    • LinuxWindows/crates/lokalbot-app/src/pages/settings/models.rs (model_bytes). Deleted comment: “Download size of a model id from its catalog. The llama.cpp runtime is includes the optional CUDA libraries until system reuse is established.”
      The llama.cpp runtime download size includes the optional CUDA libraries until system reuse is established, so the figure overstates what many users download. Implement system CUDA reuse and size the runtime by what is actually fetched.
  9. Replace the 32 ms timer with a layout-complete signal for the ghost
    • LinuxWindows/crates/lokalbot-app/src/pages/settings/writing.rs (SettingsPage::practice_sync). Deleted comment: “The ghost is placed from the caret the editor drew last, which is the old one until the editor has laid out the new text.”
      After text changes a 32 ms timer re-notifies so the ghost is placed from the new caret. Instead, redraw once the editor reports its layout/caret update.
  10. Replace timed leftover-removal retries with a signal that the old copy exited
  • LinuxWindows/crates/lokalbot-app/src/updates.rs (start). Deleted comment: “The copy this one replaced may still be closing.”
    Leftover cleanup retries at 0, 10 and 60 seconds hoping the replaced copy has finished closing. Wait on the old process exit (or a lock) and remove leftovers once.
  1. Replace the fixed 150 ms sleep with a real child-readiness check
  • LinuxWindows/crates/lokalbot-audio/src/system.rs (parec/pw-record start). Deleted comment: “Fail fast when the tool exits at once (no server, unknown device).”
    After spawning the capture tool, the code sleeps 150 ms and then checks try_wait to see whether it exited immediately. A proper fix would wait on the tool's first output or a readiness signal instead of a timed guess.
  1. Replace the fixed sleep and WScript AppActivate with a real foreground wait
  • LinuxWindows/crates/lokalbot-engine/examples/screen_capture.rs (open_notepad). Deleted comment: “A process started from a background session may not get the foreground; ask the shell to activate the window by its title.”
    The example sleeps 2 seconds, then shells out to PowerShell AppActivate by window title because a background session may not get foreground. A proper fix would poll for the window and foreground it with a platform call.
  1. Add RAW photo decoding instead of reporting it unsupported
  • LinuxWindows/crates/lokalbot-engine/src/files/media.rs (not_read_yet). Deleted comment: “RAW isn't read yet, and says so.”
    RAW files are skipped with a 'not read yet' message. Add RAW decoding (or an ffmpeg/embedded preview path) so they are indexed.
  1. Replace the fixed startup sleep with a signal that the engine is ready
  • LinuxWindows/crates/lokalbot-engine/src/indexing.rs (indexing::start). Deleted comment: “Let the window and the first engine events settle.”
    The indexing thread sleeps 5 s so the window and first engine events settle. A proper fix would start indexing on an explicit engine-ready or idle signal.
  1. Let pipeline tests join the stopped worker instead of sleeping past its wakes
  • LinuxWindows/crates/lokalbot-engine/src/pipeline.rs (tests::stopped). Deleted comment: “Past its last wake, so nothing takes a job out of the queue.”
    The test sleeps four idle wakes to be sure the worker has exited before inspecting the queue. A proper fix is to have stop() join the worker thread or expose a stopped signal to wait on.
  • LinuxWindows/crates/lokalbot-engine/src/pipeline.rs (a_new_request_takes_over_a_job_parked_for_models). Deleted comment: “Past its last wake, so nothing takes the job out of the queue.”
    The test sleeps four idle wakes so the worker cannot take the job out of the queue. A proper fix is to have stop() join the worker thread or expose a stopped signal.
  1. Replace the fixed focus-settle polling loop with a focus-ready signal
  • LinuxWindows/crates/lokalbot-engine/src/selection.rs (deliver). Deleted comment: “The panel is still closing for a moment after the click that got here.”
    deliver sleeps and rechecks the field up to four times because the panel is still closing after the click. A proper fix is to wait on a window-closed or focus-changed event instead of polling with sleeps.
  1. Replace fixed Wayland sleep before copy with real modifier-release signal
  • LinuxWindows/crates/lokalbot-platform/src/insert.rs (send_copy). Deleted comment: “Wayland does not say which keys are held.”
    On Wayland the code sleeps a fixed 400 ms because held keys cannot be queried before sending Ctrl+C. A proper fix would detect modifier release via the compositor or input device state instead of sleeping.
  1. Attach UIA controls to correct frame instead of last Meet document
  • LinuxWindows/crates/lokalbot-platform/src/meeting/browser.rs (WindowCall::control). Deleted comment: “UIA's flat list cannot find the end of an unrelated frame. Keep attaching controls to the last Meet document, as before.”
    Because UIA's flat list cannot find the end of an unrelated frame, controls are attached to the last Meet document regardless of which frame they belong to. A proper fix would track frame boundaries from the UIA tree structure.
  1. Replace the fixed sleep before emitting the action signal with a subscription signal
  • LinuxWindows/crates/lokalbot-platform/tests/live_dbus.rs (choose). Deleted comment: “Give the waiting thread time to subscribe first.”
    The test sleeps 500 ms to give the waiting thread time to subscribe before the fake server emits ActionInvoked. A proper fix would have the notifier signal readiness (or poll for the match rule) before the signal is emitted.
  1. Replace the sleep-and-retry loop with a signal that the upload claim was released
  • LinuxWindows/crates/lokalbot-sync/src/tests/recordings.rs (an_interrupted_upload_resumes_where_it_stopped). Deleted comment: “The app's own pass finishes it. It retries while the session above lets go.”
    The test polls upload_recordings up to 100 times with 50 ms sleeps until the server drops its claim on the old session. A proper fix would wait on an explicit release signal or a deterministic hook instead of polling.
  1. Replace fixed 2 s sleep before capture with a render-ready signal
  • LinuxWindows/scripts/ci/capture-linux.sh (capture-linux.sh). Deleted comment: “Time for the compositor and the panel to draw.”
    The script sleeps a fixed 2 seconds to let the compositor and panel draw. It should wait for a concrete readiness signal, as it already does for the window manager and tray, so it is neither racy nor wasteful.
  1. Replace 20 ms polling for isSending with a settle signal
  • LokalBot/Agent/AgentSessionController.swift (AgentSessionController.scheduleQueuedDelivery). Deleted comment: “A prompt ack can arrive just after agent_end. Never overlap two sends or lose the queued message to that ordering.”
    Queued delivery loops with a 20 ms sleep until isSending clears, to dodge a prompt ack arriving just after agent_end. A proper fix would await a continuation or state change that resumes delivery once the send settles.
  1. Remove the close alias for archive once callers migrate
  • LokalBot/Agent/AgentSessionTabs.swift (AgentSessionTabs.close). Deleted comment: “Compatibility for callers that close a workspace: archive keeps drafts.”
    close(_:) is a compatibility shim that just archives, and only tests still call it. Update those callers to setArchived and delete the alias.
  1. Drive marketing-capture setup from settled-state signals, not fixed delays
  • LokalBot/AppLifecycle.swift (AppDelegate.applyCaptureEnvironment). Deleted comment: “Storage discovery and NavigationSplitView restoration can both update the selection after AppState is created. Reapply once the synthetic library and list have settled so marketing captures always show the requested meeting.”
    The code reapplies the meeting selection after a fixed 2.5 s because storage discovery and NavigationSplitView restoration can change it late. A proper fix would wait for an explicit library-and-list-ready signal or make selection restoration not override it.
  • LokalBot/AppLifecycle.swift (AppDelegate.applyCaptureEnvironment). Deleted comment: “Window creation happens immediately after this method. Resize on the next settled turn, before the scripted rasterization delay.”
    The capture window is resized after a fixed 1.5 s delay because window creation happens right after this method. A proper fix would resize in the window creation path or on a window-ready callback instead of a timer.
  • LokalBot/AppLifecycle.swift (AppDelegate.applyCaptureEnvironment). Deleted comment: “Sidebar vibrancy redraws asynchronously after key-state changes. A full second prevents the active material from being captured between its mask and compositing passes.”
    The capture waits a fixed second after key-state changes so sidebar vibrancy finishes redrawing before the snapshot. A proper fix would wait for the material redraw to complete or force a synchronous display pass rather than sleeping.
  1. Stop splitting the setting identifier to dodge code search in UI-test replies
  • LokalBot/Engines/MuseUITestTransport.swift (MuseUITestTransport.liveAnswer). Deleted comment: “Split so a code search of this checkout finds the setting, not these replies.”
    The identifier string is concatenated from two literals so a code search of this checkout does not hit the test replies. Reference the setting through a shared constant and exclude the test transport from the search, or make the search tool ignore this file.
  1. Replace polling for agent running state with an event-driven wait
  • LokalBot/HeadlessCommands.swift (HeadlessCommandRunner.runAgent). Deleted comment: “send() returns after the prompt is accepted; work streams in as events. Immediately after send() the state may still read .ready (agent_start hasn't arrived yet), so first wait for .running, THEN wait for it to leave .running. Otherwise the settle loop exits before any work happened.”
    The --agent runner sleeps in 100 ms loops waiting for the controller to enter and leave .running because state may still read .ready right after send(). A proper fix is to await a state-change signal or an agent_start/agent_end event from the controller.
  1. Replace fixed 500 ms sleep before relaunch with reply-sent signal
  • LokalBot/Services/AppControl/AppControlHandler+Setup.swift (AppControlHandler.setupResponse restart). Deleted comment: “Reply first; the relaunch quits this copy.”
    The restart handler sleeps 500 ms so the reply can be written before the relaunch quits the app. A proper fix would relaunch once the response has actually been flushed to the socket.
  1. Remove legacy in-memory user-action fallback kept for tests
  • LokalBot/Services/Dreaming/DreamCompiler.swift (DreamCompiler.fallbackReport). Deleted comment: “Compatibility for tests and legacy in-memory evidence values.”
    When no projected user actions exist, the code falls back to meeting outcomes only for tests and legacy in-memory evidence values. Migrate those tests and values to projected actions and delete the branch.
  1. Stop production dedup supporting SHA-sized values from tests
  • LokalBot/Services/ScreenMemory/ScreenshotService.swift (ScreenPerceptualHash.isNearDuplicate). Deleted comment: “Test/custom processors historically supplied SHA-sized values. Preserve exact-dedup behavior for those non-production inputs.”
    The comparison falls back to exact equality when a value is not a perceptual hash, only to accommodate test and custom processors that historically supplied SHA-sized values. Update those tests and processors to supply perceptual hashes and remove the fallback branch.
  1. Replace fixed 0.75 s sleep before retrying transient accessibility reads
  • LokalBot/Services/ScreenMemory/ScreenshotService.swift (ScreenshotService.captureIfAppropriate). Deleted comment: “A tab switch or page load can change the window while it is read; the capture event often fires at exactly that moment. Let it settle once instead of losing the capture to the cooldown.”
    When a text read fails transiently because the window changed mid-read, the code sleeps a fixed 0.75 s and reads again to avoid losing the capture to the cooldown. A proper fix would wait for a window-settled or title-change signal, or retry without consuming the cooldown.
  1. Replace fixed 120 ms sleep before paste with a focus signal
  • LokalBot/Services/SelectionActions/SelectionActionsController.swift (SelectionDelivery.deliver). Deleted comment: “Let the app give keyboard focus back to its field before checking it.”
    The code sleeps a fixed 120 ms to let the app return keyboard focus before checking the field. A proper fix would wait for an observed focus change or poll the focus snapshot until it matches the target.
  1. Remove no-op applyingAliases compatibility seam from SpeakerAutoNamer
  • LokalBot/Services/Speakers/SpeakerAutoNamer.swift (SpeakerAutoNamer.applyingAliases). Deleted comment: “Kept as a compatibility seam for processing callers. Confirmed aliases remain unchanged; the rename sheet exposes the calendar suggestions.”
    applyingAliases returns the transcript unchanged and is kept only as a compatibility seam for callers. A proper fix would update the callers and delete the function.
  1. Replace full library scan for meta.json with the SQLite index
  • LokalBot/Services/Storage/StorageManager.swift (StorageManager.loadMeetings). Deleted comment: “Scan the library for meta.json files. Fine for M1; replaced by the SQLite index in M3. Source meetings folded into a merged record remain on disk for provenance but are excluded from the normal library view.”
    loadMeetings walks the whole meetings directory decoding every meta.json, a stopgap the comment says was for M1 until a SQLite index in M3. A proper fix would read the meeting list from the index.
  1. Remove test-only clearOCRText and test the real retention path
  • LokalBot/Services/Timeline/ActivityTracker.swift (ActivityStore.clearOCRText). Deleted comment: “Not the retention path, and only tests call it. Retention is retentionReview with clearRetainedText, which also clears the window titles, addresses and document names this leaves in place.”
    clearOCRText is a production method only tests call, and it leaves window titles, addresses and document names behind unlike retentionReview. Delete it and have tests exercise retentionReview with clearRetainedText.
  1. Replace fixed one-second sleep with a transcript layout-complete signal
  • LokalBot/Support/FilmDirector.swift (FilmDirector.show). Deleted comment: “Open on the latest output, and again once the transcript has laid out.”
    The director sets the transcript to the end anchor, then sleeps one second and clears it to wait for layout. A proper fix would observe a layout-complete signal from the transcript view.
  1. Replace deferred main-queue scroll with a mount-driven scroll signal
  • LokalBot/Views/Meetings/MeetingWorkspaceView.swift (MeetingWorkspaceDetail.reveal). Deleted comment: “The target may live in another tab; scroll after SwiftUI mounts it.”
    Scrolling to the target is deferred with DispatchQueue.main.async so SwiftUI has mounted the other tab first, which depends on run-loop timing. A proper fix scrolls from the target view's onAppear or a state-driven scroll request.
  1. Agent tests: await drained events, stderr and sent lines instead of fixed sleeps
  • LokalBotTests/Agent/AgentSessionControllerTests.swift (AgentSessionControllerTests.pump). Deleted comment: “Let the event-consumption task drain injected lines.”
    The helper sleeps a fixed 150 ms to let the event-consumption task drain injected lines, which is slow and can flake. Await a published state or an expectation, as the stop test does.
  • LokalBotTests/Agent/PiProcessTests.swift (PiProcessTests.testStderrTailIsCaptured). Deleted comment: “stderr pipe drains async”
    The test sleeps 200 ms because the stderr pipe drains asynchronously. PiProcess could expose a way to await stderr drain or process exit so tests do not depend on timing.
  • LokalBotTests/Agent/PiRPCClientTests.swift (PiRPCClientTests.testRequestResolvesOnMatchingID). Deleted comment: “Give the request time to hit the wire, then answer it.”
    The test sleeps 100 ms hoping the request has reached the wire. Wait until the fake transport records the sent line instead.
  1. Make agent-access wake handling and lease release awaitable for tests
  • LokalBotTests/Services/AgentAccess/AgentAccessManagerTests.swift (AgentAccessManagerTests.waitUntil). Deleted comment: “The manager finishes handling a wake just after the engine answers; wait for that instead of sleeping a fixed 200 ms on a busy runner.”
    The test helper polls every 10 ms for up to 3 s because the manager finishes handling a wake just after the engine answers, replacing a fixed 200 ms sleep. The manager should expose an awaitable completion (continuation or event) that tests wait on.
  • LokalBotTests/Services/AgentAccess/AgentAccessManagerTests.swift (AgentAccessManagerTests.testDisableReleasesTheAgentLease). Deleted comment: “releaseAgentLease is fire-and-forget from the MainActor; poll briefly.”
    releaseAgentLease is fire-and-forget from the MainActor, so the test polls the broker's lease count in a loop. A proper fix is an awaitable release (or completion callback) that the test can await deterministically.
  1. File search tests: await watcher start and index deletion instead of sleeping
  • LokalBotTests/Services/FileSearch/FileSearchServiceTests.swift (testOnlyAChangeThatCanAlterTheIndexStartsAPass). Deleted comment: “FSEvents can still report what was written just before its stream began, and notes.txt does start a pass. Outlast the watcher's latency, so that only the writes below can start another.”
    The test sleeps 3 seconds to outlast the FSEvents watcher latency and its replay of writes made just before the stream began. A proper fix would expose a settled or stream-started signal from the service and await it.
  • LokalBotTests/Services/FileSearch/FileSearchServiceTests.swift (testRemovingAFolderDropsItsFilesAndTurningOffDeletesTheIndex). Deleted comment: “The index goes once the reader and the worker have let go of it, on their own queues.”
    The test polls every 50 ms for up to 20 s until the index folder disappears because the reader and worker release it on their own queues. A proper fix would make the service expose an awaitable shutdown or deletion completion.
  1. Make Quick Recall query debounce deterministic so tests can type queries
  • LokalBotUITests/QuickRecallUITests.swift (QuickRecallUITests.setUpWithError). Deleted comment: “Seed the complete query before SwiftUI mounts. The clear test below still drives real typing; the result/restore tests avoid a race among eight per-character debounce tasks on hosted Macs.”
    Tests seed the full query through an environment variable because typing races eight per-character debounce tasks on hosted Macs. Coalesce or cancel the debounce reliably so typed input works in tests.
  1. Replace the fixed 0.8s sleep with a layout-settled wait
  • LokalBotUITests/RedesignUITests.swift (RedesignUITests.testProjectsHighlightsTheOpenProjectAndSelectionKeepsTheColumnWidth). Deleted comment: “A re-division lands on the next layout pass, so give it one.”
    The test sleeps 800 ms to let a possible column re-division land on the next layout pass. Wait on a layout-settled signal or poll the width stably instead of sleeping.
  1. Media scripts: wait for readiness signals instead of fixed sleeps
  • Scripts/media/capture-screenshots.sh (capture-screenshots.sh capture). Deleted comment: “let the PNG write finish before stopping the self-capture host”
    After polling, the script sleeps 0.3 s so the PNG write can finish before killing the self-capture host. The host should signal completion (for example by writing a done marker) or the script should wait for the process to exit.
  • Scripts/media/readme-gif/film_live.sh (film_live.sh). Deleted comment: “models load and the autocomplete and dictation shortcuts register”
    The script sleeps 8 seconds assuming models have loaded and the autocomplete and dictation shortcuts have registered. It should poll for a real readiness signal (log line, port or status command) instead of a fixed delay.

Code no longer takes comments: Scripts/ci/comment-ratchet.py counts comment
lines per file (tool directives, shebangs and license notices excluded), and the
Lint workflow fails when a file gains any. ui-tests.sh prints its usage from a
heredoc instead of its own header comment.
18,486 comments that recorded a decision (a reason, measurement, platform
quirk, privacy boundary or invariant) are kept verbatim, grouped by area, file
and symbol, each under a heading that states the decision.
Tautologies (10,046) and stale comments (23) are gone, decision records live in
Docs/decisions/, and the 51 excuses are issue drafts in the pull request. Tool
directives, shebangs, license notices and clap help text stay. The comment
baseline starts empty. Removing a comment between two nested ifs in
shortcuts.rs exposed clippy's collapsible_if, so they are one let chain now.
@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

Deploying with  Cloudflare Workers  Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status Name Latest Commit Preview URL Updated (UTC)
✅ Deployment successful!
View logs
lokalbot abc6061 Commit Preview URL

Branch Preview URL
Nov 21 2026, 07:02 AM

The first pass kept 18,486 comments as decision records, mostly descriptions of
the code, and copied them verbatim into 123 per-folder ADRs (84k lines). A
stricter screen kept 1,770 that are important and non-obvious; they are now
1,083 decisions in ADRs 0002-0024, one per feature, with a decision the Swift
and Rust code share written once. The /delete-comment skill uses the same bar.
@stevyhacker stevyhacker changed the title Delete every code comment: decisions to ADRs, a comment ratchet, /delete-comment Delete every code comment: important decisions to feature ADRs, a comment ratchet, /delete-comment Nov 20, 2026
@stevyhacker
stevyhacker marked this pull request as ready for review November 21, 2026 05:57
@stevyhacker
stevyhacker merged commit 767f95f into master Nov 21, 2026
51 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant