Reddit Post — r/AI_Agents

Why your agent fails on domain-specific tasks (and it's not the model)

---

Hello folks. My friend (ref on comments) and I want to present an idea so you can point holes in it. Our hypothesis: agents fail on domain-specific tasks because the representation of that domain is wrong — not necessarily the model/agent.

We know this framework might be overkill for most projects, and how much of it to apply will inevitably change from case to case. This represents the purist version of the idea, and fully implementing it could be impractical in some fast-moving situations. Given that, we still firmly believe the core foundations and the mental model can be highly valuable across several contexts.

I'm posting the concept here without worrying about the engineering. The idea is to find holes in the logic. If the idea survives scrutiny, I'll post about the infrastructure we've been building on top of it.

Pushback is the point.

---

TL;DR

Agents fail on domain-specific tasks because the representation they operate on is wrong — not the model. We propose a seven-layer framework to make that explicit.

Three object layers:

• The domain (L0): What exists in the real world
• The understanding of that domain (L1): Split between practitioners who know it tacitly and builders who model it structurally
• The software (L2): What implements the understanding, not the domain directly

Our hypothesis is that most failures live in the gap between those three.

Four meta layers on top:

• Governing rules (L3): What should be built and how
• Premises behind those rules (L4): Why the rules exist
• Navigation (L5): How accumulated knowledge stays traversable
• Enforcement (L6): What turns conventions into invariants
• Agent orchestration (L7): What governs the agent acting across the entire stack

The meta-system sits outside the object system and keeps it honest — when governance lives inside the system it governs, it becomes invisible.

The core claim: a well-structured domain representation is what makes an agent reliable, not prompt engineering.

---

You give your agent access to your codebase. You write a detailed CLAUDE.md. You add context, examples, tool definitions. The agent still does something subtly wrong — not because the LLM is bad, but because the domain it's operating on was never cleanly modeled.

The agent can only be as good as the representation it works from. And most representations are wrong in ways nobody has made explicit.

---

The core problem: software is not a mirror of reality

Software is a formalized representation of reality — not reality itself. Building it means codifying things that exist in the real world: rules, contracts, state changes, flows. When those elements are unknown or poorly modeled, systems silently drift. An agent operating on a drifted system doesn't hallucinate — it faithfully executes on a model that was already wrong before the agent touched it.

The framework we're building tries to make that drift visible and correctable. Seven layers, two tracks.

---

The Object Layer — what your system actually represents

L0 — The Domain. The reality that precedes the software. Entities acting within rules, relationships forming and dissolving, states changing. A customer requests a refund. An order is dispatched. A trust boundary is crossed. The system does not create this reality. It arrives late, and tries to keep up.

L1 — Domain Understanding. What someone modeled when they observed L0. L1 exists in two simultaneous registers.

• L1 operational (practitioners): The support agent knows they can manually approve a refund on day 31 if the customer is highly loyal. Their understanding is procedural, embedded in practice, and closest to L0.
• L1 architectural (builders): The spec says "Refunds are blocked after 30 days." Abstract, transferable, formalizable — and more distant from the lived reality of the domain.

These two may never fully align. The practitioner knows more than they can articulate. The builder formalizes what they can observe. The gap between them is where most modeling failures originate — and where agents fail on edge cases that no prompt engineering can fix, because the representation itself never captured the ground truth. One of this framework's objectives is to reduce the knowledge asymmetry between practitioners and builders.

L2 — The Software. The formal model — code, schemas, APIs — that makes the understanding executable. Software implements L1, not L0. The quality ceiling is the understanding, not the code.

When L2 drifts from L1, the code compiles and ships. Production breaks in ways the test suite never anticipated — because the tests were written against the same incomplete L1. An agent grounded on that system inherits the same blind spots.

---

The Meta Layer — what keeps the representations honest

The meta layer exists to ensure the object track stays coupled to the reality it models. Four functions across five layers.

L3 — Governing Rules. What should be built and how. Constitutions, conventions, confidence levels. Defines correctness for L1 and L2. Acts on the object track from outside it — this separation is structural, not incidental. When governance rules live inside the system they govern, they become invisible. Invisible rules drift without anyone noticing.

L4 — Epistemic Foundations. The reasons you uncover when rules in L3 start to contradict each other. Not axioms written before the rules — premises excavated after the rules have existed long enough to reveal what they were built on. When two L3 rules conflict, the resolution happens here: find the premise, decide if it still holds, update the rules accordingly.

L5 — Knowledge Navigation. Makes the accumulated knowledge across L1, L2, and L3 traversable — for humans and agents alike. Not enforcement; orientation. A well-structured L5 is the difference between an agent that needs a 10,000-token context dump to operate and one that can navigate to what it needs.

L6 — Enforcement. Turns L3's conventions into invariants. Pre-commit hooks, CI/CD gates, extraction pipelines. Where L3 prescribes, L6 blocks. The only layer that actively prevents violations from landing.

L7 — Agent Orchestration. Governs the AI agent acting across the entire stack. Your CLAUDE.md, memory system, skills catalog. Uses what the other layers established; doesn't define rules or enforce them. The point: a CLAUDE.md written without L3 beneath it is instructions floating on nothing. An agent operating on a well-structured L3/L4 needs far less explicit prompting — the structure carries the context.

Layer	Track	Name	Function in the system
L0	Object	The Domain	Raw reality — entities, contracts, and states that exist independent of any software
L1	Object	Understanding	How we interpret L0 — split between operational (practitioners) and architectural (builders)
L2	Object	The Software	The code, APIs, and schemas that implement the formal understanding
L3	Meta	Governing Rules	What should be built and the conventions that define correctness
L4	Meta	Foundations	The premises you uncover when L3 rules start to contradict each other
L5	Meta	Navigation	The index that makes accumulated knowledge traversable for agents and humans
L6	Meta	Enforcement	Hooks and CI/CD gates that block violations of L3
L7	Meta	Orchestration	The logic that governs the agent navigating and acting across the entire stack

This stack maps structural dependency, not chronological creation. The diagram shows how the system must hold together in steady state. But in practice, discovery is bottom-up: a developer writes code, hits an edge case, and only then finds the rule that should have governed it. The framework doesn't demand top-down waterfall design. It only demands explicit mapping. Code without a formalized rule is meta-track debt — allowed, but it must be marked as rule-less, not left as a silent assumption.

---

The feedback loops

The construction flow moves upward. What flows back down is where the system earns its keep.

• L2 → L1 (most useful loop): Implementation forces precision in a way specs cannot. Ambiguities that survive in documentation don't survive in code. Every time implementation hits something the spec didn't cover, that gap belongs in L1 before it gets resolved in L2. If the developer just guesses, the resolution is local and invisible — and the agent will guess the same way forever.

• L2 → L0 (the one to watch): Software reconfigures the domain it models. New required formats, new approval flows, new constraints that didn't exist before the system was built. When this increases efficiency: symbiosis. When it creates friction that practitioners quietly route around: parasitism. The signal is systematic workarounds — an agent trained on that system will learn the workarounds too, and treat them as ground truth.

• L3 → L1, L2 (lateral governance): The meta-system governs the object system from outside. Structural, not incidental.

• L6 → L1, L2 (active validation): The only layer that blocks. Commits that violate L1 or events that don't match the catalog are rejected. Conventions become invariants.

---

If this is a system, it can be measured

The goal of the meta track isn't to write more documents — it's to minimize drift between reality and software. A few specific metrics:

• Orphan Rate: Concepts in L1 with no mapped equivalent in L2, and annotations in L2 pointing to non-existent rules in L3. High orphan rate means understanding and code have severed ties.
• Governance Coverage Ratio: Percentage of core domain code (L2) actively mapped to a governing rule (L3). Code without rules is structural debt. This tracks it.
• L6 Friction Rate: How often does enforcement actually block a commit? At 0%, the meta-system is dead or bypassed. At 80%, it's parasitic. The healthy middle is where L6 catches drift just enough to force conversations.
• Time-to-Alignment: When a new concept enters the L1 dictionary, how long until a corresponding L2 implementation is verified by L6? This measures the latency between the business understanding a new reality and the software reflecting it.

---

Open questions — where I think the model has unresolved tensions

1. Reconciling the two L1s at the enforcement gate. If an operator needs to process a legitimate exception that the L1-builder spec forbids, what does L6 do? We need a mechanism to accommodate operational reality without forcing developers to break CI/CD or write invisible bypasses.

2. Ergonomics of the meta track. Systems that require heavy metalinguistic documentation rot because engineers don't update them. How do you design tooling so that maintaining L3 and L4 feels like part of writing code, not bureaucratic overhead?

3. Human vs. agent legibility. As L7 matures, the meta layers will get optimized for AI consumption. If the rules become highly structured for agents, how do you keep them legible and editable for the humans who have to debug them?

---

Happy to be wrong about any of this.