I built a map of my own product — and then it started giving me things I had never planned for.

• 1. What it is
• 2. Why it's needed
• 3. What's in it
• 4. What we've built so far and what it gave us
• 5. How it's built, in short
• 6. The agent instruction
• 7. Where we used it
• 8. How to keep it current

1. What it is

A description of what the product can do today: which screens exist, what the user does on them, what data the product stores, what is already built and what is only being discussed. It lives as a folder of linked files rather than one text; the contents are listed in section 3. It is written from fact, not from intent, out of the code and a walkthrough of the live interface. Documentation is the third source. Technical docs (knowledge-base articles, tracker tickets) explain why a feature was meant to exist; user manuals show how it gets explained to the customer. But the senior source is code confirmed by a walkthrough: where a document disagrees with the product, the product goes into the map and the disagreement is written down separately.

Put simply, it answers the question "so how does this work right now?" without having to reassemble the answer every time out of people, chat history and old documents.

2. Why it's needed

Documentation goes stale, the map doesn't. Requirements get written before development and then never touched. Six months later they say one thing and the product does another. The map is assembled from what actually runs, so you can make decisions from it.

A new person or a new agent gets up to speed in hours, not weeks. A developer, an analyst or an AI agent reads one file instead of digging through code and interviewing the team.

You can see what isn't there. When everything that exists is written down in one place, the holes stand out by themselves: there's a setting but no way to save it; there's a field but no hint next to it. One section of the map is a list of those gaps with links to tickets.

The support tracker doesn't show the whole product. A ticket exists only because somebody reported it: got that far, wrote in, explained why it was in the way. The person who couldn't work it out and quietly left never shows up in the tracker. So a gap list built from the tracker alone is always shorter than reality: it describes the product as seen by the people who had the energy to complain. The map starts from the product rather than from complaints, and that covers the blind spot.

Less wasted work. Before commissioning development you can see whether it's already built. And the other way round: checking the description against the code turns up bugs that testing never finds, where the interface looks fine but the command never reaches the device.

Requirements get written faster and land more precisely. When we spec a new task, the map shows straight away which screen it attaches to, what's already there, and what we can point at.

3. What's in it

The map is a folder of several files, not one text.

The screen storyboard

The screen file says what the screen does. The storyboard shows it: frames of the live interface on the left, notes on each state on the right. One HTML page per screen, kept in the repository next to the map, opens off the disk with a double click. No fonts over the network, no build step.

A document like this used to be drawn by hand by a designer when specifying new functionality: a mockup of the screen with callouts beside it about where the user came from, what they do here, which requirement the screen covers, why the solution looks the way it does. The map's storyboard gives you the same thing, but on the working product, and built from a captured frame instead of from intent. An agent puts it together.

Some of those notes the designer couldn't have written anyway: what goal the screen serves, which user job it closes, what the product manager had in mind with this particular state of the form, and why they picked this solution. A mockup describes how the screen looks and behaves; the intent stays in the product manager's head and usually never reaches a document at all. In the storyboard it sits next to the frame.

The note on each frame answers one set of questions:

• why this screen or this state: what the person does here and what they walk away with;
• which user job it closes: and why that job can't be done without this screen;
• how you get here: the address, the menu item, the click or the mode that opened this exact state;
• what's on the screen: the full inventory of sections, fields, buttons and banners in this state;
• how it differs from the neighbouring states of the same screen, as a concrete difference rather than the phrase "a different set of fields";
• why the solution is what it is: what goes to the server on save, what the shape of the form depends on, why a field is read-only;
• what's unfinished and what looks odd in the frame, with a ticket key if one has been filed.

The rules without which a set of frames is pointless:

• A frame for every state that differs, not one "as it opened": every mode of the form, every tab of a card, an empty list, service screens. A frame is spent where the set of fields changes, not where a different button is highlighted.
• One screen, one window width, one object. Otherwise half the set describes a different record and the states can't be compared with each other.
• Read-only. States that only open after a write to the server don't get invented: they go into a separate list with the reason there's no frame.
• The note is written off the open frame, not off the file name: labels exactly as the interface has them, typo included; a disabled field as disabled; an empty list as empty.
• The frame outranks the document. If it disagrees with the screen file or with the map, the document gets fixed, not the caption under the frame. That's how we found a field that had been taken out of the code but not out of the description.
• Validator and a browser render before handover: missing images, broken links, one note copied across ten blocks, frames shot at the wrong address or with failed requests.

The size of a screen is uneven because of this: a simple list gets one or two frames, a form whose shape depends on the mode gets fifteen or twenty.

4. What we've built so far and what it gave us

In the summer of 2026 we mapped two products in and around fintech, about 50 screens. Entities and cross-cutting functions are described for one of the two so far: 15 and 23 respectively. Storyboards also exist for one product only: 10 screens, 64 frames. The method is the same throughout: walk the interface, read the code, then check against technical documentation, manuals and tickets. Both maps sit in the team's shared repository, and the agents of everyone who writes code pull them from there.

What it gave us over two months. Numbers and details for each case are in section 7.

Documentation gets checked against fact. The map overturned conclusions that had been drawn from technical descriptions and manuals. A feature everyone believed was missing was already working, and the plans to build it again were cancelled. The manual on connecting the payment side, cited as proof that "the instruction exists and the questions keep coming anyway", appeared later than 144 of the 237 requests on that topic. For most of those questions the instruction simply didn't exist yet, and the argument fell apart.

Defects turn up that nobody was looking for. Working through one screen, matching the form against the commands that go out to the device, exposed bugs in the frontend. Testing never caught them because the interface looked fine. A separate class of finds is the seams: the same field validated more strictly on one screen than on another; a requirement written so that the user physically never reaches it. Places like that are visible only to someone holding the whole product in their head at once, and that is exactly what the map is.

The storyboard replaced the designer's version. A screen description with frames and notes on every state used to be drawn by a designer, and only for new functionality. Now a document like that exists for everything that runs today, and it gets updated together with the map. The side effect turned out to matter more than the replacement itself: roughly half the finds surface not while reading code but while writing the note under a frame. Six of them came out of a single shooting run: an "update" heading on an add form, a typo in a list column, a hard-coded date in a text, a disabled eighth price field, and others. Details in section 7.

Testing stopped being the bottleneck. Development was moving faster than testing, and talking about it got us nowhere: neither persuasion nor process reviews helped. The testers got the map and an agent. A ticket comes in from the tracker, the agent works through the ticket and the branch, runs checks against the API and the interface, reads the staging logs, writes a report, and moves some of the tickets through the statuses on its own.

The results are worth reading as a trend, not as absolute numbers: the incoming volume swings, so comparing "how many items" is meaningless. Report from one of the two testers for 15 June to 7 August 2026, 40 working days:

• throughput up roughly threefold, from 3 tickets a day in June to 10 or 12 in August, with no new headcount;
• at the old volume of work that comes out as about two free days out of five;
• one person's intake and output: was around 15 tickets a week, now 45 to 50, again about ×3; the output now also includes knowledge-base reports and filed bugs, which at that volume never used to get done;
• of the tickets that went through the agent, more than half (45 out of 81) it carried to the end of the cycle by itself: tested them and changed the status in the tracker.

Absolutes for the record: 87 working sessions, about 8,800 actions, of which around 5,500 were terminal commands that used to be typed by hand. On their own they don't say much; the change of mode is the point.

The bulk of the gain came not from "we switched on AI" but from the rigging built around the agent: 10 in-house playbooks (checking a merge request, a pre-release check, a targeted retest, filing a bug, digging through server errors, staging logs, "what's actually deployed", and more). Runs over time: almost none in June (2), 46 in July on the main playbook alone, 108 across the whole period. That's the effect of a month and a half spent packing our own process into the agent. A by-product: the set of eight Playwright autotests for the product was written by the same agent.

Across the project as a whole the trend is the same, in shares of the weekly intake (counted by a tracker label or a templated report in a comment): in May, without the agent, we closed about 40% of what came in and the queue grew by roughly half of intake; by the end of July, with the agent, about 95% closed, the queue barely moving, about 30% of everything closed being agent runs. The tester's own words at the daily: time is no longer tight, and there's room to take on other work.

Product capabilities show up that were documented nowhere. Checking the code against the list of screens exposed server requests that no document mentioned.

The backlog stopped being scattered. The "Product gaps" section holds tracker tickets, ideas from the knowledge base and local specs in one place: what's described and not built, what's built differently from what's written.

The rule that holds all of this up: the senior source is code, confirmed by a walkthrough of the live interface. Any document is context and a list of discrepancies, never grounds for writing down that a feature works a certain way (see section 5).

5. How it's built, in short

The work is done by an AI agent following a written instruction, one screen per run.

1. It looks at the screen through the user's eyes. Opens the staging environment, goes through the tabs, captures the page inventory and screenshots. Changes nothing and saves nothing, read-only, so no data gets touched.
2. It reads the code. What the page asks the server for, which fields the data has, who sees what. Labels come out of the interface text files, not out of thin air.
3. It checks against documentation. Technical descriptions and tracker tickets give the intent and the business context; user manuals give what was promised to the customer. The gap list comes from the same place: what's described but not built, and the reverse, what's built differently from what's written.
4. It writes everything up in a common format: purpose in plain language, contents, data, permissions, links to other screens.
5. It assembles the storyboard. A frame for every state of the screen that differs, plus a note on each frame: why this state, which user job it closes, how you get here, how it differs from its neighbours, why the solution is what it is. Without a storyboard the screen doesn't count as described. What goes into the notes, and the shooting rules, are in section 3.
6. It separates fact from guess. Anything not confirmed by the interface or the code is marked as needing a check. Filling in the blanks is forbidden.

A walkthrough of one screen takes one working session. The full map of the first product came together in a few days.

Source priority. What counts first is how the product is built in code, and that has to be confirmed by a Playwright walkthrough: the screen was open, the field or the button was seen live. Design descriptions were written before development and never revised afterwards, manuals lag behind the product, tickets describe the intent rather than the result. So documentation in the map is context and a list of discrepancies, not grounds for writing "the feature works like this". Where code and a document disagree, the code goes into the map and the disagreement gets its own line.

6. The agent instruction

The method is packaged as a skill, an instruction the agent follows step by step. The agent doesn't pick it up on its own: it's launched by hand, one screen at a time.

Two kinds of file

Pages and functions link to each other both ways.

A hard limit, read-only. Allowed: navigating to addresses, tabs, pagination, changing the period, expanding blocks, screenshots, reading the page markup. Forbidden is anything that changes data: create, save, delete, apply, submit, upload a file. If the screen can't be understood without a forbidden action, stop and ask.

Access is described inside the instruction itself and never requested from the user: staging by default, production only on an explicit instruction; credentials come out of a protected environment file instead of being written into the text; code is read from local copies of the repositories, and an external API is called only when there's no local file.

Steps

1. Check against the map. Find the screen in the list of addresses, fix the canonical name, the section number and the file name. Not in the map: say so. File already there: extend it, don't overwrite it silently.
2. Walk the interface. A ready Playwright script template: sign in, navigate, capture the structure (headings, tabs, table columns, visible buttons) and a full-page screenshot. A redirect, an access denial or an empty screen doesn't get guessed at: we write "access restricted for the demo account" and fill the rest in from the code.
3. Read the code. The component for services, display conditions, permissions and filter parameters; the template for tables, tabs and navigation; the service for API calls; the models for fields; the localisation files for exact labels (the source of truth for interface text); the server side when a request isn't visible in the client code.
4. Check against documentation. Technical knowledge base, tracker tickets, user manuals. This is where the business context, the "Product gaps" section and the list of places where the written word differs from the working product all come from. Source priority isn't up for debate: a discrepancy is resolved in favour of the code and written down on its own line.
5. Assemble the file to the skeleton: purpose in the user's language, filters and period, contents, API, models, permissions, discrepancies with documentation, related functions and pages, inbound links.
6. Storyboard. Shoot every state of the screen at one window width and on one entity, write the note on each frame off the open frame, keep a separate list of the states that can't be shot with a reason for each. Then the validator and a render of the page in a browser. Without a storyboard the run on that screen isn't finished.
7. Links. The page points at its section of the map, the map points at the page; when a new page appears, the ones already described get updated.
8. Report: what was created, what the interface confirmed, what came out of the code, what was left unverified.

Two rules that produce the quality

• Fact and assumption stay apart: anything unverified is marked "presumably, needs checking".
• One screen, one chat. We don't run parallel agents across several screens: context burns faster than the benefit grows.

7. Where we used it

The map turned out to be useful well beyond what it was built for.

Checking what's documented against what's in the code. We went through every screen and compared the list of server requests with what had been described. We found eight requests no document knew about, and rewrote five entries in the map: device operating mode, connection settings, the bonus system, automatic assignment of payment credentials, interface languages.

Working through support requests on top of the map. We attached everything the customer arrives with: chat messages and voice notes from messengers, tracker tickets that recorded change requests. That came out as 21,820 messages and 786 requests over two years.

Across that corpus, together with the map and the manuals, we built a graph of connections with Graphify. Nodes: error codes and symptoms, hardware, product features, objects on the payment side. An edge is co-occurrence inside one request. The point isn't frequency, it's the junctions: which places the diagnosis of almost any conversation runs through. The result came out different from a plain count of topics. The biggest topic turned out to be closed in on itself, while the genuinely cross-cutting one was issuing payment credentials and binding them to a device. Clustering also split two decline codes into different communities, which gave us a hypothesis that they are errors of different natures: settings on the device itself against a refusal on the external provider's side.

Then the map, the manuals and the graph together produced an analysis of the tight spots along the customer's path. The work started out as a rewrite of the manuals and led somewhere else: a confusing spot gets closed on four layers, and the manual is the third of them. The layers run in a strict order, from the foundation upwards, and you only move to the next one if the previous one didn't answer the question:

1. Rebuild the product and the processes, meaning everything the customer goes through end to end: the path from the website to a running device, the order of work inside the company, the design of the product itself. This is where the rewritten customer path went, with tickets to change the website, the internal processes and the product. The lowest layer and the most expensive one: if the question is born here, no hint and no instruction will remove it.
2. Fix the interface so there's nothing left to explain, and put a short line of text in place where an explanation is unavoidable. Not a question-mark icon: nobody clicks the icon.
3. Write a short manual where an explanation is unavoidable. The first instruction, on setting prices on the device, was assembled straight off the map without pulling developers away for answers.
4. Put a one-page insert in the box, the way a new iPhone does it: where to start once the device is unpacked.

Something nobody was looking for came out along the way: the manual in force gives customers the wrong instruction about the data an external party checks at connection. And two of the review's own main conclusions had to be withdrawn, because the code showed that an interface everyone believed was missing already existed.

Testing new epics. The map was handed to the testers as the input for an agent: an epic comes in from the tracker, the agent uses the map to find the affected screens, knows their contents, their fields and their validation rules, builds cases out of that and runs them. Before this, testing was the bottleneck of the whole development process: developers were shipping faster than the team could check, and negotiating inside the team changed nothing. What was missing wasn't willingness but a description of the product from which cases can be assembled mechanically. The trend figures are in section 4: about ×3 on tickets per day and on weekly intake and output over a month and a half, and about two free days out of five at the old volume. The growth came from packing the process into agent playbooks, not from "switching on AI". Absolute counters are secondary here.

Working one screen down to the level of commands. We built the mapping "setting in the interface → command sent to the device → parameters". The screen description grew from 398 to 651 lines, and eight finds split into four filed bugs, three "works as intended" verdicts and one deleted setting.

A storyboard instead of the designer's. Shooting ten screens gave 64 frames and, along the way, six finds that aren't visible in the code: an add form carries an "update" heading; an empty value in a list column prints with a typo; a specific date is hard-coded into the text of a service screen; in every mode with eight positions, the eighth "price / label" pair is disabled; one of the sixteen payment-connection forms has no instruction at all; the unfinished setup wizard disagrees with the main form, one position short and with a typo in a step label. Of the six, one went straight into a ticket and the rest are waiting on the owner to say whether it's intended. The rule "before filing a ticket, check the open tickets that contradict it" paid off here too: a ticket had been sitting since last year asking to remove some of the connection methods from the product, and with it the meaning of the find changed. That ticket was cancelled. One more find came out of comparing a frame with the description: a field on the second step of registration had long been taken out of the code but not out of the document.

Bringing the map up to date after releases. We take the closed tickets together with the discussion in their comments and check them against the code. That's how what was actually built got into the map, and separately the places where the implementation diverged from the spec.

Writing requirements for a new project. The map of an adjacent product showed that the screen we needed simply isn't there: external devices in the registry can't be edited and have no page of their own. The requirements branch and the acceptance criteria were rewritten before development, and the requirements themselves carry links to the ready mechanisms in the neighbouring product.

Describing our own work to the outside. The map is ready-made evidence of scope and authorship: what was built, in what form, and to what depth.

8. How to keep it current

• After noticeable changes in the product: take the closed tickets, read the comments on them, check against the code. The implementation goes into the map, not the spec: what was built often differs from the ticket description, and that difference gets recorded too.
• A screen that changed is reshot in full, not one frame at a time. A set of frames from different versions of the interface is worse than no set at all. Same when the shooting conditions change: window width, hidden elements, the entity you picked.
• The working copy of the map lives in the product repository, the team copy in the shared one. After edits to the working copy, the team copy is synced through a separate branch and a merge request.
• Reread the "Product gaps" section before writing new tickets: some of the entries close themselves when developers build an adjacent feature differently from the description.