Improve skill to reduce excessive comment generation by LLM

[henrybear327]

Summary by cubic

Teaches the skill files to prefer deleting generated prose instead of adding more, so comments, docs, and commit bodies carry only facts the code cannot state.

Refactors

• Adds references/prose-reduction.md as the single owner for deletion passes, surface ownership, and calibration examples.
• Points elfuse-conventions, elfuse-refactor, and elfuse-skills to the reference so prose questions resolve to one place.
• Changes file and module headers to omit titles or synopses the filename already states, with a short module paragraph only for a file-wide stable constraint.
• Extends refactor's comment smell to cover narration and runtime-visible Python docstrings; removal is behavior-preserving only after ruling out introspection consumers.

^{Written for commit 15b8530. Summary will update on new commits.}

[jserv]

Shorten .claude/skills/elfuse-conventions/references/prose-reduction.md

[cubic-dev-ai]

2 issues found across 4 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name=".claude/skills/elfuse-conventions/references/prose-reduction.md">

<violation number="1" location=".claude/skills/elfuse-conventions/references/prose-reduction.md:3">
P3: This file is a prose-reduction reference that is itself long and partly restates guidance SKILL.md already carries, which is why the review asks to shorten it. The three prose sections (Survivors, Commit bodies, and parts of the deletion pass and surface table) re-derive rules already stated near-verbatim in SKILL.md ("Editing one sentence reopens its paragraph", "two to four sentences carry most commits", "A comment earns its place only for rationale, invariant, boundary condition, unit, citation", a Python docstring has runtime consumers). Trimming the restated paragraphs and keeping the distinctive content (the surface-ownership table, the owner-vs-link rule, the calibration block) would bring it closer to the density bar the document sets for everyone else and cuts the reading cost SKILL.md already imposes.</violation>
</file>

<file name=".claude/skills/elfuse-conventions/SKILL.md">

<violation number="1" location=".claude/skills/elfuse-conventions/SKILL.md:243">
P3: The pointer to "surface tests" in `references/prose-reduction.md` does not resolve to anything by that name in the reference. The file exposes a "Surface ownership" table and a pass verification called "The test of the pass", so a reader following the pointer will look for a section that is not there. Rename the reference to the "surface ownership table" (or "Surface ownership rule") so the pointer matches what the file actually carries.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P3: This file is a prose-reduction reference that is itself long and partly restates guidance SKILL.md already carries, which is why the review asks to shorten it. The three prose sections (Survivors, Commit bodies, and parts of the deletion pass and surface table) re-derive rules already stated near-verbatim in SKILL.md ("Editing one sentence reopens its paragraph", "two to four sentences carry most commits", "A comment earns its place only for rationale, invariant, boundary condition, unit, citation", a Python docstring has runtime consumers). Trimming the restated paragraphs and keeping the distinctive content (the surface-ownership table, the owner-vs-link rule, the calibration block) would bring it closer to the density bar the document sets for everyone else and cuts the reading cost SKILL.md already imposes.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At .claude/skills/elfuse-conventions/references/prose-reduction.md, line 3:

<comment>This file is a prose-reduction reference that is itself long and partly restates guidance SKILL.md already carries, which is why the review asks to shorten it. The three prose sections (Survivors, Commit bodies, and parts of the deletion pass and surface table) re-derive rules already stated near-verbatim in SKILL.md ("Editing one sentence reopens its paragraph", "two to four sentences carry most commits", "A comment earns its place only for rationale, invariant, boundary condition, unit, citation", a Python docstring has runtime consumers). Trimming the restated paragraphs and keeping the distinctive content (the surface-ownership table, the owner-vs-link rule, the calibration block) would bring it closer to the density bar the document sets for everyone else and cuts the reading cost SKILL.md already imposes.</comment>

<file context>
@@ -0,0 +1,88 @@
+# Reducing prose
+
+This reference decides which prose survives and which surface owns it. The
+sibling `references/prose-register.md` decides how a survivor is written.
+Apply both when a task adds, reviews, or reduces more than a local sentence.
</file context>

[cubic-dev-ai]

P3: The pointer to "surface tests" in references/prose-reduction.md does not resolve to anything by that name in the reference. The file exposes a "Surface ownership" table and a pass verification called "The test of the pass", so a reader following the pointer will look for a section that is not there. Rename the reference to the "surface ownership table" (or "Surface ownership rule") so the pointer matches what the file actually carries.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At .claude/skills/elfuse-conventions/SKILL.md, line 243:

<comment>The pointer to "surface tests" in `references/prose-reduction.md` does not resolve to anything by that name in the reference. The file exposes a "Surface ownership" table and a pass verification called "The test of the pass", so a reader following the pointer will look for a section that is not there. Rename the reference to the "surface ownership table" (or "Surface ownership rule") so the pointer matches what the file actually carries.</comment>

<file context>
@@ -235,6 +240,11 @@ comments!", PR#290, on a 28-line test header; "Shorten the comments
 slightly.", PR#254, PR#261). An unrequested comment, log line, defensive
 check, or restructuring is a defect to remove, not a favor.
 
+For a comment-heavy diff, a module header, or a docstring cleanup, use the
+deletion pass and surface tests in `references/prose-reduction.md`. A line
+count reports the result; it is not a target that can justify deleting a
</file context>