- Home
- Skills
- Code Quality & Review
- big ball of mud audit
Works with the AI Agents you already use
big ball of mud audit
Detect architectural decay and technical debt with a scored health report and a staged refactoring plan.
Free
big ball of mud audit
Example session with this skill installed
Audit this Next.js repo for architecture smells and tell me if I should rewrite the dashboard logic. It feels like spaghetti.
- Read your context and instructions
- Compiled the big ball
I have audited the directory structure, import patterns, and business logic placement. The system shows significant coupling between the UI layer and data persistence.
Architecture Health Score: 3/10 — Critical Big Ball of Mud risk
Overall Assessment
The project has reached a state where feature development is high-risk. Business logic is scattered across 14 different files rather than centralized, and the "God component" in the dashboard manages everything from raw SQL queries to chart rendering.
Big Ball of Mud Symptoms
src/components/Dashboard.tsx(842 lines): Handles auth checks, Prisma calls, and D3 rendering.src/pages/api/update.ts: Directly modifies the schema without validation logic, bypasses existing helpers.src/utils/all.ts: 1,200-line "junk drawer" containing both UI formatting and database connection strings.
Highest-Risk Areas
- Data Coupling: The UI components import
prismadirectly. Changing the schema requires updating 12 UI files. - State Sprawl: Redux, React Context, and local
useStateare used simultaneously to track the same user object.
Quick Wins
- Move the 4 Prisma queries from
Dashboard.tsxinto a newsrc/services/dashboardService.ts. - Rename
utils/all.tstoutils/formatting.tsand delete unused exports to reduce the import surface.
Is a Full Rewrite Needed?
No. The core logic is sound but poorly placed. An incremental "extract and delegate" approach will stabilize the system in 2 weeks without the downtime of a rewrite.
Prioritized Action List
- Critical — Extract DB logic from
src/components/Dashboard.tsx. - High — Standardize API response shapes in
/pages/api. - Medium — Consolidate user state into a single Context provider.
Next steps
- Review
src/services/dashboardService.tsto confirm the new boundaries. - Run the provided
grepcommands to find the remaining 8 direct Prisma imports in the UI. - Schedule a 2-day sprint to clear the "Critical" priority items.
Connects securely to your tools. The creator never sees your data.
About this skill
This skill audits codebases to detect structural decay, unplanned growth, and eroded architectural boundaries. It identifies "Big Ball of Mud" symptoms where modules are tightly coupled and temporary hacks have become permanent infrastructure. Instead of generic advice, it delivers a scored health report (0 to 10) backed by file-level evidence and a prioritized, non-destructive refactoring plan.
What it does
- Architectural mapping — Analyzes directory trees, dependency manifests, and import chains to visualize the system shape.
- Complexity auditing — Locates "God files" and over-responsible components by scanning for line counts and responsibility sprawl.
- Coupling detection — Identifies business logic leaks where UI components perform direct database queries or API calls.
- Technical debt discovery — Greps for calcified hacks, duplicated logic, and inconsistent role-based access enforcement.
- Refactor planning — Generates a staged, incremental action plan designed to improve architecture without breaking the live system.
How it works
- Provide access to your codebase or upload specific directories for analysis.
- The agent maps the project structure and identifies high-risk files and coupling patterns.
- It evaluates the code against ten diagnostic questions regarding isolation, sustainability, and blast radius.
- You receive a structured report with a 0 to 10 health score and a prioritized list of refactoring tasks.
Frameworks & tools
Works with any language or framework. It uses standard CLI tools like grep, find, wc, and sort to analyze file structures and content.
Why this beats prompting it yourself
Standard prompts give vague advice like "separate your concerns." This skill forces the AI to provide specific line-item evidence, naming the exact files and symbols that violate architectural boundaries. It focuses on the "strangler-fig" pattern to ensure refactors are safe and incremental.
Use cases
- Deciding whether a legacy codebase needs a full rewrite or incremental refactoring.
- Auditing a project after a period of rapid feature growth to stabilize the architecture.
- Performing a deep-dive technical due diligence on a new repository or acquisition.
- Identifying the highest-risk modules before starting a major system migration.
Known limitations
Large monorepos may require targeted scans of specific sub-directories to avoid token limits. Findings are limited to the files and directories provided in the current context.
Requires visibility into file contents and directory structure. Large-scale audits may be limited by context window sizes. Results are scoped to provided files.
How to use
- 1
Connect your agent to the Agensi MCP
Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup
- 2
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before any payment.
Reviews
No reviews yet
Be one of the first to try it. Every listed skill goes through the trust checks below.
Security scanned
Checked by our 8-point scan before listing
Fresh listing
Recently published to Agensi
Free forever
No account required to browse
Trust & safety
Security scan
Security scan passed 14 days ago
- Free with an Agensi account