Skip to content

refactor: Cut the multi-issue narration comments (108 blocks, 991 lines) #753

Closed

Description

@omesser

Part of #744, and the first work PR. Do this before the domain children (#747-#750).

Why this one first

The owner's words were "reads like a vague story dereferencing past PRs and issues." That shape is measurable, and it is the one cut that lets a reviewer check one rule instead of 3,903 individual judgments.

Scope

Blocks citing two or more distinct issue numbers: 108 blocks, 991 comment lines. Counted, not estimated.

The worst offenders:

Lines Location Cites
50 src-tauri/src/platform/macos/dock.rs:1 #39 #148
41 src-tauri/src/model.rs:4652 #144 #175 #230 #244
32 crates/mcp-server/src/lib.rs:1 #470 #497 #501
28 crates/core/src/director.rs:597 #588 #609
27 src-tauri/src/harness.rs:1455 #243 #499 #514
26 crates/core/src/engine/geometry.rs:262 #141 #176 #361

Find them with a script; do not hunt by hand. A block is any run of consecutive //-prefixed lines, and the rule is len(set(re.findall(r"#\d{2,4}", block))) >= 2.

The rule

Keep the one issue the current code's constraint came from. Delete the narrative of the others.

Inside those blocks only, also cut:

  • Sentences describing a former state: "used to", "previously", "before #NNN", "was answered here", "this replaced". git log holds it better.
  • Sentences reporting a measurement or investigation outcome rather than a constraint on the code — sample sizes, percentages, run counts.

src-tauri/src/model.rs:4652 is the exemplar: 41 lines of doc comment on an #[ignore]d benchmark narrating four issues' worth of findings. A decision log, verbatim, which docs/agents/comments.md:48 already forbids. Nine-tenths of it goes.

Exempt, do not touch

  • //! module docs are exempt from the length ceiling, but dock.rs:1 and mcp-server/src/lib.rs:1 are in scope for the multi-issue rule only — cut the issue narration, keep the orientation.
  • ponytail: blocks. SAFETY: blocks.
  • src-tauri/src/settings.rs, settings/form.rs, and the three platform/*/settings_window.rs — see Comments are 20% of the tree: compact them to a stated bar #744.
  • Do not strip a fenced-code tag. model.rs:4662 sits inside your exemplar block and is tagged ```sh. Keep the fence and its tag intact while cutting the prose around it.

Verify

This is the PR that proves the safety property, so do it properly:

  • The diff touches no code line. Prove it over git diff -U0.
  • cargo test --workspace and cargo clippy --workspace --all-targets -- -D warnings green.
  • node --test tests/*.test.js before and after, with the pass list diffed, not just the exit code. harness.rs and director.rs are both read as raw text by meta-tests (tests/connect-buttons.test.js:24-27, tests/chat-composer-limit.test.js:12), and a comment edit can disarm one silently.
  • Add the windows label, or that leg is lint-only and skips the tests.
  • Report the block count and line count removed.

Expected yield

About 2 points of ratio. Say the real number in the PR rather than rounding it up.

— Claude Code agent, on @omesser's behalf.

Activity

  1. added
    ready-for-agentFully specified, ready for an AFK agent
    p2Eventually: real, but nothing waits on it
    on Sep 15, 2026
  2. added this to the V1 milestone on Sep 15, 2026
  3. self-assigned this
    on Sep 16, 2026
  4. moved this from 👷 Todo to 🏗 In Progress in Fidgeton Sep 16, 2026
  5. moved this from 🏗 In Progress to 🏁 Done in Fidgeton Sep 16, 2026
  6. omesser commented on Sep 16, 2026

    @omesser
    OwnerAuthor

    Landed on main via #763

    Merged PR #763 (7f174f3) closes this ticket.

    What shipped

    • One rule over the multi-issue narration census: keep the issue the current constraint came from; drop the retelling / former-state / measurement diary.
    • 92 → 1 multi-issue blocks in scope (the survivor is a #106 false positive from quoting javascript: in platform.rs; one real issue cite, left alone).
    • 142 comment lines net removed (322 added / 464 removed). Comment-only diff verified (git diff -U0: every touched line is //).
    • Ratio moved 0.19 points (18.65% → 18.46% comments/(comments+code)), not the ~2 projected here — stated honestly in the PR.
    • cargo test --workspace, node --test pass-list (203 identical names), and clippy all green; Windows label ran the real test leg.

    Acceptance for this first #744 work PR is met. Domain children (#747–#750) and the census/hook work stay separate.

    — Cursor agent (Coder), on @omesser's behalf.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

p2Eventually: real, but nothing waits on itready-for-agentFully specified, ready for an AFK agentrefactoring

Projects

  • Status
    Done

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions