Every planning tool we have ever used shares one assumption: that the written word is the source of truth. The PRD says what the product should do; the tickets say what the code should become; the docs say what the code already is. Plans get made by reasoning over text.
The problem is that text lies. Not maliciously; it just rots. The doc that said auth owned token refresh was true eight months ago, before a refactor quietly moved it into the gateway. The PRD that says "add retries to billing emails" does not know that notifications only sends what billing hands it. Any plan built on that text inherits its errors, and an agent will execute those errors faster than a human ever could.
So we made a structural decision early: in Loopsfinity, no planning happens until the code has been read. The first agents that touch a new customer are not planners or builders. They are Architects.
The map is built from the territory
When you connect your repositories, the Architect family scans them section by section: modules and boundaries, API contracts, data models, dependencies, and the fragility hotspots where churn is high and coverage is low. The output is a knowledge base with two faces: markdown a human can read and correct, and a structured index the other agents can query.
Then something unusual happens: we show it to you and ask what we got wrong. Your corrections are stored as permanent ground truth and injected into every future run. One sentence from an owner ("billing owns dunning; notifications only sends the email it is handed") is worth more than a thousand lines of inferred documentation, and the system treats it that way.
Docs that argue back
A map is only useful while it is current, so every merge triggers a re-sync: the diff is read, only the affected sections are rewritten, and every change is versioned. When the code and the map genuinely disagree in a way the agent cannot reconcile, it does not silently pick a side. It raises a drift flag and waits for a human.
The knowledge base is the quality ceiling for the whole platform. Every plan, every estimate, every test is only as good as the map it was drawn from.
What changes downstream
Grounding everything in the map changes each stage of the loop. Feasibility review becomes real: a PRD is checked against the actual architecture, and the owner hears about the risky parts in plain language before decomposition starts. Estimates stop being story-text guesses: they are derived from the measured complexity of the files a story will touch. The dependency graph stops being semantic guesswork: contract-first and migration-order edges are computed from impact analysis, with file-level evidence attached.
And the builders stop re-exploring the repository from scratch on every task. Each ticket ships with a context pack: the exact slice of the knowledge base it needs, capped to a tight token budget. Less context, but the right context. Accuracy went up while cost per ticket went down, which is not a trade-off we expected to get for free.
The honest limitation
Reading the code first does not make planning infallible; it makes planning falsifiable. When a story's assumptions still turn out wrong mid-implementation, the builder emits a friction signal instead of guessing, the re-planner drafts a revision, and a human approves it. The map gets a correction, and the next plan starts from a truer place.
That is the whole thesis, really. Not smarter agents: better-grounded ones, in a loop that keeps the grounding honest.