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.
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.
| name | refactor-lexical-ontology |
|---|---|
| license | MIT |
| description | | |
| author | Jordan 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.md02_PRECONDITIONS.md03_RULES.md04_PROCEDURE.md05_OUTPUT.md
Scripts
If scripts are present, also read scripts/INDEX.md and follow any automated steps first.