KatalIA: Can a Declarative Metamodel Make LLM-Based Smell Characterization Traceable?

Abstract

Software engineers need to identify and assess maintainability concerns in source code to support inspection and refactoring decisions. However, code-smell characterization is context-dependent: static-analysis tools such as SonarQube provide systematic rule-based findings, whereas LLMs offer contextual interpretation but may produce inconsistent categories and weak evidence links. We present KatalIA, a metamodel-guided LLM approach that operationalizes a declarative quality/smell metamodel through a YAML catalog and a skill-guided evidence chain. We conducted an exploratory single-case study on a Python repository, comparing Codex with and without KatalIA over identical metric artifacts and using SonarQube as an external hotspot reference. The baseline produced 66 free-form observations, whereas KatalIA produced 36 traceable candidate rows encoding 53 smell occurrences across ten reusable categories. KatalIA contributes normalized characterization, evidence-to-smell traceability, a declarative representation defined independently of a specific LLM, and aggregation capabilities that support developer-oriented hotspot identification and layer-level profiling for inspection and prioritization.