code-tidying: new `self-document` skill — comments → self-documenting code (audit + apply modes)

[kyle-sexton]

Intent

Add a new skill to the code-tidying plugin that removes comments and rewrites the code so it becomes self-documenting (rename, extract, restructure). Removal is always paired with code that carries the information — otherwise the comment stays.

Motivations:

• Self-documenting code as org posture.
• Fewer tokens for AI agents reading code.
• Code as single source of truth — no comment-drift maintenance burden.

Name (locked — do not re-litigate)

code-tidying:self-document — fits the plugin's verb-shaped siblings.

Skill shape (locked — do not re-litigate)

• Actions: audit / find-candidates (read-only) + apply modes.
• Scope: configurable via arguments or natural-language prompt, with safe defaults; the skill confirms user intent before mutating anything.
• Scope grammar:
  • Default: uncommitted changes (working tree + staged).
  • Modes: last commit; feature-branch commits vs default branch; whole-repo hunt.
  • Whole-repo mode routes through the existing tidy-lane infrastructure — no second repo-walking mechanism.

Boundaries vs existing skills (locked — do not re-litigate; reuse-or-replace, no silent second way)

• code-tidying:audit-comment-residue stays the read-only residue detector and becomes a consumable input to this skill.
• code-tidying:tidy keeps its in-passing comment deletes (Beck tidyings) with a pointer to this deep skill.
• /simplify (harness builtin) remains the current-diff general quality pass.
• Evaluate consolidation during design; each skill's skip-when states the boundaries.

Research work item

Derive the org's comment criteria from the literature and reconcile into one org posture:

• Clean Code (Robert C. Martin)
• The Pragmatic Programmer
• Counterweights: Ousterhout's A Philosophy of Software Design (comments carry design intent code cannot), Fowler (extract function instead of comment), Beck

Criteria home (locked — do not re-litigate)

• New comment-conventions doc in melodic-software/standards (policy home). Verified gap: no comment-philosophy doc exists there today; criteria currently live only in the user's global CLAUDE.md, which will then defer to the standards doc.
• The skill points at the doc — pointer-not-copy.
• User-reserved escalation: if execution research argues a different home, surface to the user before placing.

Keep-list guardrails (locked — bake into skill design)

Exempt from removal:

• Non-obvious "why" comments
• Constraints
• Interface/design-intent contracts
• TODO(#issue)
• Legally required headers
• Public-API doc comments (XML docs/JSDoc — separate axis; feeds generated docs)

Never bulk-strip.

Integration sub-item (locked scope)

Evaluate seams for making the discipline a default — standards doc via managed sync, planning/implementation skill defaults, repo CLAUDE.md rule, hook — pick during design.

Explicitly out of scope: the broader "are our plugins modular vs repo-influenced" question (separate future issue).

Priority

priority: medium — daily-driver quality tooling, no gates, tidy-family tier.

[kyle-sexton]

This was generated by AI during the /work-items:work-loop autonomous drain cycle.

Surfaced in the --autonomous frontier (unassigned, unblocked, not human-gated) but carries no role label — already triaged (priority set) yet never routed to agent-ready or needs-human. Content reads as structural/cross-cutting (convention, contract, or design-space work) rather than a scoped bug fix, so this cycle's admission gate classifies it C4-shaped or unclassified and routes it human-gated per the fail-closed default rather than admitting it to autonomous dispatch.

Routing: added needs-human. No other state changed — priority and existing labels are left as-is. If this is actually scoped/delegable, re-label to agent-ready (+ status: ready) and it will be picked up by a later drain cycle.

[kyle-sexton]

Frontier disposition (drain session)

Ruling: Close as not planned for this drain wave (frontier consensus).

Dual-panel drain ruling: advisory, superseded, folded into a program umbrella, or blocked on a host/design carrier without an actionable in-repo slice this session. Re-open with a concrete acceptance brief if a consumer needs the work.

KEEP set for this wave: standing telemetry; host-physical Class C (#631 family); program umbrellas #530/#531/#532/#535; live design carriers #1500/#1553/#1668/#1695/#1716/#1681/#1718; #1360.