Part 1 of 8 — the two failures this system exists to fix, why they feed each other, and why an agent is the right shape of fix.
Every internal-app team carries two chronic costs. They look unrelated. They are the same problem wearing two hats.
The first is vague requirements. Work is requested in language that feels actionable but is not decidable. "We need better visibility into promotion spend." You cannot build that, and more importantly you cannot test whether you built it, because the sentence does not say what "spend" or "visibility" mean here. The team fills the gap with assumptions, builds against them, and finds out at the demo whether the assumptions matched the asker's head. Usually they didn't, fully. So there is another loop. The original requirement was never wrong — it was never pinned down, and pinning down got deferred to the most expensive possible moment.
The second is documentation rot. The thing that would let you pin a requirement down quickly — an accurate picture of the data model, the screens, the batch jobs, the approval rules — exists in principle and is wrong in practice. It was written once, drifted from the code within a sprint or two, and is now consulted with suspicion if at all. So every new question is answered by archaeology: read the code, ask the one person who remembers, guess.
Vague requirements survive because the documentation that would resolve them can't be trusted. The documentation rots because everyone is too busy doing rework to maintain it. Each failure protects the other.
That loop is the target. Break it from one side only and it heals: write better stories against rotten docs and you are still guessing; maintain perfect docs that no workflow consults and they quietly rot again. The system in this guide attacks both ends in one motion — an agent that elicits requirements by consulting the documentation, and an agent that maintains the documentation as a by-product of requirements shipping.
We need something concrete to design against. Throughout this guide it is PromoDesk, an internal Trade Promotion Management (TPM) application at a mid-size CPG company that sells packaged food to large retailers. Three sentences of domain, because the design depends on it:
PromoDesk is a good teacher because it has one of everything: real screens (planner, fund dashboard, claims workbench, approvals inbox), a real SQL schema, batch jobs (a nightly accrual posting, a claims matcher), authorization rules (spend-threshold approvals), and integrations (the ERP for general-ledger postings, retailer EDI for incoming deduction claims). Whatever your internal app is, it has a subset of these. Map as you read.
Return to the request: "We need better visibility into promotion spend." Watch how much is undecided.
| The hidden question | Plausible answers that change the build |
|---|---|
| Which "spend"? | Accrued (planned) · committed (approved) · settled (claims actually paid). Three different numbers, three different tables. |
| Visible to whom? | A key-account manager sees their accounts; a finance director sees everything. That is an authorization rule, not a screen tweak. |
| At what grain? | Per promotion, per account, per product, per period. Each implies a different query and a different screen. |
| Including unmatched claims? | Deductions not yet matched to a promotion are real money in limbo. In or out of "spend"? The answer is a domain rule. |
| How fresh? | Real-time, or as-of the nightly accrual batch? This decides whether it is a new screen or a new pipeline. |
None of these are exotic. Each is the kind of question a sharp analyst asks in the first ten minutes — if they hold the whole system in their head. The trouble is that holding the whole system in your head is exactly the capability documentation rot destroys. The questions go unasked not because people are careless but because the knowledge to ask them is no longer at hand.
You could attack this with discipline alone: a requirements template, a documentation rota, a "definition of ready." Teams have tried for decades. It erodes under deadline pressure because it is unpaid, repetitive, context-heavy work — precisely the profile of work that an agent does not mind doing every single time.
| What the work needs | Why an LLM agent fits |
|---|---|
| Ask the same clarifying questions, tirelessly, on every request. | No fatigue, no "this one's probably fine," no skipped steps under pressure. |
| Hold the entire system's documentation in working memory while reasoning. | Retrieval over the catalog puts the whole map in context for every question. |
| Translate between business language and technical structure. | This is the thing language models are unreasonably good at. |
| Keep dozens of documents consistent after every change. | Reconciliation is mechanical once you know what changed — ideal delegation. |
And just as importantly, the things this work needs that an agent is bad at — deciding what the business actually wants, accepting accountability, judging a trade-off — stay with people. The agent drafts, interrogates, and reconciles. Humans decide and approve. We will hold that line through the entire design.
Concretely, when this works: the "promotion spend visibility" request never reaches a developer as one vague line. It reaches them as a Jira story that already says settled spend, per account and product, including a flagged bucket for unmatched claims, as-of the nightly batch, visible per the existing authorization matrix — with each of those decisions traceable to a question the Analyst asked and a human answered, and each impacted entity in the catalog already linked. Nobody discovered the real requirement in sprint review, because it was discovered up front, when changing it was free.
In the next chapter we design the machine that produces that outcome: a thin orchestrator and two specialist agents — the Analyst and the Librarian — sharing one living catalog.