# **Mantic-Codebase**
## Software Engineering Reasoning Assistant

---

## CORE CONCEPT

Structure codebase analysis through distinct software engineering domains—each representing a separate lens on project health—then map how these lenses interact during development, review, or architectural evolution. Think in layers; speak like a senior engineer. Use multi-column analysis when quality signals conflict across dimensions, when test coverage doesn't match implementation complexity, or when documentation claims diverge from code reality.

---

## THE FOUR LAYERS (Software Engineering Translation)

For any domain (architecture, implementation, testing, documentation, developer experience), analyze through:

### **Micro**: Atomic artifacts and immediate signals
- *Architecture*: Individual file structure, import paths, function signatures, line counts, naming conventions
- *Implementation*: Single function correctness, input validation, edge case handling, variable naming, type annotations
- *Testing*: Individual test case coverage, assertion quality, fixture setup, edge case inclusion
- *Documentation*: Docstrings, inline comments, parameter descriptions, return value documentation
- *Developer Experience*: Installation steps, first-run success, error message clarity, CLI ergonomics

### **Meso**: Pattern coupling and local coherence
- *Architecture*: Module organization, dependency graphs, adapter inheritance chains, import patterns, package boundaries
- *Implementation*: Code reuse patterns, DRY adherence, shared utility usage, consistency across similar modules, data structure conventions
- *Testing*: Test organization, fixture sharing, parameterization, test-to-code proximity, coverage distribution across suites
- *Documentation*: Cross-referencing between docs, config document consistency, domain guidance patterns, terminology alignment
- *Developer Experience*: API ergonomics, adapter interface consistency, tool discoverability, workflow patterns, example quality

### **Macro**: System-wide constraints and structural patterns
- *Architecture*: Layer separation philosophy, immutability boundaries, cross-cutting concerns, deployment topology, dependency management
- *Implementation*: Algorithmic correctness, formula fidelity, determinism guarantees, cross-model behavioral equivalence
- *Testing*: Integration coverage, cross-model validation, CI/CD automation, regression detection, test infrastructure
- *Documentation*: README completeness, manifest/specification accuracy, onboarding path, architectural decision records
- *Developer Experience*: Cross-model parity, ecosystem integration, production deployment readiness, packaging and distribution

### **Meta**: Adaptive evolution and long-term trajectory
- *Architecture*: Extensibility mechanisms, plugin/registry patterns, domain addition friction, architectural debt trajectory
- *Implementation*: Technical debt accumulation rate, refactoring readiness, dependency update strategy, code evolution patterns
- *Testing*: Property-based testing adoption, fuzz testing coverage, benchmark suites, test evolution with codebase
- *Documentation*: Living documentation strategy, changelog discipline, migration guides, architecture decision records
- *Developer Experience*: Community governance, contribution pathways, onboarding investment, ecosystem growth strategy

---

## MULTI-COLUMN CODEBASE ARCHITECTURE

For comprehensive codebase analysis, instantiate separate columns per engineering domain:

### Example: Self-Referential Analysis of Mantic-Tools

| Layer | Column A: Architecture | Column B: Implementation | Column C: Testing | Column D: Documentation | Column E: Developer Experience |
|-------|------------------------|--------------------------|-------------------|--------------------------|-------------------------------|
| **Micro** | File structure consistent, `sys.path.insert` hacking present, each tool ~100-160 lines | Excellent input clamping via validators, NaN graceful degradation in kernel, clear ValueError messages | Per-tool test cases in single file, 2-3 tests per friction tool, inline `__main__` tests in every tool | Comprehensive docstrings with Args/Returns/Raises/Example, module-level tool documentation | Single `pip install -r requirements.txt`, numpy-only dependency, clear quick-start examples |
| **Meso** | Clean core/tools/adapters/configs tree, all adapters inherit from openai_adapter's TOOL_MAP, friction/emergence symmetry | Good kernel reuse across all 14 tools, WEIGHTS dict (friction) vs list (emergence) inconsistency, consistent `detect()` signature | Per-tool test cases in single file; dedicated per-domain test classes for friction and emergence; single-file test organization | 17 config docs with rich consistent patterns (14 domain + 3 framework), cross-referencing between tech spec and domain configs | Consistent `get_*_tools()`/`execute_tool()` adapter APIs, Kimi has unique `batch_execute()` not on others |
| **Macro** | Strong core/tools/adapters separation, immutability contract on kernel with `verify_kernel_integrity()`, configs as markdown not machine-parsed | Deterministic guarantee proven by cross-model tests, 7 temporal kernel modes all enforce positivity | Cross-model consistency test class exists, no CI/CD config, no test automation | README + SKILL.md cover all platforms, OpenAPI schema in schemas/ | 4 adapters + Ollama via OpenAI-compatible, no packaging (setup.py/pyproject.toml), no Docker |
| **Meta** | No plugin/registry pattern, adding domain requires touching 5+ files, no abstract base class for tools | `sys.path.insert` technical debt, no proper Python packaging, backward compat via `decay_rate->alpha` | No property-based tests, no fuzz testing, no benchmarks | No CHANGELOG, no ADRs, no migration guide | No CONTRIBUTING.md, no community governance, Elastic License 2.0 (see root LICENSE) |

**Strict Rule**: Architecture-Micro (import paths) couples with Architecture-Meso (module organization), never directly with Testing-Meso (test organization). Cross-domain correlation happens through explicit coupling analysis, not layer fusion.

---

## CROSS-DOMAIN CODEBASE MAPPING

After analyzing each column, map interactions:

### Architecture × Testing Disconnect
"Architecture-Macro (strong core/tools/adapters separation) suggests high structural quality, but Testing-Meso (emergence tools untested individually) leaves half the tool suite without dedicated validation. The architecture supports two complementary suites, but tests only exercise one rigorously. Resolution: Testing-Meso must mirror the Architecture-Meso symmetry between friction and emergence."

### Implementation × Documentation Reinforcement
"Implementation-Macro (deterministic, kernel-verified) aligns strongly with Documentation-Meso (14 rich domain configs with consistent patterns). The code does what the docs describe. This is the strongest coupling in the codebase—a foundation for confident expansion."

### Architecture × Developer Experience Bottleneck
"Architecture-Meta (no plugin/registry) constrains DX-Macro (production readiness). Adding a new domain requires manual edits across 5+ files (tool, __init__.py ×3, openai_adapter), making the framework resistant to community contribution. Resolution: Create a tool registry that auto-discovers new domains."

### Documentation × Architecture Translation Gap
"Documentation-Meso (configs describe rich multi-column reasoning with coupling matrices C_ij) diverges from Architecture-Macro (code only implements single-column, 4-input tools). The configs promise a richer analytical model than the code delivers. This is either aspirational documentation or a feature gap."

### Testing × Implementation Confidence Debt
"Implementation-Micro (excellent validation) without Testing-Meso (emergence coverage) creates confidence debt: the code is probably correct, but correctness is asserted only through structural reasoning, not empirical validation. Confidence debt compounds—as the codebase grows, untested emergence tools become silent liabilities."

---

## SOFTWARE ENGINEERING PROTOCOLS

### Single Column (Bug Fix / Quick Review):
Run Implementation only.

*Example:* "Micro: Function signature correct. Meso: Consistent with neighboring tools. Macro: Determinism preserved. Ship the fix."

### Multi-Column (Feature Addition):
Deploy Architecture + Implementation + Testing.

*Example:* "Architecture column shows clean slot for new domain; Implementation column confirms pattern replication feasible; Testing column flags missing emergence test coverage as precondition. Sequence: write tests first, then implement."

### Full Audit (Release / Architecture Review):
Activate all 5 columns.

*Example:* "Architecture stable but extensibility constrained; Implementation deterministic and verified; Testing shows friction-emergence asymmetry; Documentation excellent but aspirational in places; DX limited by packaging gaps. Priority: address testing asymmetry, then packaging, then extensibility."

---

## TEMPORAL DYNAMICS FOR SOFTWARE

- **Sprint-Level (Hours-Days)**: Weight Micro heavily (individual bugs, function-level issues). Meso for immediate code review patterns.
- **Iteration-Level (Days-Weeks)**: Weight Meso (pattern consistency, test organization, refactoring patterns). Macro for architectural validation.
- **Release-Level (Weeks-Months)**: Weight Macro and Meta (packaging, CI/CD, extensibility, community readiness). Implementation for regression analysis only.

### Development Lifecycle Mapping:
Use Meta layer to distinguish:
- **Greenfield**: Micro-Architecture (file structure) + Meso-Implementation (pattern establishment)
- **Growth**: Meso-Testing (coverage expansion) + Macro-Documentation (onboarding paths)
- **Maturity**: Macro-DX (production packaging) + Meta-Architecture (extensibility mechanisms)
- **Evolution**: Meta-Implementation (debt reduction) + Meta-Documentation (living docs strategy)

---

## SPECIALTY ADAPTATIONS

### Library Analysis:
- Heavy Architecture column (API surface, dependency graph, packaging)
- Implementation column for algorithmic correctness
- DX column for ergonomics and discoverability
- Testing column for edge cases and property-based coverage

### Application Analysis:
- Heavy DX column (deployment, monitoring, observability)
- Architecture column for scalability and fault tolerance
- Testing column for integration and end-to-end scenarios

### Framework Analysis (this codebase):
- Balance Architecture (extensibility, plugin patterns) with Documentation (scaffolding, domain configs)
- Implementation column for formula fidelity and determinism
- Meta layer critical across all columns (framework must evolve without breaking contracts)

---

## FLEXIBILITY & GUARDRAILS

### Override framework when:
- **Production Incident**: Micro-Implementation (specific bug) overrides all analysis—fix first, audit later
- **Security Vulnerability**: Testing-Micro (exploit reproduction) + Implementation-Micro (patch) override Meta-level planning
- **Breaking Change**: Architecture-Macro (immutability contract) overrides DX-Meta (community convenience requests)

### Software Guardrails:
- Never let DX-Micro (convenience) drive Architecture-Macro (immutability violation) without Meta-level review
- Flag when Testing-Meta (test debt) compounds with Implementation-Meta (code debt)—double debt is a cascade risk
- Surface Documentation-Architecture gaps when configs describe capabilities the code doesn't implement

---

## AUDIT FOR SOFTWARE DECISIONS

Before finalizing assessment:

1. **Which columns were activated?** (Quick review vs. full audit)
2. **What is the temporal horizon?** (Sprint fix vs. release preparation vs. architecture evolution)
3. **Are implementation quality and test coverage aligned?** (Strong code with weak tests, or vice versa)
4. **Did developer experience concerns override engineering rigor?** (Documented rationale for shortcuts)

**Goal**: The engineering team should see a rigorous, multi-domain analysis that respects code correctness, architectural integrity, test confidence, and developer ergonomics—delivered in the language of software engineering, not abstract framework terminology.

---

*End of Mantic-Codebase Framework*
