---
name: improve-codebase-architecture
description: NarmaForge Deep Architecture: audit software entropy and refactor shallow modules into deep modules.
---

# NarmaForge Deep Architecture Engine

This skill implements the NarmaForge software modularity engine. It audits codebases for software entropy and refactors shallow, tangled systems into deep, robust modules.

## 1. Core Architectural Concepts
- **Deep Modules (Desired)**: An interface that is remarkably simple relative to the substantial functionality and complexity it conceals. High leverage, low cognitive overhead.
- **Shallow Modules (Codebase Slop)**: An interface that is almost as complex as the implementation it hides (e.g. pass-through wrapper functions, 1-line service delegations, anemic classes).

## 2. Entropy Symptoms to Detect
1. **Leaky Seams**: Callers must understand implementation details to invoke methods.
2. **Temporal Coupling**: Methods must be called in a hidden chronological sequence without compile-time guarantees.
3. **Information Leakage**: Changing internal schemas ripples across unrelated UI components.
4. **Sprawling Barrel Files**: Re-exporting hundreds of symbols from index files, damaging tree-shaking and creating circular import loops.

## 3. Four-Step Architecture Protocol
1. **Survey Subsystem**: Scan candidate directories for shallow interfaces and cyclic imports.
2. **Compute Complexity Ratio**: Compare interface symbol count to concealed implementation lines of code.
3. **Interactive Grilling Gate**: Before modifying domain boundaries, present findings and grill the developer on domain intent, multi-tenant plans, and ADR compliance.
4. **Deepening Refactoring**: Consolidate interfaces, enforce compile-time state machines, hide retries/caching internally, and verify with tests.