Skills/Rpa_Skills
8
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add rpa-bot-handoff skill: ops guide for bot handover

Browse Source 
The skill scans a bot with subagents (never runs it) and writes
HANDOVER.md, an 11-section ops guide in the operator's order: where is
what, how to run, how long to wait, after the run, how to see an
exception, exception list, how you will know, how to tell us, don'ts,
issues seen before. Dev material (check against 12 failure classes from
Tebra Auto Post, gaps with file:line, incidents) goes to HANDOVER-DEV.md.

Also adds ADR-0004, glossary terms, five fixture bots and a handoff eval
runner (--resume, --regrade) with results from 47 runs of the earlier
13-section version. The grader still expects that structure and must be
updated before the next eval run.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
VasanthandClaude Opus 5.5 committed 2026-10-28 15:01:42 +05:30
1 parent 3d2db6aca6
commit 3942fad6cd
143 files changed
+11815 -2
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

tests/evals/results/handoff/h-packaged-desktop-full-r3.md
+172
View File
@@ -0,0 +1,172 @@
# 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 checks the day's bank statement against the **LedgerPro** accounting app and adds any entry that is missing from LedgerPro. You give it one bank-statement Excel file. It opens LedgerPro, exports LedgerPro's entries to Excel, compares every statement line with them by reference number and amount, and types each missing entry into LedgerPro (New Entry → reference → amount → Save). At the end it writes one result file, `data/output/Reconcile_<date>_<time>.xlsx`, with one row per statement line. It drives one desktop app: **LedgerPro**. It does this by looking for pictures of LedgerPro's buttons on the screen and clicking them, so the screen must look exactly the way it did when those pictures were taken.
## 2. How it works
```
launcher.exe (what you start)
└─ checks for an update, then starts → LedgerBot.exe ──clicks & types──> LedgerPro
│ (do not touch while it runs)
├─ reads → your bank statement Excel
├─ reads → data/ledger_export.xlsx (LedgerPro's export)
├─ writes → data/output/Reconcile_<date>_<time>.xlsx
└─ writes → logs/ledger_<date>.log
logs/notfound_<button>.png (only on a problem)
```
- **launcher.exe** asks the update server whether a newer LedgerBot exists, installs it if so, then starts LedgerBot.exe. If it cannot reach the server it starts the current build without telling you.
- **LedgerBot.exe** does the actual work. It has no window of its own with buttons; it only moves the mouse and types.
- **LedgerPro** is the accounting app the bot drives. Hands off it while the bot runs.
- **Your bank statement Excel** is the input (see section 3 for its layout).
- **data/ledger_export.xlsx** is LedgerPro's own export; the bot reads it as "what LedgerPro already has".
- **data/output/Reconcile_….xlsx** is the result file: columns Reference, Amount, Result, Note.
- **logs/ledger_<date>.log** gets one line per statement line (reference, result, note). One log file per day; several runs on the same day go into the same file.
- **logs/notfound_<button>.png** is a screenshot taken when the bot could not find a button.
**One run, step by step:**
1. Finds the LedgerPro shortcut on the Desktop and starts LedgerPro.
2. Waits 15 seconds for LedgerPro to open.
3. Clicks LedgerPro's **Export to Excel** button, then waits 10 seconds.
4. Reads `data/ledger_export.xlsx` (LedgerPro's entries) and your statement Excel.
5. For each statement line: OK if LedgerPro has the same amount, Mismatch if the amount differs, Missing if LedgerPro does not have the reference at all.
6. For each Missing line: clicks **New Entry**, types the reference, Tab, types the amount, clicks **Save**.
7. After the last line, saves the result file. **The result file only exists if the bot reaches this step.**
## 3. Before a run
- [ ] Start the bot by **dragging the bank statement Excel onto `launcher.exe`** (or a shortcut that passes the statement file). Started without a file, the bot stops at once with no result file.
- [ ] LedgerPro's **Export to Excel** saves to `data\ledger_export.xlsx` next to LedgerBot.exe. Check the file's modified time changes on each run (E08).
- [ ] **Display scaling is 100%** (Settings → System → Display → Scale), screen resolution 1920 × 1080. At 125% the bot misses buttons (section 9).
- [ ] The **LedgerPro shortcut** is named exactly `LedgerPro` and sits on your Desktop or on the Public Desktop. Otherwise the run stops at once (E01).
- [ ] The folders `logs` and `data\output` exist next to LedgerBot.exe. If `logs` is missing the bot does not start; if `data\output` is missing the bot does all the posting and then **cannot save the result file** (E07).
- [ ] Bank statement Excel layout - the bot reads only the **first sheet**:
- Row 1 is a header; data starts at row 2.
- Column A = reference, column B = amount. Other columns are ignored.
- Amount must be a real number cell. Good: `1234.50`. Bad: `1,234.50 USD`, `$1234.50` typed as text, or an empty amount cell. One bad amount stops the whole run before anything is compared (E06).
- A row with an empty reference is skipped silently.
- **Each reference only once.** If the same reference appears twice, the bot keeps only the last one and the other line is not in the result file at all.
- The reference must be spelled exactly as it will appear in LedgerPro (`REF-1001` and `REF 1001` are different references).
- [ ] Amounts are compared to the cent: a difference of more than 0.01 is a Mismatch.
- [ ] Note the version: see section 10.
## 4. During a run
- **Hands off the mouse and keyboard.** The bot types into whatever window has focus. If you click elsewhere, the reference and amount get typed into that window.
- Keep LedgerPro **maximised and visible**, with nothing on top of it. No other window may show something that looks like LedgerPro's buttons (for example a screenshot or a second LedgerPro).
- Do not lock the screen and do not let the screen saver start - the bot can only click what is visible.
- **To stop the bot:** close the LedgerBot console window (or end `LedgerBot.exe` in Task Manager). Moving the mouse into the top-left corner of the screen also stops it. Closing LedgerPro does **not** stop it - the bot keeps looking for buttons and then stops with an error. **Whichever way you stop it, no result file is written**, so treat the run as in section 7, E07.
- How long it waits: about 25 seconds to open LedgerPro and export, then up to **20 seconds per button**. If nothing moves on screen for more than a minute, the bot has stopped or is stuck - check whether the LedgerBot window is still open.
## 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 your run. No new file = the run did **not** finish (E07). |
| Which lines failed? | Result file → filter column **Result** = `Error` (and review `Mismatch`). |
| Why did one line fail? | Result file → column **Note**. Then `logs\ledger_<date>.log`, search for the reference. |
| What did the screen look like? | `logs\notfound_<button>.png` (only the latest one per button - older ones are overwritten). |
| Why did the whole run stop? | The LedgerBot console window, **if it is still open** - the reason is shown there only. It is not in the log file (see section 13). |
| Did the bot already retry? | It never retries. Every Error is final for that run. |
| Which version is running? | Not shown anywhere today (see section 10 and section 13). |
## 6. Statuses
The result file has no colours. These are all the values the bot writes in **Result** and **Note**:
| Result | Note | Meaning | What ops does |
|---|---|---|---|
| OK | (empty) | LedgerPro already has this reference with the same amount. | nothing |
| **Missing** | **Posted** | The reference was not in LedgerPro. The bot typed it in and clicked Save. **"Missing" here means "was missing, bot added it"** - it is the normal outcome of a post. The bot does **not** check that LedgerPro accepted the save. | Spot-check a few in LedgerPro. If one is not there, see E05. |
| **Mismatch** | `LedgerPro has <amount>` | LedgerPro has this reference but with a different amount. **The bot changes nothing.** | Needs follow-up: compare with the statement and correct LedgerPro by hand. |
| **Error** | `Button new_entry.png not found on screen` | The bot could not find LedgerPro's New Entry button. Nothing was typed for this line. | E03 |
| **Error** | `Button save_btn.png not found on screen` | The bot typed reference and amount but could not find Save. The entry is **not saved**, and the half-filled entry form may still be open. | E04 |
A value you will never see but which the code mentions: Note `Not in LedgerPro - posting` is always replaced by `Posted` or by an error text before the file is saved.
## 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 | Bot stops at once, LedgerPro never opens; console shows "LedgerPro shortcut not found on the Desktop" | It looks for a shortcut named `LedgerPro` on your Desktop and the Public Desktop | Console window only. No result file. | System | Ops | Put the LedgerPro shortcut on the Desktop with that exact name. Run again. | The shortcut is there and it still fails |
| E02 | LedgerPro opens but nothing is clicked; bot stops after ~20 s; console shows "Button export_excel.png not found on screen" | It searches the screen for 20 s for a picture of the Export to Excel button | Console window; `logs\notfound_export_excel.png`. No result file. | System | Ops, then Dev | Check display scaling is 100%, LedgerPro is maximised and fully loaded (on a slow day it can take longer than 15 s to open). Run again. | Fails twice with scaling at 100% - send the screenshot |
| E03 | Result = Error, Note `Button new_entry.png not found on screen` | Searches 20 s for the New Entry button | Result file; log line; `logs\notfound_new_entry.png` | System | Ops | Check LedgerPro: nothing was entered for this reference. Look at the screenshot: a popup or dialog in LedgerPro usually explains it - close it. Run again with the same statement; lines already posted now show OK. | More than one line per run, or it repeats on the re-run |
| E04 | Result = Error, Note `Button save_btn.png not found on screen` | Clicked New Entry and typed, then searched 20 s for Save | Result file; log line; `logs\notfound_save_btn.png` | System | Ops | In LedgerPro, check the entry for this reference: it is usually **not** saved and a half-filled entry form may still be open - cancel it. The **next** line may also have been typed into that open form, so check the next reference too. Then run again. | It happens on every line, or scaling is already 100% (this was the 125% scaling incident) |
| E05 | Result = Missing / Posted, but the entry is not in LedgerPro (or has wrong text in it) | The bot only clicks Save; it does not check for a "saved" message | Nothing - the row looks normal | System | Ops | Add the entry in LedgerPro by hand, or run again (the line then comes out Missing again and is re-posted). **Check LedgerPro before re-running** so you do not post twice. | It happens more than once a week |
| E06 | Bot stops right after the export; console shows an error about converting a value to a number (for example "could not convert string to float") | It turns every amount in column B (statement and LedgerPro export) into a number; a text or empty amount stops the run | Console window only. No result file. Nothing was posted yet. | Business | Ops | Fix the amount column in the statement (real numbers, no currency signs, no empty amounts). Run again. If the statement is fine, the bad value is in LedgerPro's export - escalate. | The statement is clean and it still stops |
| E07 | **No new result file** after the run (bot window closed, or stopped half-way) | Any stop in the middle (button not found before posting, mouse in the corner, window closed, `data\output` missing, crash) | Only the log lines for lines already handled. The console message is lost once the window closes. | System | Ops, then Dev | Lines in today's log **were** handled - Missing lines there were posted. Do **not** run again blindly: first check that `data\output` exists and that LedgerPro is closed, then run again. Posted lines will now show OK. | Twice in a row, or the console message is not one of E01-E06 |
| E08 | Result file shows Missing for references that are already in LedgerPro, or OK for ones that are not | The bot reads `data\ledger_export.xlsx`. If today's export did not save there, it reads an **older** export without noticing | Nothing - looks like a normal run | System | Ops, then Dev | Before a run, check the date of `data\ledger_export.xlsx` changes when the bot exports. If it did not, stop the bot and escalate - re-running would post duplicates. | Always - the export path needs a dev fix (section 13) |
| E09 | A statement line is missing from the result file | Duplicate reference in the statement: the bot keeps only the last one; or an empty reference cell: skipped | Nothing | Business | Ops | Make every reference unique in the statement; fill empty references. | Never - input fix |
| E10 | Version did not change after an update, or the bot starts but behaves like an older build | The launcher gives up silently if the update server is unreachable or its certificate is not trusted | Nothing | System | Dev | Report the machine name and what version you expected. | Always |
**What to send for every "Dev" escalation** (in #rpa-support): the exception ID (E02…), the date and time of the run, the statement file name (not its content), `logs\ledger_<date>.log`, any `logs\notfound_*.png` - **check the screenshot shows no client names or amounts first, or crop it** - and a photo or copy of the console message if the window is still open.
## 8. What the bot recovers by itself
| Problem | What the bot does | Limit | After the limit |
|---|---|---|---|
| Button not on screen yet | Looks again every second | 20 s per button | Export button: run stops (E02). New Entry / Save: line = Error, next line (E03/E04) |
| LedgerPro slow to open | Fixed wait, no check | 15 s, then the 20 s button search | E02 |
| Export slow to save | Fixed wait, no check | 10 s | Reads whatever export file is there (E08) |
| Anything else | **Nothing.** No retries, no restarts, no resume. | - | Run stops, no result file (E07) |
There is no watchdog and no automatic re-run. A run either finishes with a result file or stops; you never need to wait for the bot to "try again".
## 9. Known incidents
| When / version | What ops saw | Cause | What to do now | Ops could handle? |
|---|---|---|---|---|
| 2026-10-23 (fix recorded), 3.2.0 | Bot started but could not find any button in the exe build | Button pictures were not packed into the exe | Fix recorded in git; see section 13 item 3. If **every** button fails on a fresh install, escalate (E02). | No |
| 2026-10-23 (fix recorded) | Save clicked in the wrong place / missed on some laptops | Laptops at 125% display scaling; button pictures taken at 100% | Keep display scaling at **100%** (section 3) | Yes |
| 2026-10-23 (fix recorded) | Two laptops never got the new version | Launcher silently ignored the update server's untrusted (self-signed) certificate and kept starting the old build | Compare the version after every release (section 10); escalate E10 | Partly |
| 2026-09-05 (log) | One line Error "Button save_btn.png not found on screen" | Matches the 125% scaling incident | E04 | Yes |
## 10. Releases and version check
- How an update arrives: start the bot through **launcher.exe**, never LedgerBot.exe directly. The launcher downloads and unpacks the new build before starting the bot.
- How to confirm it applied: **today you cannot see the version on screen** - the bot has no window title or About box. Until the dev team adds one (section 13), ask in #rpa-support for the expected release date and compare the date of `LedgerBot.exe` in the program folder.
- If the version did not change: the launcher failed silently (no internet, or the update server's certificate is not trusted on this machine). Escalate E10 with the machine name. Do not copy files between laptops yourself.
## 11. Escalating to dev
Send in Teams **#rpa-support**: exception ID from section 7, date and time of the run, machine name, `logs\ledger_<date>.log`, the `logs\notfound_*.png` screenshot (cropped of client names and amounts), and the console message if still visible.
Never send: passwords, the `.env` settings file, the bank statement itself, or client names and amounts in chat.
## 12. Failure-class check
- F1 Missing prerequisite - covered in section 3 (shortcut, folders, scaling) and E01, E07; section 13 items 3, 7.
- F2 Wrong window / focus - covered in section 4 (hands off, LedgerPro maximised, nothing on top) and E04 (typing into the wrong form).
- F3 Target app slower or different - covered in E02-E04, section 8 (15 s / 10 s fixed waits, 20 s per button), section 3 (100%, 1920 × 1080); section 13 item 5.
- F4 Input read differently - covered in section 3 input rules and E06, E09.
- F5 Marked done when nothing was done - covered in E08 (stale export read as current); section 13 item 4.
- F6 Action happened but not confirmed - covered in E05 and E04; section 13 item 2.
- F7 Business exception shown as success - covered in section 6 (Missing = posted; Mismatch needs follow-up); section 13 item 6.
- F8 Endless re-runs / watchdog - not applicable: the bot has no re-run loop and no watchdog; every wait has a fixed limit (section 8).
- F9 Stopping the wrong way - covered in section 4 (close the console window; closing LedgerPro does not stop it) and E07.
- F10 One stuck item blocks the queue - not applicable: there is no batch, queue or lock; each run is independent and an Error line does not block anything.
- F11 Cause hidden from ops - covered in section 5 (console-only messages) and section 13 items 1, 8.
- F12 Update did not arrive - covered in section 10 and E10; section 13 items 9, 10.
## 13. Fix before handover (dev team)
| # | Gap | Why it hurts ops | Where (file:line) |
|---|---|---|---|
| 1 | A run that stops writes **no result file**: the workbook is saved only after the last line, and nothing catches errors outside `post_entry`. Lines already posted are only in the log. | Ops cannot tell which entries were posted; risk of double posting on re-run | `app.py:86-96` |
| 2 | No confirmation after Save: `post_entry` returns as soon as Save is clicked; the note "Posted" is written without checking LedgerPro accepted it. After a Save-not-found error the half-filled form stays open and the next line types into it. | Silent missing or corrupted entries (E04, E05) | `app.py:65-70`, `app.py:88-92` |
| 3 | The "fix" commits only added comments. `ledgerbot.spec` is entirely commented out (the `datas` line is a comment), and the files in `assets/` are 16-byte placeholders, not real button pictures - the 100%-scaling recapture is not in the repo. | A fresh build may again have no button images | `ledgerbot.spec:2-3`, `assets/*.png`, commits `2ade1d3`, `158175d` |
| 4 | Stale export: bot clicks Export and reads `data/ledger_export.xlsx` after a fixed 10 s, with no check that the file is new (and nothing tells LedgerPro to save to that path). | An old export makes the bot re-post entries already in LedgerPro (E08) | `app.py:77-79` |
| 5 | Fixed waits (15 s start, 10 s export) instead of waiting for a screen. Also: newer pyautogui raises an exception instead of returning nothing when an image is not found, which would skip the 20 s retry loop entirely; `requirements.txt` does not pin versions. | Run stops on a slow day; behaviour depends on which library version was packed | `app.py:39-41`, `app.py:76-78`, `requirements.txt` |
| 6 | Result "Missing" is kept for lines that were successfully posted (Note "Posted"); summary counts them as Missing. | Ops reads a successful post as a problem | `app.py:86-93` |
| 7 | `logs/` and `data/output/` are not created by the code. Missing `logs` stops the bot on start; missing `data/output` fails **after** all posting. | Posted entries with no result file | `app.py:24`, `app.py:96` |
| 8 | Run-stopping errors and the summary counts go to the console only (`print`), not to the log file. | Cause lost when the window closes | `app.py:97`, `app.py:101` |
| 9 | Launcher still swallows every update error (`except Exception: return None`) - the SSL-incident "fix" is only a comment. A download or unzip failure is **not** caught and stops the launcher, so the bot never starts. Version check is `!=`, so an older version on the server downgrades every machine. | Machines silently stay on, or roll back to, old builds | `launcher.py:15-20`, `launcher.py:25-29`, commit `0085285` |
| 10 | Version is not shown anywhere (the comment says "window title" but there is no window); launcher compares against its own built-in copy of the version, so after an update it may download again on every start. | Ops cannot confirm an update applied | `app.py:15`, `launcher.py:9` |
| 11 | `notfound_<button>.png` is overwritten each time and is a full-screen screenshot that can contain client names and amounts. | Evidence lost; screenshots need cropping before sharing | `app.py:45` |
| 12 | `.env` is committed to git (the code does not read it). | Possible secrets in the repo history | `.env`, commit `cd9e04d` |
| 13 | Duplicate references in the statement collapse silently (dict keeps the last). | A real bank line disappears from the result | `app.py:81` |
| 14 | The 2026-09-05 log has a Mismatch line with a party name in brackets that the current code does not write. Either the deployed build differs from this source, or names reach the log. | Ops may be running code nobody can read; client names in a file ops share | `logs/ledger_20260905.log:3` vs `app.py:60` |
| 15 | No popup handling: any LedgerPro dialog (login prompt, Save As on export, warning) blocks every button search. | Run stops with "not found" and no hint that a dialog was the cause | `app.py:37-46`, `app.py:77` |