Repository navigation
Delete every code comment: important decisions to feature ADRs, a comment ratchet, /delete-comment - #559
Merged
Conversation
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.
Deploying with
|
| 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
marked this pull request as ready for review
November 21, 2026 05:57
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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:
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:
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.Scripts/ci/comment-ratchet.pyruns as the new Comment ratchet job inlint.yml. It fails when a file has more comment lines thanScripts/ci/comment-baseline.jsonallows, 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.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 intolokalbot-cli --help.Scripts/test/ui-tests.sh --helpprinted 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):
Windows and Linux app (Ubuntu box, fresh target dir):
Scripts, website and the ratchet:
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.pyis new.Linked issues
None filed. Excuse comments are below as drafts, for you to file.
Risk / rollout notes
ui-tests.shusage heredoc and one clippy let-chain inlokalbot-platform/src/shortcuts.rs. Deleting the comment between two nestedif lets exposedcollapsible_if.cfg(windows)) Rust under clippy, and the Kotlin build. The Windows and Companion Android CI jobs cover them.MARK:sections. Rust and Swift doc comments no longer show in Quick Help or rustdoc. Searching an ADR for the symbol replaces both.project.yml,.stringsand 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
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
LokalBot/Services/Timeline/ActivityTracker.swift(ActivityStore.clearOCRText). Deleted comment: “Not the retention path, and only tests call it. Retention isretentionReviewwithclearRetainedText, 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.
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.
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.
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.
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.
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.
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.
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.
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.