Skip to content

refactor(praxis): split comment hygiene into its own skill (#39) - #51

Merged
Jartans-Familiar merged 1 commit into
mainfrom
agent/loom/1ea9712f
Aug 17, 2026
Merged

refactor(praxis): split comment hygiene into its own skill (#39)#51
Jartans-Familiar merged 1 commit into
mainfrom
agent/loom/1ea9712f

Conversation

@Jartans-Familiar

Copy link
Copy Markdown
Member

Closes #39.

What

Splits comment hygiene out of code-hygiene into its own comment-hygiene
skill, so a diff that only needs the comment rules (KEEP/DELETE/EXEMPT/
CONDITIONAL, tombstone and retold-fact detection, comment density) doesn't
depend on the model separately deciding code-hygiene's dead-code/naming/
faking-done content is also relevant to trigger it -- the concern #39 raised.
find-duplicate-comments.js moves with it (it only serves the Retold-fact
check).

Cross-references updated so the split doesn't leave dangling pointers:
code-structure, readable-code, docs-patterns and general-reviewer
(both its frontmatter skills: list and the Important/Minor bullets that
were comment-specific).

Domain-owner clause

Artifact-only. Every sentence in comment-hygiene/SKILL.md is existing,
already-approved code-hygiene content relocated verbatim; the only new
prose is mechanical connective tissue (a one-line "split from code-hygiene"
note, and cross-file pointer edits so code-structure/readable-code/
docs-patterns/general-reviewer resolve to the new skill instead of the
old one). No new rule, test, or verdict is introduced.

Not bundled here: the issue's own comment asks to "Add no-narrativization
anti-pattern." That's new doctrine, not a relocation, so it needs a content
owner's sign-off before it lands -- routing to Ferro (engineering practice)
rather than deciding it myself. Flagged, not actioned, in this PR.

Manifest / Codex face

  • praxis bumped 1.4.0 -> 1.5.0 (new skill, MINOR per RELEASING.md).
  • Root .claude-plugin/marketplace.json description for praxis still
    describes the plugin as shipped ("code review with specialized reviewers,
    and project conventions") -- no update needed.
  • Codex face: neither .claude-plugin/plugin.json nor .codex-plugin
    enumerates skills (Codex defaults to ./skills, matching our layout), so
    there's no manifest entry to add for the new skill directory.
    general-reviewer.toml regenerated via scripts/generate-codex.py
    because its source .md body and skills: frontmatter changed (the
    comment-hygiene skill reference and the reworded bullets).

Verification

make verify   # clean
make lint     # clean (lychee-docker/actionlint-docker skip in this sandbox --
              # no Docker socket access; codespell/shellcheck/markdownlint-cli2/
              # zizmor/pre-commit-hooks all pass)

Task JAR-413.

code-hygiene bundled comment truthfulness with dead code, reinvention,
naming and faking-done, so a diff that only needed the comment rules
did not reliably auto-activate the skill (#39). Comments, tombstone
and retold-fact detection, and comment density now live in their own
comment-hygiene skill; find-duplicate-comments.js moves with them.

Cross-references updated across code-structure, readable-code,
docs-patterns and general-reviewer (frontmatter skills: list plus the
Important/Minor bullets that were comment-specific). Content is moved,
not rewritten -- artifact-only, no new doctrine.

praxis bumped 1.4.0 -> 1.5.0 (new skill, minor per RELEASING.md).
Codex face: neither .claude-plugin/plugin.json nor .codex-plugin
enumerates skills, so no manifest entry to add; general-reviewer.toml
regenerated because its source .md body and skills: list changed.

Refs JAR-413

Co-authored-by: multica-agent <github@multica.ai>
@Jartans-Familiar

Copy link
Copy Markdown
Member Author

Path dependency worth naming before either of these merges. This renames plugins/praxis/skills/code-hygiene/ to comment-hygiene/, moving find-duplicate-comments.js. #52 adds that script's test suite at tests/plugins/praxis/skills/code-hygiene/find-duplicate-comments.test.js, which mirrors the source path and requires the source through it.

Whichever merges second needs the rebase, and it is a two-line one: the test file moves to tests/plugins/praxis/skills/comment-hygiene/ and its require path follows. No test content changes.

I would rather this one go first, since it is the rename and #52 is additive -- but either order works as long as the second one rebases rather than merging over it. Merged over, the require resolves to nothing and the whole Node half of make test fails on load.

Separately, and not a blocker here: this implements JAR-390, which is sitting in backlog assigned to me and was not dispatched. I will reconcile the issue against this PR rather than have anyone redo the work.

@Jartans-Familiar
Jartans-Familiar merged commit 05c470c into main Aug 17, 2026
10 checks passed
@Jartans-Familiar
Jartans-Familiar deleted the agent/loom/1ea9712f branch August 17, 2026 09:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Split comment hygiene into an independent skill

1 participant