Replication Package for Understanding Architectural Degradation. A Large Language Model-assisted Multivocal Literature Review
Abstract
Replication Package The package contains the datasets, source code, validation results, and generated outputs used throughout the study. It enables researchers to reproduce the literature review, data extraction, coding, validation, and analysis procedures reported in the paper. Note: All the hyperlinks referring to the shared files only work in the local version (downloading the replication package). The online version will not work because the browser cannot locate the referenced local files. License All generated data is provided under DATA_LICENSE Creative Commons 4.0 Attribution License. All scripts are provided under the Script_LICENSE MIT License. Package Structure Replication_Package/ │ ├── README.md ├── Install.md ├── requirements.txt ├── Data License.md ├── Script License.md ├── Understanding Full read and analysis.xlsx ├── Validation understanding architectural degradation.xlsx │ └── Code and outputs/ ├── Title Abstract Round Code and output/ ├── T-A Validation code and Outputs/ ├── Full Read code and outputs/ ├── Validation Full Read outputs/ ├── (Final Round code and outputs) Understanding MLR analysis/ ├── Validation for Final Round (code and outputs)/ └── Figures (Sankey & Heatmap) Data Files 1. Understanding Full read and analysis.xlsx This workbook contains the extracted data and the final coded datasets used throughout the study. Workbook Contents Sheet Name Description Process Documents the complete study workflow, including screening, queries, extraction, and coding procedures followed during the literature review. White (title/abstract) Contains the raw results obtained after the title and abstract screening stage for the white literature (peer-reviewed studies). Grey (title/abstract) Contains the raw results obtained after the title and abstract screening stage for the grey literature. Full read (accepted) Data extraction form containing information extracted from all accepted primary studies during the full-text review. Who Consolidated coding table of the stakeholders associated with software architecture degradation. What Consolidated coding table of the drivers and motivations of software architecture degradation. When Consolidated coding table of the software development lifecycle stages and situations in which software architecture degradation emerges. Where Consolidated coding table of the locations within software systems where software architecture degradation occurs. Why Consolidated coding table of the reasons why practitioners and organizations tolerate or introduce software architecture degradation. How Consolidated coding table of how the identified motivations manifest and evolve into software architecture degradation. 2. Validation understanding architectural degradation.xlsx This workbook contains the validation datasets used to evaluate the reliability and consistency of the coding process. Workbook Contents Sheet Name Description Stats Summary statistics, agreement rates, disagreement counts, and validation results reported in the study. Title abstract (Validation) Validation dataset for the title and abstract screening stage, including sampled studies, validation decisions, and adjudicated outcomes. Who (full read) Validation of the full-text review coding for Who by LLM models and human evaluators. What (full read) Validation of the full-text review coding for What by LLM models and human evaluators. When (full read) Validation of the full-text review coding for When by LLM models and human evaluators. Where (full read) Validation of the full-text review coding for Where by LLM models and human evaluators. Why (full read) Validation of the full-text review coding for Why by LLM models and human evaluators. How (full read) Validation of the full-text review coding for How by LLM models and human evaluators. Who (final round validation) Final-round validation dataset for the coding of stakeholders (Who), including LLM and human validation What (final round validation) Final-round validation dataset for the coding of drivers and motivations (What), including LLM and human validation When (final round validation) Final-round validation dataset for the coding of lifecycle stages (When), including LLM and human validation Where (final round validation) Final-round validation dataset for the coding of locations (Where), including LLM and human validation Why (final round validation) Final-round validation dataset for the coding of motivations (Why), including LLM and human validation How (final round validation) Final-round validation dataset for the coding of manifestations (How), including LLM and human validation Code and Outputs The Code and outputs directory contains the source code, validation scripts, intermediate files, and generated outputs used throughout the study. Folder Description Title Abstract Round Code and output Source code used for the title and abstract screening stage and all the raw outputs. T-A Validation code and Outputs Validation scripts and generated outputs for the title and abstract screening stage. Full Read code and outputs Source code used during the full-text review, data extraction, coding, and analysis. Validation Full Read outputs Validation scripts and generated outputs for the full-text review stage. (Final Round code and outputs) understanding MLR analysis Source code used to generate the final coded datasets, descriptive statistics, tables, and figures reported in the manuscript. Validation for Final Round (code and outputs) Scripts and outputs used for the final validation of the coded datasets before producing the final study results. Figrues (Sankey & Heatmap) Scripts and outputs used in paper for sankey and heatmap diagrams. Replication of the Results This section describes the procedure for reproducing the title and abstract screening, full-text analysis, LLM-based extraction and coding, validation, and final analysis performed in this study. The workflow uses Marco-o1 as the primary model and Mistral, Qwen, and Llama as independent validation models. The computationally intensive LLM experiments were originally executed on a supercomputer. Setting Up the Environment Follow the instructions in INSTALL.md to configure the required software environment. The required Python dependencies are listed in requirements.txt. After configuring the environment, execute the replication stages below in the specified order. 1. Title and Abstract Screening Use the scripts and input data provided in: Code and outputs/Title Abstract Round Code and output/ The scripts process the retrieved white and grey literature and generate the title and abstract screening decisions. The corresponding outputs are provided in the White (title/abstract) and Grey (title/abstract) sheets of: Understanding Full read and analysis.xlsx Studies accepted at this stage proceed to validation and full-text review. 2. Title and Abstract Validation Use the scripts provided in: Code and outputs/T-A Validation code and Outputs/ The title and abstract screening decisions are independently validated using Mistral, Qwen, and Llama. Human validation is performed on the selected validation sample as described in the paper. The resulting validation data are provided in the Title abstract (Validation) sheet of: Validation understanding architectural degradation.xlsx After validation and adjudication, the accepted studies are used as input to the full-text analysis. 3. Preparing the Full-Text Input The full-text analysis requires the PDF files of the studies accepted after title and abstract screening and validation. The PDFs are processed using the scripts provided in: Code and outputs/Full Read code and outputs/ The scripts extract the textual content of each study and provide it to the LLM analysis pipeline. Note: The full-text PDFs are not distributed with the replication package. Researchers wishing to reproduce this stage must obtain the corresponding papers independently and place them in the input location expected by the scripts. 4. Full-Text Analysis with Marco-o1 Use the scripts provided in: Code and outputs/Full Read code and outputs/ Marco-o1 is used as the primary model to analyze the accepted studies and extract information for the six dimensions investigated in the study: Who, What, When, Where, Why, and How. For the original supercomputer execution, the general command structure is: sbatch "MODEL_NAME" The exact Python and batch scripts used in the experiments are provided in the same directory. The resulting extracted data are consolidated in the Full read (accepted) sheet of: Understanding Full read and analysis.xlsx 5. Full-Text Validation After generating the Marco-o1 full-text results, independently validate them using Mistral, Qwen, and Llama. The validation scripts and generated outputs are provided in: Code and outputs/Validation Full Read outputs/ Each validator is executed separately using the corresponding model configuration. For supercomputer execution, the general command structure is: sbatch "MODEL_NAME" The LLM validation results are combined with the human validation decisions according to the validation and adjudication procedure described in the paper. The resulting data are available in the corresponding Who, What, When, Where, Why, and How (full read) sheets of: Validation understanding architectural degradation.xlsx The corresponding agreement statistics are reported in the Stats sheet. 6. Final-Round Analysis After completing the full-text analysis and validation, use the validated results as input to the final coding stage. The scripts and outputs are provided in: Code and outputs/(Final Round code and outputs) Understanding MLR analysis/ Marco-o1 is used to consolidate the