Rpa_Skills/tests/evals/results/handoff/h-packaged-desktop-full-r1.md

LedgerBot - ops handover

Version 3.2.0 · Written 2026-10-23 · Escalation: RPA dev team, Teams channel #rpa-support

1. What the bot does

LedgerBot reconciles the daily bank statement Excel against the LedgerPro desktop accounting app. You give it the statement file. It opens LedgerPro, exports LedgerPro's entries to Excel, and compares the two by reference:

• When the reference and amount match, it does nothing.
• When the amount differs, it reports the difference and changes nothing.
• When the reference is not in LedgerPro, it types the entry into LedgerPro and saves it.

It writes one result file per run, data/output/Reconcile_<date>_<time>.xlsx. It drives one app, LedgerPro, by finding buttons on the screen from pictures and clicking them. Entries that are in LedgerPro but not in the statement are ignored and are not reported.

2. How it works

launcher.exe (what you start, with the statement file)
   ├─ checks the update server → downloads and unpacks a new build if there is one
   └─ starts → LedgerBot.exe (no window of its own) ──drives──> LedgerPro
                    │                                  (do not touch while it runs)
                    ├─ writes → data/output/Reconcile_<date>_<time>.xlsx   (only at the very end)
                    ├─ writes → logs/ledger_<date>.log                     (one line per entry)
                    └─ writes → logs/notfound_<button>.png                 (screenshot when a button is not found)

• launcher.exe checks for an update, then starts the bot and closes itself straight away.
• LedgerBot.exe does all the work. It has no window and no Stop button.
• LedgerPro is the app the bot clicks and types in. While the bot runs, the mouse and keyboard belong to the bot.
• The Reconcile file is the result of the run. It is saved only after the last entry is done.
• The daily log gets one line per entry: the reference, the result and the note.
• The screenshot is a picture of the whole screen at the moment a button could not be found.

One run, step by step:

1. Starts LedgerPro from the LedgerPro shortcut on the Desktop.
2. Waits 15 seconds, then clicks LedgerPro's Export to Excel button.
3. Waits 10 seconds, then reads the LedgerPro export.
4. Reads the bank statement.
5. For each statement row: OK, Mismatch, or a missing entry, which it posts with New Entry → reference → Tab → amount → Save.
6. Saves the Reconcile file.

3. Before a run

• Windows display scaling is 100% and the resolution is 1920x1080 (Settings → System → Display). At 125% the bot cannot find the buttons (incident in section 9). LedgerPro must open on that screen.
• The LedgerPro shortcut (named exactly LedgerPro) is on your Desktop or the Public Desktop.
• LedgerPro opens already signed in and ready within 15 seconds. The bot does not sign in.
• LedgerPro's Export to Excel saves to the bot's data folder as ledger_export.xlsx, overwriting the old one. The bot only clicks Export. If an old export is still there, the bot compares against yesterday's ledger and can post entries twice (E07). Ask dev to confirm this is set up on your machine.
• The logs, data and data/output folders exist next to LedgerBot.exe. If logs is missing, nothing starts. If data/output is missing, the whole run's results are lost at the end.
• The statement Excel follows these rules. The bot reads the first sheet, starting from row 2:

Rule	Good	Bad
Row 1 is a header	Reference | Amount	The first entry in row 1. It is skipped.
Column A holds the reference, column B the amount	TX-1001 | 250.00	Amount in column C
The amount is a plain number	250.00	$250.00, 250,00, n/a. The whole run stops with no result file.
Each reference appears once	One row per reference	The same reference twice. Only the last one is checked, and the other disappears from the result file.
No blank reference in the middle	Every row has a reference	A blank reference. That row is skipped without any message.

• Start the bot by dropping the statement Excel onto launcher.exe, or by starting launcher.exe with the file path. If no file is given, the bot stops at once and nothing happens.
• After a new release, check the version (section 10).

4. During a run

• Don't use the mouse or keyboard on this machine. The bot types into whatever window has focus. If you click elsewhere, the reference and amount are typed into that window.
• Don't open other windows over LedgerPro, and don't move LedgerPro to another monitor.
• Don't move the mouse into a screen corner. That is the emergency stop, see below.
• To stop the bot there is no Stop button. Use one of these:
  • Move the mouse hard into a corner of the screen. The bot stops at its next click or keystroke.
  • Or end LedgerBot.exe in Task Manager.
  • Closing LedgerPro does not stop the bot. It keeps clicking and typing into whatever is on the screen.
  • Closing launcher.exe does nothing, because it has already exited.
  • Either way, no Reconcile file is written. Use the log (E05).
• A run looks stuck when LedgerPro does nothing for more than about 20 seconds. The bot waits 20 seconds for each button, then gives up on that entry. There is no other watchdog. The bot finishes or stops by itself, so wait for it.
• The run is finished when a new Reconcile_<date>_<time>.xlsx appears in data/output.

5. Where to look when something goes wrong

Question	Where to look
Did the run finish?	A new Reconcile_<date>_<time>.xlsx in data/output with the time of this run. No new file means the run stopped early (E04 / E05).
Which entries failed?	The Reconcile file, Result column = Error or Mismatch
Why did one entry fail?	The Reconcile file, Note column. Then logs/ledger_<date>.log: search for the reference.
What did the screen look like when a button was not found?	logs/notfound_new_entry.png, logs/notfound_save_btn.png, logs/notfound_export_excel.png. Each one shows only the most recent failure for that button. Check its time.
The run stopped early. What was done?	logs/ledger_<date>.log. Each line written during this run is an entry the bot finished. A line saying Missing Posted means the bot posted that entry.
Did the bot already retry?	It never retries an entry. It only waits up to 20 s for each button (section 8).
Was the entry really saved in LedgerPro?	Only LedgerPro can tell you. The bot does not check after Save (E06).
Which version is running?	Nothing on screen shows it. See section 10.

6. Statuses

The Reconcile file has no colours. Each row's status is the Result column plus the Note column.

Result	Note	Colour	Meaning	What ops does
OK	(empty)	none	The reference and amount match LedgerPro	nothing
Missing	Posted	none	The entry was not in LedgerPro and the bot posted it. "Missing" here means "was missing, now posted". The bot did not confirm that the save worked.	Spot-check a few in LedgerPro (E06)
Missing	Not in LedgerPro - posting	none	Temporary note. It is always replaced by Posted or by an error before the file is saved.	You should never see it. If you do, contact Dev.
Mismatch	LedgerPro has <amount>	none	Needs follow-up. The reference exists, but the amount in LedgerPro differs by more than 0.01. The bot changed nothing.	Correct it by hand (E01)
Error	Button new_entry.png not found on screen	none	The entry was not posted. The bot could not find New Entry.	E02
Error	Button save_btn.png not found on screen	none	The entry was typed but not saved. A half-filled form may still be open in LedgerPro.	E03

7. Exception catalogue

ID	What you see	How the bot identifies it	Where it is recorded	Type	Who acts	What to do	Escalate when
E01	Row Mismatch, note "LedgerPro has 240.00"	The reference is in both files, but the amounts differ by more than 0.01	Reconcile file; log line	Business	Ops	Check the bank statement and LedgerPro, then correct the right one by hand. The bot never fixes amounts.	Many rows mismatch by the same pattern, which suggests a wrong export or a wrong file
E02	Row Error, note "Button new_entry.png not found on screen"	It looks for the New Entry button picture for 20 s. When it is not found, it saves a screenshot and moves on to the next entry.	Reconcile file; log line; logs/notfound_new_entry.png	System	Ops, then Dev	1) Check that display scaling is 100% and 1920x1080. 2) Open the screenshot: was a popup or another window covering LedgerPro? 3) Post the entry by hand in LedgerPro, or re-run (see E07 first).	Scaling is 100%, nothing covered LedgerPro, and it still happens. Send the time, the reference, the screenshot and the log file.
E03	Row Error, note "Button save_btn.png not found on screen"	The bot clicked New Entry and typed the reference and amount. It then could not find Save for 20 s, saved a screenshot and moved on.	Reconcile file; log line; logs/notfound_save_btn.png	System	Ops	1) In LedgerPro, look for an unsaved, half-filled entry and cancel it, or save it if it is correct. 2) Check the next entry after this one too. The bot may have typed it into the same open form. 3) Check scaling as in E02. 4) Post the entry by hand.	Same as E02
E04	No new Reconcile file, and no new lines in today's log	The run stopped before checking any entry. Possible causes: LedgerPro shortcut not found; LedgerPro not ready within 15 s; Export button not found (a new logs/notfound_export_excel.png appears); the export file missing; a statement amount that is not a number; no statement file given. The cause is not written anywhere.	Nothing, except possibly the export screenshot	System	Ops, then Dev	Work through section 3: shortcut, LedgerPro signed in, scaling, the statement amounts are plain numbers, you dropped the file onto launcher.exe. Then run again. Nothing was posted, so a re-run is safe.	It still fails after the checklist. Send the time, the statement file name (not its contents) and any notfound_export_excel.png.
E05	No new Reconcile file, but today's log has entry lines from this run	The run stopped part-way, or at the end while saving: you used the corner stop or Task Manager, the data/output folder is missing, or an unexpected error happened. The cause is not written anywhere.	Log lines only	System	Ops, then Dev	1) Use the log as the result. Every Missing Posted line was posted. 2) Entries with no line were not handled. 3) Re-run only with a fresh LedgerPro export (E07), or post the rest by hand.	Always report it unless you stopped the bot yourself. Send the time, the last log line and the log file.
E06	An entry marked Missing / Posted, but it is not in LedgerPro	After clicking Save, the bot does not check that LedgerPro saved the entry. It writes "Posted" as soon as the Save click happens.	Reconcile file says Posted. LedgerPro is the only proof.	System	Ops	Search LedgerPro for the reference. If it is not there, post it by hand.	More than one in a run. Send the time, the references and the log file.
E07	The same entry appears twice in LedgerPro	The bot posts every statement reference that is not in ledger_export.xlsx. If that export is old (the export didn't save over it, or a re-run happened after a partial run), entries already posted look "missing" again.	LedgerPro; two runs' Reconcile files or log lines both say Posted	System	Ops, then Dev	Delete the duplicate in LedgerPro. Before any re-run, make sure LedgerPro's export overwrites ledger_export.xlsx.	Always. The export setup needs fixing. Send both run times and the references.
E08	Typing appears in the wrong window, or LedgerPro gets odd values	The bot types blind into the window that has focus. It does not check that the window is LedgerPro.	Nowhere	System	Ops	Find and undo the stray typing. In LedgerPro, check the entries posted around that time. Keep hands off during runs (section 4).	It happens with nobody touching the machine
E09	launcher.exe shows an error or closes, and the bot never starts	Downloading or unpacking an update failed. The launcher has no error handling for this.	Nowhere, except the error box, if any	System	Dev	Take a screenshot of the error. Don't keep retrying.	Always. Send the time, the screenshot and the machine name.
E10	A fix that dev announced isn't working on this machine	The launcher could not reach the update server. It may be offline, or the machine may not trust the server's certificate. The launcher then runs the old build without any message.	Nowhere	System	Dev	Check the bot files' date (section 10).	The date did not change after a release. Send the machine name.
E11	A statement row is missing from the Reconcile file	The same reference appears twice in the statement, so only the last row is checked. Or the reference cell is blank.	Nowhere	Business	Ops	Fix the statement (section 3 rules) and check those rows by hand	-

8. What the bot recovers by itself

Problem	What the bot does	Limit	After the limit
A button (Export, New Entry, Save) is not on screen yet	Looks again every second	20 s per button	New Entry / Save: row = Error, screenshot saved, next entry. Export: the run stops (E04).
LedgerPro slow to start	Nothing. It waits a fixed time.	15 s	Carries on regardless. The usual result is E04.
Export slow to save	Nothing. It waits a fixed time.	10 s	Reads whatever ledger_export.xlsx is there, possibly an old one (E07)
Failed entry	No retry	-	Ops posts it by hand or re-runs
Run stopped	No restart, no resume	-	Ops follows E04 / E05

The longest the bot ever waits on one thing is 20 seconds. If nothing has happened for a minute, the run has ended. Check for the Reconcile file.

9. Known incidents

When / version	What ops saw	Cause	What to do now	Ops could handle?
2026-09 (fix 3b3625f)	Rows Error "Button save_btn.png not found on screen" on some laptops	Windows display scaling at 125%. The button pictures are matched at 100% only.	Button pictures were re-captured at 100%. Keep scaling at 100% and 1920x1080 (section 3). Follow E03 for affected rows.	Yes
(fix 30cb604)	Two laptops never received an update and kept running the old build	The update server's certificate isn't trusted on those laptops. The launcher hides the error and runs the old build.	Not fixed in code: the error is still hidden. After every release, check the version on each machine (section 10), then E10.	Partly
(fix 6694f19)	The packaged bot could not find any buttons	The button pictures were left out of the exe build	Build fix. Do a test run after each new release.	No

10. Releases and version check

• How an update arrives: launcher.exe checks the update server on every start. When the server reports a different version, the launcher downloads it and unpacks it into the bot folder.
• How to confirm it applied: the bot has no window, so the version is not shown anywhere. The only sign is the Date modified of LedgerBot.exe in the bot folder. It should match the release date dev announced in #rpa-support.
• If the date did not change: the update was skipped without any message (E10). Post the machine name in #rpa-support. Dev will copy the build over by hand or fix the certificate on the machine.
• After any release, do one test run with a small statement. Confirm a Reconcile file appears and that the rows are not all Error.

11. Escalating to dev

Post in Teams #rpa-support. Send:

• the exception ID from section 7 (for example "E05")
• the date and time of the run, and the machine name
• the logs/ledger_<date>.log file
• the matching logs/notfound_*.png screenshot, if there is one
• the Reconcile file name (attach it only if your team allows sharing it)

Never send passwords, the bot's settings file, or bank statement or ledger contents pasted into chat. The screenshots and logs show financial data, so share them only in #rpa-support.

12. Failure-class check

• F1 covered in section 3 (shortcut, folders, LedgerPro signed in, how to start) and E04, E09.
• F2 covered in section 4 (hands off, nothing over LedgerPro) and E08; no window check is in Fix #6.
• F3 covered in section 3 (100% / 1920x1080), E02, E03 and E04, and section 8 (20 s, 15 s and 10 s limits); fixed waits are in Fix #7.
• F4 covered in the section 3 input table and E11; fix in Fix #8.
• F5 covered in E06; fix in Fix #2.
• F6 covered in E03 and E06 (check in LedgerPro before re-posting); fix in Fix #2.
• F7 covered in section 6 ("Missing / Posted" means posted; Mismatch needs follow-up); fix in Fix #9.
• F8 not applicable: there is no automatic re-run and no watchdog. The risk from a manual re-run (double posting) is covered in E07.
• F9 covered in section 4 (corner stop or Task Manager; closing LedgerPro does not stop it).
• F10 not applicable: there are no batches, queues or locks, and each run stands alone. The one case of an item spilling into the next one (a half-filled form) is in E03.
• F11 covered in Fix #3, #4 and #5 (crash cause not recorded, summary not saved, screenshots overwritten).
• F12 covered in section 10, E09 and E10; fixes in Fix #1 and #10.

13. Fix before handover (dev team)

#	Gap	Why it hurts ops	Where (file:line)
1	The update check swallows every error (SSL, offline, bad JSON) and runs the old build without a message. The 30cb604 "fix" only added a comment.	Machines stay on old builds without anyone knowing (E10)	launcher.py:15-20
2	"Posted" is written right after the Save click. Nothing confirms that LedgerPro saved the entry.	Rows show Posted when nothing was posted (E06)	app.py:89-90, app.py:65-70
3	Crashes are not logged and not caught outside the posting step: missing shortcut, Export not found, missing export file, bad amount, missing argument, missing data/output. Only RuntimeError is caught. pyautogui's own exceptions (newer ImageNotFoundException, FailSafeException) also crash the run.	No result file and no cause anywhere (E04 / E05)	app.py:34, app.py:77-81, app.py:91, app.py:96, app.py:101
4	The Reconcile file is saved only at the end. A stop mid-run loses every result, including what was already posted.	Ops must rebuild the result from the log (E05)	app.py:96
5	Screenshots are named per button only, with no time or reference, so they overwrite each other. The run summary goes to stdout only, and nothing reads it.	Evidence is lost. There is no run start/end marker in the log.	app.py:45, app.py:97, app.py:95
6	No check that LedgerPro has focus before typing. A Save failure leaves a half-filled form, and the next entry types into it.	Stray or merged entries (E03, E08)	app.py:65-70, app.py:91-92
7	Fixed sleeps (15 s and 10 s) instead of waiting for LedgerPro or the export. The export file's freshness is never checked, and nothing in the code saves the export to data/ledger_export.xlsx, although the docstring says the bot does.	Stale export leads to double posting (E07)	app.py:76-79, app.py:50
8	Duplicate references in the statement or the export silently collapse into one. Blank references are skipped. A non-numeric amount crashes the run.	Rows vanish from the result (E11)	app.py:52, app.py:81
9	Posted entries keep Result = "Missing". Ops reads "Missing" as "not done".	Misleading status	app.py:87-90
10	No version is visible anywhere. The comment claims a window title, but the bot has no window. The spec is a commented-out stub, so the 6694f19 asset fix can't be verified from this repo. The launcher compares against the VERSION frozen into its own exe, and a running launcher.exe can't overwrite itself if the zip contains it (likely re-download on every start, or an unpack error). The download and unpack have no error handling.	Ops can't confirm a release; possible E09	app.py:15, ledgerbot.spec:1-3, launcher.py:9, launcher.py:25-29
11	No display-scaling or resolution check at startup. Ops must remember the 100% rule.	E02 / E03 at any other scaling	app.py:20
12	.env with LedgerPro credentials is committed to git, and no code reads it.	Credential exposure in the repo	.env (tracked)
13	The existing log from 2026-09-05 has a counterparty name in a Mismatch line, which the current code doesn't write. It came from an older build.	Logs may hold customer data. Purge or restrict the old logs.	logs/ledger_20260905.log:3
14	requirements.txt doesn't pin pyautogui or pyscreeze. Newer versions raise an exception instead of returning "not found", which breaks the 20 s wait and the screenshot.	E02 / E03 could become run crashes after a rebuild	requirements.txt, app.py:40