Skip to content

Repository Analysis Framework

How This Framework Can Help

If, like me, you have used different AI tools at different points in time to generate parts of your codebase, the logic and approach is not always consistent, and the differences start adding up over time. In technical terms, this is referred to as 'Technical Debt'.

Sometimes, an older or newer utility that you created may also employ a more robust technique that you can re deploy in your other scripts. e.g. The way each script looks up the project's root folder can make the script "break" (or not) if you rename a file or move its location.

Lastly, in any coding project, files can quickly accumulate: old scripts, experiments, utilities and code that may no longer be needed. Manually sorting through them can be time-consuming, and carries the risk of deleting something important, or retaining unnecessary clutter.

I created this framework to address all these problems. You can use it as a repeatable checklist to audit your codebase with your preferred AI tool.

If you use AI tools for coding, rather than asking it a vague question like “Is this file useful?”, you can give it a structured process to follow. Check references, examine Git history, identify hard-coded elements and other risks, assess confidence before making a recommendation... In other words, this approach can help you make decisions based on evidence rather than assumptions.

You don't need to be a developer - or understand every technical concept here - to use it. Just follow the checklist, and let the AI handle the detailed analysis. The output will be a clear report that tells you what to keep, what to archive, what to modify, and what can be safely deleted.

Repository Analysis

Purpose: Audit repository and classify files using evidence

Inputs: One or more folders, files, or modules

Required Evidence: Source code, Git history, references, documentation, CI/CD configuration files (e.g., .github/workflows, Jenkinsfile), environment variable definitions (.env, config files), package manager manifests (package.json, setup.py, requirements.txt)

Modification Policy: Read-only unless explicitly instructed

Estimated Effort: Medium to High

Objective

Perform a thorough, evidence-based analysis of the specified repository, folder, module, or file(s)

  • Base every conclusion on observable evidence from the repository
  • Do not modify any files unless explicitly instructed
  • Do not expose sensitive data (credentials, tokens, internal paths) in the final report

Analysis Methodology

For every file under review, perform the following steps:

1. Determine Current Usage

Determine whether the file is still actively used

Check for:

  • Imports (in source files)
  • Function calls
  • Class instantiation
  • Shell scripts / batch files
  • Scheduled jobs (cron, Windows Task Scheduler)
  • Wrappers (e.g., scripts that invoke other scripts)
  • GitHub Actions, GitLab CI, Jenkins pipelines
  • README references
  • Documentation references
  • Configuration references (e.g., in .ini, .yaml, .json)
  • Package manager dependencies (e.g., in package.json "scripts", setup.py entry_points)
  • CI/CD step definitions (e.g., in .github/workflows/*.yml)
  • Any indirect invocation (e.g., via subprocess, exec, or dynamic imports)

Output:

  • Referenced: Yes / No
  • Referenced by: (list of files)

2. Determine Origin

Identify how and when the file entered the repository

Use Git history. Capture:

  • Original commit hash
  • Commit date
  • Author
  • Commit message
  • Look for keywords: "temporary", "migration", "cleanup", "hotfix", "WIP".

Summarize why the file appears to have been created

3. Determine Evolution

Evaluate how the file evolved over time

Review the Git history for the file to determine:

  • Number of commits affecting the file
  • Major functional changes (e.g., adding new features vs. bug fixes)
  • Whether the file evolved into a reusable utility
  • Whether it remained a one-off script
  • Time since last commit (if > 1 year, consider stale)
  • Author activity – is the original author still active? (if not, maintenance risk)

Summarize the evolution

4. Understand Purpose

Read the code (including comments and docstrings) to assess:

  • Primary purpose
  • Inputs (arguments, environment variables, config files, stdin)
  • Outputs (files, stdout, APIs, database updates, logs)
  • Dependencies (libraries, external services, APIs, Google Sheets, databases)
  • File system usage (reads/writes from specific paths)
  • Reliance on environment variables or configuration files (list them)

Summarize in one concise paragraph

5. Assess Reusability

Classify every file as High, Medium, Low, or None

Guidance:

  • High – Generic utility (e.g., string_utils.py), reusable without modification.
  • Medium – Reusable with minor configuration (e.g., accepts parameters for paths/endpoints).
  • Low – Useful only for similar maintenance work (e.g., a backup script for a specific database).
  • None – One-off migration or historical recovery (e.g., migrate_2020_data.py).

Summarize your findings, and include the reasoning

6. Detect Temporary Assumptions

Look for evidence that the script was intended only for temporary use

Examples include:

  • Hard-coded IDs, dates, paths, or filenames
  • Temporary folder names (e.g., temp, scratch)
  • Migration or recovery logic specific to an incident
  • One-time cleanup operations
  • Manual intervention flags (e.g., if __name__ == "__main__" with no entry point)
  • Debug output (print, logging.debug)
  • Experimental code (commented-out sections, TODOs)
  • Hard-coded credentials or tokens (immediate red flag)

List every finding

7. Identify Risks

Determine whether deleting or moving the file could affect:

  • Production pipeline (CI/CD, deployment)
  • Scheduled jobs (cron, Task Scheduler)
  • Documentation (if referenced in guides)
  • Recovery procedures (if used for disaster recovery)
  • Historical reproducibility (if needed to recreate past results)
  • Security posture (if the file contains secrets)
  • Data integrity (if the script modifies production data)

Summarize the risks and recommend mitigation measures as necessary

8. Recommend Disposition

Choose exactly one:

  • Keep in current location
  • Move to maintenance/ (for utilities that are still used but not core)
  • Move to archive/ (for historical/obsolete but kept for reference)
  • Delete (safe to remove entirely)
  • Refactor (useful but needs to be merged or rewritten)

Explain why

9. Confidence Score

Assign a confidence score (0-100%)

Explain the evidence supporting the score (e.g., multiple references found, Git history clear)

Final Repository Report

Produce a summary table with columns:

File | Purpose | Referenced | Reusable | Recommendation | Confidence

Sort by confidence (highest first)

Repository-Level Observations

After reviewing all files, identify:

  • Duplicate functionality
  • Dead code
  • Similar scripts that should be merged
  • Obsolete scripts
  • Missing documentation
  • Folder organization improvements
  • Opportunities to simplify the repository

Recommendations

Provide recommendations in priority order:

  • Priority 1: Safe cleanup (files with high confidence and no risks)
  • Priority 2: Refactoring (files with medium confidence or reusable potential)
  • Priority 3: Folder reorganization
  • Priority 4: Documentation improvements
  • Priority 5: Technical debt (e.g., outdated dependencies)

Constraints

  • Never invent facts
  • Use Git history wherever possible
  • State uncertainty explicitly
  • Prefer evidence over assumptions
  • Do not delete, move, or edit files
  • Produce the report only
  • Do not include sensitive information (credentials, tokens, internal IPs) in the report – mask or omit them

The way I use the above framework is to copy-paste this as a detailed prompt in a competent AI model that can read my codebase and respond with an analysis report. That report can, then, be saved for future reference, and phase-wise edits can be made to improve the project, based on your priorities.

Additional Guidance for Non-Technical Users

To make this framework accessible, I have also included a glossary and a DIY Guide below. These are intended to help non-technical users understand the terminology and the audit process...

Glossary of Terms

Term Explanation
Repository The folder (and its history) where your project’s codebase lives, often on GitHub or GitLab
Commit Snapshot of changes saved to the repo with a message and timestamp
Git history The complete record of commits, showing what changed and when
Import A statement in code that brings functionality from another file or library
CI/CD Automated pipelines that build, test & deploy code eg. GitHub Actions
Cron job A scheduled task that runs scripts automatically on Linux/macOS
Environment Variables Settings stored outside the code that scripts read at runtime
Refactor Rewriting code to improve its structure without changing its behaviour

DIY Guide

If you are more technically-inclined, and wish to run the assessment by yourself (or understand better what's actually happening under the hood)...

Determine Current Usage

  • Use your IDE’s Find References feature where available
  • Search the repository for the filename: grep -r "filename.py" . (Unix/Linux/macOS), or use your code editor’s search
  • Check .github/workflows/*.yml, package.json, and other configuration files for references

Determine Origin & Evolution

  • Run git log --follow -- filename to see the file’s history
  • Count commits: git log --oneline -- filename | wc -l
  • Check the last modification date: git log -1 --format=%cd -- filename

Understand Purpose

  • Read the file’s top-level comments and docstrings
  • Identify its import statements and what functionality they bring in
  • Note any os.getenv() calls — these indicate that the script depends on environment variables

Assess Reusability & Temporary Assumptions

  • Ask: Could I copy this file to another project and use it with minimal changes?
  • Look for project-specific values such as "https://api.mycompany.com", local file paths, hard-coded IDs, or dates
  • Distinguish between intentional configuration and temporary assumptions

Identify Risks

  • Check whether the script is referenced in the README, deployment documentation, CI/CD configuration, or other operational guides
  • Ask the team: “Is this used in production?” — but treat the answer as additional evidence, not proof; Verify where possible

Make a Recommendation

  • Used and generic → Keep
  • Used but difficult to maintain → Refactor
  • Old, unused, and safe to remove → Delete (after an appropriate backup)
  • No longer used but potentially useful for reference → Archive

Assign a Confidence Score

  • High confidence (90%+) when there are multiple clear references and the file’s purpose is well understood
  • Medium confidence (60–89%) when there is some evidence but important questions remain
  • Low confidence (<60%) when evidence is sparse, contradictory, or incomplete
  • Always record the evidence and the reason for the confidence score

eof

This project chronicles ideas, decisions and lessons I have gleaned from building with AI. The goal is to help non-technical users get familiar with these tools and techniques, so that they may be able to use them effectively. At times, I have also made the use of AI tools to augment or refine the content.

Readers are responsible for using any commands or instructions published here with due caution. The creator of this site accepts no responsibility for any system damage, data loss or other consequences, resulting from the application of this content.