comment-cleanup

name	comment-cleanup
description	Systematic pattern for cleaning code comments — strip process meta (Phase/Cluster/c-*/Stage/m*/cross-cluster labels, milestones), rewrite history as present constraints, convert pending/deferred language to TODO: markers, fix broken grammar, and log discovered TODOs to docs/TODO.md

Comment cleanup

Use when asked to clean up code comments according to the QWEN.md comment guidelines (present tense, no process meta, no history, only TODO: markers for forward-looking items).

Step 1: Sweep for violations

Grep the target file(s) for these patterns:

Phase [A-E0-9]      — task phase IDs (also in Cargo.toml descriptions)
Cluster [A-C]       — project cluster labels
c-\d:               — substage task IDs
m\d{2}              — milestone IDs (m27, m39, m49-d-xii, etc.) in Cargo.toml
cross-cluster       — external spec citation labels ("cross-cluster Lock X")
Substage c-         — spec subsection references
milestone           — milestone language
task #\d            — task references
previously          — history narration
replaced            — changelog narration (when describing what was there before)
shipped             — changelog meta ("shipped at", "shipped the container")
retired             — changelog meta ("retired at Phase 1")
was a bug           — bug history
fixed in            — fix history
per the plan        — plan references
2026-               — date stamps in comments (historical annotations)
follow-up part      — process staging labels
Stage [A-F].*:      — stage labels used as comment prefixes

Also scan for broken grammar: // .*at so the|// .*For we |// .*the the |// .*is is .

Step 2: Fix each match

Process labels (Phase X, Cluster Y, c-Z:, Stage X): Strip the prefix, keep the descriptive content. These appear as:

• Inline: // Stage F: TickGroups lives on engine. → // TickGroups lives on engine.
• Doc comments: /// Cluster B.3: verify that Tab... → /// Verify that Tab...
• Bold doc headers: /// **Stage A.3 — captures the... → /// Captures the...

Section headers with labels: Remove the label, keep the header:

// ----- c-2 lock surface -----    →    // ----- Lock surface -----

Cross-cluster / spec citations: Remove entirely or rephrase as a present rationale. These are external references meaningless to someone reading the code:

// (cross-cluster Lock 3) so any lock visible...    →    // so any lock visible...
/// Default is [`Self::Local`] per cross-cluster Lock 5.    →    /// Default is [`Self::Local`] — preserves the user's own work.
// requirement (Substage c-2 § "Warning modal...")    →    // requirement for the warning modal

Cargo.toml descriptions: These often carry milestone IDs and Phase labels:

description = "Networking foundation types (m27). ... Phase 6 m1 lands..."
→    description = "Networking foundation types. ... Full networking implementation is not yet complete."

Milestone/deferred language: Convert to TODO: markers AND log to docs/TODO.md immediately (don't batch). Example:

// pending Phase 4 polish            →    // TODO: <description>
// A future milestone can plumb...   →    // TODO: plumb...

History/changelog narration: Rewrite as a present constraint:

// The pre-X check this replaced was always-false
→    // Filter to Prefab-category assets only.

Date stamps: Remove date annotations like (2026-05-03) and locked 2026-05-03 — these are historical noise. The "why" should already be expressed as a present constraint.

Stage labels in parentheticals: Remove (Stage F) and similar annotations from doc comments:

/// engine singleton (Stage F).    →    /// engine singleton.

Runtime strings (user-facing error messages, log messages, test assertions): Strip process labels from these too, and update any test assertions that match against them. Examples:

• "not wired in Cluster C" → "not yet implemented"
• "Cluster B.1 boot-path frame-graph" → "Boot-path frame-graph"
• "Substage c-2" → remove or rephrase as plain English

Broken grammar: Fix typos and sentence fragments:

// Surfaces at so the menu bar    →    // Surfaces here so the menu bar
// For we mirror upstream's...    →    // We mirror upstream's...

Step 3: Log TODOs immediately

When you add a TODO: marker or convert "pending" language, log it to docs/TODO.md at the same moment — don't batch TODOs. Check if the TODO already exists before adding a duplicate. Format:

- **Short description.** What is missing and why. **Trigger:** when to act.

Verify TODOs against reality. Before logging a TODO that claims something is "not yet implemented", confirm it's actually still unimplemented. Stale comments may claim missing features that already exist. When in doubt, grep the codebase for the relevant function or feature to confirm.

Step 4: One file at a time

Complete each file fully before moving to the next. Verify with a final grep to confirm zero remaining matches for the violation patterns.

Pitfalls

replace_all is risky for doc comments. Stripping **Stage X — from /// **Stage A.3 — captures the live workspace as a leaves stray ** markers and can mangle indentation. Always read each doc comment before editing, and verify output after.

Multi-line doc comment boundaries. When stripping a label from the first line of a multi-line doc comment, read the full comment first to avoid splitting the label across two lines. Example of what NOT to do:

Original:
  /// **Stage F follow-up part 1 — Save half of the
  /// dirty-close confirmation modal.**

Bad edit (label split across two lines in old_string didn't match):
  /// Save half of the dirty-close confirm modal.
  /// dirty-close confirmation modal.**        ← orphan fragment left behind

Indentation loss from replace_all. When using replace_all to strip a prefix like /// Cluster B.6: → ///, the extracted remainder line may lose its indentation if the pattern matches at different indent levels. Check the full file with grep afterward.

Cargo.toml descriptions are single-line. Unlike Rust doc comments, Cargo.toml description = "..." strings are on a single line and can be safely cleaned with replace_all.

Rendering WGSL shader comments. Phase labels in .wgsl files like "Phase 5a" or "Phase H2" often serve as algorithm-version markers for the rendering team. These may look like process labels but function as revision stamps for shader passes. Evaluate each occurrence against context: if the label names a specific rendering technique version (rather than a project milestone), it may be legitimate documentation.

Stale comments that claim missing features. Some comments describe features as "future milestone" or "not yet implemented" when they actually exist. The Stratum GI case was one — the comment said "GI = future milestone" but Stratum GI was already implemented. Always verify before converting to a TODO, and just strip the stale claim if the feature exists.

Broken sentences from prefix stripping. When removing a label from the middle of a sentence (not a prefix), the remaining fragments may not connect. Example:

Original:  // the addition must survive — Phase C only drops overrides
Bad edit:  // the addition must // Stale-delta cleanup only drops overrides
Fix:       // the addition must survive — stale-delta cleanup only drops overrides

Read the full paragraph context when stripping mid-sentence labels.

Orphaned text fragments after aggressive edits. When the old_string doesn't fully capture the tail of a comment (because it was truncated in the read), orphaned lines like // a matching source .tentity. or // inline section that Stage A shipped. can be left behind. After every edit batch, grep for standalone lines that look like sentence fragments (lines starting with // a , // the without a preceding context line).

Constraints

• Do NOT change test assertions that would break test logic — only change the process-label portions of test needle strings when safe. Update matching log messages and test assertions together.
• For user-facing error strings embedded in code (.to_string()), replace "not wired in Cluster C" with "not yet implemented".
• When stripping a label from a doc comment, ensure the resulting sentence still reads grammatically — add connecting words if needed.
• Leave code-identifiers alone: TouchPhase, depth stage, three-stage fallback chain, LayoutImportConflictStage, and similar terms are code concepts, not process labels.
• In physics crates, broad-phase is a collision detection term, not a process label — skip it.
• In WGSL shaders, phase in phase lock / static phase is a rendering pipeline timing concept — skip it.
• Before logging a TODO claiming something is unimplemented, verify it with the user or by checking the code. A stale comment may

Agent prompt rule

When dispatching subagents for implementation work, include the comment rules in every agent prompt — not just in the plan header. The plan header is for the human reading the plan; the subagent only sees the prompt you give it. This was a recurring user correction across m54-a/b/c execution.

Template to include in every implementer prompt:

## Comment Rules (STRICT — apply to ALL code you write)
- Comments state what the code does or why — present tense,
  about the current code only.
- No process meta: no task/step/phase/milestone numbers, no
  plan/spec/audit references.
- No project history: no "previously", "replaced X", "was a bug".
  History belongs in commit messages.
- The only forward-looking marker is a plain `TODO:` — never
  tied to a task or plan ID.
- Plain language, minimal jargon.
- Code carries zero proprietary names. Name the technique, not
  the product.

Why: subagents do NOT inherit plan headers — they only see the prompt text you construct. The plan's comment rules section is for human readers of the plan file, not for the subagent context. erroneously describe a feature as missing (e.g., "GI = future milestone" when Stratum GI already exists).

• After every batch of edits, scan for orphaned sentence fragments (lines like // a matching source.tentity. or // inline section that without surrounding context) and fix them.