refactor-lexical-ontology

Audit identifiers and namespaces for lexical-semantic and ontological correctness.Detect semantic role misalignment (agent/tool/process/artifact), derivational misuse(e.g., -er agent nouns), and category errors between modules, packages, classes,functions, and data artifacts. Output a single Markdown report with actionable fixes.

⭐5stars🔀0forks📁View on GitHub🕐Updated Jan 10, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill automates the audit of code identifiers and namespaces to ensure lexical-semantic and ontological precision. It detects subtle naming errors, such as semantic role misalignments (e.g., confusing a process with an agent) and derivational misuse, generating a comprehensive Markdown report with actionable fixes to enhance codebase readability and structural integrity.

Use Cases

  • Codebase Refactoring: Use this skill during major refactors to identify and correct naming inconsistencies that have accumulated over time, ensuring the architecture follows strict ontological rules.
  • Semantic Role Validation: Detect instances where a class or function name implies a different role than its actual implementation, such as using an '-er' suffix for a passive data artifact instead of an active agent.
  • Standardizing Large-Scale Projects: Maintain a unified naming convention across multiple packages and modules to prevent 'ontology drift' and improve developer onboarding speed through clearer identifier semantics.
namerefactor-lexical-ontology
licenseMIT
description|
authorJordan Godau

Instructions

Read all references in references/ before using this skill.

Signals

  • The user says: "naming feels off", "planner vs planning", "module naming convention", "agentive suffix misuse", "semantic role mismatch", "ontology drift", "lexical audit"
  • A naming refactor is planned or ongoing
  • Confusion exists between thing vs doer vs process vs tool in identifiers
  • The codebase has inconsistent conventions between directories/modules/classes/functions

References

Directory: references/

  • 01_INTENT.md
  • 02_PRECONDITIONS.md
  • 03_RULES.md
  • 04_PROCEDURE.md
  • 05_OUTPUT.md

Scripts

If scripts are present, also read scripts/INDEX.md and follow any automated steps first.