Add rpa-bot-handoff skill: ops guide for bot handover
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
1 parent
3d2db6aca6
commit
3942fad6cd
143 files changed
+11815
-2
No files matched your search
@@ -0,0 +1,37 @@
|
||||
# rpa-bot-handoff
|
||||
|
||||
A Claude skill that writes the **ops guide** for an RPA bot that is being handed over to an ops team.
|
||||
|
||||
## What you get
|
||||
**`HANDOVER.md`**: the ops guide, in plain words, for operators who don't read code:
|
||||
1. What this bot does
|
||||
2. Where is what: which tab, screen, file or folder shows what
|
||||
3. How to run: checklist and steps with the real button names
|
||||
4. How long to wait at each step, in seconds or minutes, and when to step in
|
||||
5. After the run: what each ending means, where the report is
|
||||
6. How to see an exception
|
||||
7. Exception list: message → where → meaning → what you do → wait or call us
|
||||
8. How you will know something went wrong
|
||||
9. How to tell the dev team, with a ready message template
|
||||
10. Don'ts, and the right way to stop the bot
|
||||
11. Issues seen before
|
||||
|
||||
**`HANDOVER-DEV.md`**: for developers. The check against 12 failure classes learned from Tebra Auto Post, the gaps to fix before handover (file:line), and the incident list.
|
||||
|
||||
## Install
|
||||
Copy this folder to `~/.claude/skills/rpa-bot-handoff/`.
|
||||
|
||||
## Use
|
||||
In your bot project, ask Claude: *"write the ops guide for this bot"* or *"document this bot for handover"*. The skill:
|
||||
1. Scans the code and history with subagents. It never runs the bot.
|
||||
2. Asks up to three things: how ops reaches the dev team, what ops can open, and any unclear statuses.
|
||||
3. Writes both files and checks them.
|
||||
|
||||
## Files
|
||||
| File | What it is |
|
||||
|---|---|
|
||||
| `SKILL.md` | Steps Claude follows |
|
||||
| `templates/HANDOVER.md` | The ops guide skeleton |
|
||||
| `templates/HANDOVER-DEV.md` | The dev notes skeleton |
|
||||
| `templates/failure-classes.md` | 12 failure classes from Tebra's first months with ops |
|
||||
| `templates/reference/tebra-auto-post.md` | Both files filled in for Tebra, scrubbed |
|
||||
@@ -0,0 +1,89 @@
|
||||
---
|
||||
name: rpa-bot-handoff
|
||||
description: Writes the ops guide for an RPA bot that is being handed over to an ops/support team. Scans the bot's code and history with subagents (never runs it) and writes HANDOVER.md, a plain-language guide that answers what an operator asks - which tab or screen shows what, how to run the bot step by step, how long to wait at each step, how to read the result and the report, how to see an exception and what each message means, how they will find out something went wrong, and exactly how to tell the dev team. It also writes HANDOVER-DEV.md for developers - a check against 12 failure classes learned from Tebra Auto Post and the gaps to fix before handover. Use when the user asks to "hand over a bot", "document a bot for ops", "write a handover doc", "ops guide", "runbook", "support doc", "operator guide" or "how ops should handle bot errors" for an RPA or automation project.
|
||||
---
|
||||
|
||||
# RPA bot handoff
|
||||
|
||||
Write two files in the bot's repo:
|
||||
- **`HANDOVER.md`**: the ops guide. The reader is an **operator who does not read code**. It answers their questions in the order they ask them: where is what, how do I run it, how long do I wait, how do I check the result, how do I see an exception, how will I know, how do I tell the dev team.
|
||||
- **`HANDOVER-DEV.md`**: for the dev team only. It holds the failure-class check and the gaps to fix before handover, with file:line.
|
||||
|
||||
| File | What it is |
|
||||
|---|---|
|
||||
| `templates/HANDOVER.md` | The ops guide skeleton: 11 sections. Keep their order. |
|
||||
| `templates/HANDOVER-DEV.md` | The dev notes skeleton. |
|
||||
| `templates/failure-classes.md` | 12 failure classes from Tebra Auto Post. Every one must be checked against the bot. |
|
||||
| `templates/reference/tebra-auto-post.md` | A filled example of both files for Tebra, scrubbed. Copy its depth and wording, not its content. |
|
||||
|
||||
Rules:
|
||||
- **Never run the bot.** Real bots act on live systems. Read code, config, logs and history only.
|
||||
- **Use the operator's words.** Name the real tab, button, column, colour and message the operator sees, exactly as the app shows them ("Report tab → File Status column → Error"). No file:line, no class or function names, no SQL in `HANDOVER.md`. File:line refs belong in `HANDOVER-DEV.md` only.
|
||||
- **Every wait is a number.** Take timeouts, retries and watchdog limits from the code, in seconds or minutes. Take normal durations from the logs when they show them; otherwise write "not measured".
|
||||
- **Write what the code does, not what it should do.** If a status is misleading (an item needing follow-up shows green), say so plainly in the ops guide and add it to the gaps in `HANDOVER-DEV.md`.
|
||||
- **Never copy** patient data (PHI), customer names, credentials, internal IPs, keys or `.env` values into either file. Logs are read for message types and durations only.
|
||||
- Change no code. The only output is the two files.
|
||||
|
||||
## 1. Scan (subagents are required)
|
||||
|
||||
**Always start the subagents.** Never write the guide from your own reading of the code. Send subagent A, and subagent B when there is history, in **one message** so they run in parallel. Tell each one: read-only, never run the bot, no PHI/credentials/IPs in the report, give file:line refs, under 1500 words.
|
||||
|
||||
**Subagent A: what the operator sees and does.** Ask it to report:
|
||||
1. **Screens:** every window, tab, page and button the operator uses, with its exact label and what it shows. Output files and folders ops can open, with name patterns and columns.
|
||||
2. **How to run:** how the bot starts (shortcut, exe, launcher, scheduler, button), what input it needs (file, sheets, columns, rules), and what the screen shows while it runs (progress, steps, checkpoint boxes, log).
|
||||
3. **Waits:** every timeout, retry count, restart limit and watchdog limit, in seconds, with the step it belongs to. Typical durations seen in the logs.
|
||||
4. **Result:** how a run ends (banner, colours, summary), and every status, comment and message the bot writes per item, with the colour it shows on screen.
|
||||
5. **Exceptions:** every place the bot detects a problem: what it checks, the exact message the operator sees, where it appears (screen, column, file), whether the bot retries by itself and how often, and what happens after the last retry.
|
||||
6. **Alerts:** whether the bot sends any email, popup, sound or notification when something fails. If not, say so.
|
||||
7. **Rules:** anything the operator must not do while it runs (use the machine, close an app, open other windows), and how to stop it safely.
|
||||
|
||||
**Subagent B: history.** Skip it only when there is no git history, bug log, changelog or release notes. Ask it to mine `git log` (fix/bug/hotfix commits), bug logs, changelogs, PROGRESS / RELEASE / DEPLOY notes, regression tests and recurring messages in `logs/`. For each real incident: what the operator saw, the cause, the fix, and **what the operator should do if it happens again**.
|
||||
|
||||
While they run, read `templates/failure-classes.md` and `templates/reference/tebra-auto-post.md`.
|
||||
|
||||
## 2. Ask once (one message, at most 3 questions)
|
||||
|
||||
Send a 5-line summary of what the scan found, then ask:
|
||||
1. **Escalation:** how ops tells the dev team: a chat channel, ticket queue or email group (a team or role, never a personal phone number), and how fast to expect an answer.
|
||||
2. **Ops access:** which places ops can open: the app's screens, the output folder, the log folder, the database. The guide sends ops only to places they can open. The rest go to the gaps in `HANDOVER-DEV.md`.
|
||||
3. **Unknowns:** any status or message whose meaning the code doesn't make clear. Skip this when there are none.
|
||||
|
||||
Default everything else: title from the project name, today's date, version from the project's version string.
|
||||
|
||||
## 3. Write `HANDOVER.md` (the ops guide)
|
||||
|
||||
Copy `templates/HANDOVER.md` to the bot's repo root and fill every `{{PLACEHOLDER}}`. Section notes:
|
||||
|
||||
1. **What this bot does:** at most 2 lines.
|
||||
2. **Where is what:** one row per tab, screen, file or folder the operator uses: what it shows and when to open it. Only places ops can open (question 2).
|
||||
3. **How to run:** a short "before you start" checklist (prerequisites, input rules with one bad and one good example), then numbered steps with the real button labels, then what a normal run looks like on screen.
|
||||
4. **How long to wait:** one row per step: normal time, how long the bot waits at most, what the bot does after that, and what the operator does. End with the line that answers "when do I step in?".
|
||||
5. **After the run:** what each ending colour or banner means, then exactly where the report is (tab, filter, columns) and how to export it.
|
||||
6. **How to see an exception:** the click path from the report to the message, then "find the message in section 7".
|
||||
7. **Exception list:** one row per message. Number them `E01`, `E02`... so ops can quote them.
|
||||
- *Message you see*: the exact text.
|
||||
- *Where*: tab and column, screen, or file.
|
||||
- *What it means*: one plain sentence.
|
||||
- *What you do*: numbered steps when there are several. Put any "check X **before** re-running" warning in bold.
|
||||
- *Bot retries / call us when*: "the bot retries 3 times, wait" or "call us if it fails again".
|
||||
8. **How you will know:** the alerts the bot sends, or "there is no alert: check the screen after every run", and when to check.
|
||||
9. **How to tell us:** the channel from question 1, what to send (run/batch ID, time, E-number, screenshot, file name), what never to send (passwords, patient or customer data), and a ready-to-copy message template.
|
||||
10. **Don'ts:** the rules from subagent A item 7, each with a short reason, plus the one right way to stop the bot.
|
||||
11. **Issues seen before:** from subagent B, newest first: what you saw, what to do now. One line each for incidents fixed for good.
|
||||
|
||||
## 4. Write `HANDOVER-DEV.md` (dev notes)
|
||||
|
||||
Copy `templates/HANDOVER-DEV.md` and fill it:
|
||||
- **Failure-class check:** walk `templates/failure-classes.md` one class at a time. Each class must end up in at least one of: a row in the ops guide (say which section or E-number), a gap in this file, or `F<n> not applicable: <reason>`. Never drop a class silently.
|
||||
- **Gaps to fix before handover:** each with why it hurts ops and file:line. Include every misleading status and every cause ops cannot see.
|
||||
- **Incidents:** the full list from subagent B with commit refs.
|
||||
|
||||
## 5. Verify
|
||||
|
||||
1. Every status and message from the scan appears in section 7 or section 5 of the ops guide.
|
||||
2. Every tab, button, column, file and folder named in the ops guide exists in the code or is created by it.
|
||||
3. Every row in section 4 has numbers, and every row in section 7 has all columns filled.
|
||||
4. Search both files for PHI, customer names, credentials, IPs, keys and `.env` values. There must be none.
|
||||
5. The ops guide has no file:line, class or function names, or SQL.
|
||||
6. `HANDOVER-DEV.md` accounts for all of F1-F12.
|
||||
7. Report to the user: sections filled, number of exceptions listed, failure classes covered vs not applicable, and the gaps for the dev team.
|
||||
@@ -0,0 +1,19 @@
|
||||
# {{BOT_NAME}}: dev notes for the handover
|
||||
|
||||
Version {{VERSION}} · Written {{DATE}} · The ops guide is `HANDOVER.md`. This file is for developers only.
|
||||
|
||||
## Failure-class check
|
||||
|
||||
{{ONE LINE PER CLASS F1-F12: "F<n> covered in HANDOVER.md section <s> / E<nn>", "F<n> gap <#> below", or "F<n> not applicable: <reason>"}}
|
||||
|
||||
## Gaps to fix before handover
|
||||
|
||||
| # | Gap | Why it hurts ops | Where (file:line) |
|
||||
|---|---|---|---|
|
||||
| 1 | {{GAP}} | {{IMPACT}} | {{REF}} |
|
||||
|
||||
## Incidents
|
||||
|
||||
| When / version | What ops saw | Cause | Fix | Ref |
|
||||
|---|---|---|---|---|
|
||||
| {{DATE / VERSION}} | {{SYMPTOM}} | {{CAUSE}} | {{FIX}} | {{COMMIT}} |
|
||||
@@ -0,0 +1,92 @@
|
||||
# {{BOT_NAME}}: ops guide
|
||||
|
||||
Version {{VERSION}} · Written {{DATE}} · Questions or problems: {{ESCALATION_CHANNEL}} (see section 9)
|
||||
|
||||
## 1. What this bot does
|
||||
|
||||
{{AT_MOST_2_LINES: what it does, in which app, from which input}}
|
||||
|
||||
## 2. Where is what
|
||||
|
||||
| Where | What you see there | Open it when |
|
||||
|---|---|---|
|
||||
| {{TAB / SCREEN / FILE / FOLDER}} | {{WHAT IT SHOWS}} | {{WHEN}} |
|
||||
|
||||
## 3. How to run
|
||||
|
||||
**Before you start**
|
||||
- [ ] {{PREREQUISITE: e.g. the target app is installed and you can sign in}}
|
||||
- [ ] {{INPUT RULE: e.g. one clinic per row. Wrong: "North, South". Right: "North" and "South" on two rows.}}
|
||||
- [ ] The app shows version {{VERSION}}.
|
||||
|
||||
**Steps**
|
||||
1. {{e.g. Open "<app name>" from the Desktop.}}
|
||||
2. {{e.g. On the Run tab, drop the input Excel on the upload box.}}
|
||||
3. {{e.g. Check the preview: every sheet has rows.}}
|
||||
4. {{e.g. Click "Trigger automation".}}
|
||||
|
||||
**What a normal run looks like:** {{e.g. the 7 checkpoint boxes turn green one by one; the live log shows each item}}
|
||||
|
||||
## 4. How long to wait
|
||||
|
||||
| Step | Normal time | The bot waits at most | After that the bot | What you do |
|
||||
|---|---|---|---|---|
|
||||
| {{STEP}} | {{e.g. 1 min, or "not measured"}} | {{e.g. 5 min}} | {{e.g. restarts the app, up to 3 times}} | {{e.g. nothing, wait}} |
|
||||
|
||||
**When do you step in?** {{e.g. only when the run ends red, or a box stays red after 3 restarts}}
|
||||
|
||||
## 5. After the run
|
||||
|
||||
| Ending | Meaning | What you do |
|
||||
|---|---|---|
|
||||
| {{e.g. green "Completed"}} | {{MEANING}} | {{ACTION}} |
|
||||
|
||||
**The report:** {{e.g. Report tab → choose the batch → File Status column. Export with the Excel button.}}
|
||||
|
||||
| Status | Colour | Meaning | What you do |
|
||||
|---|---|---|---|
|
||||
| {{STATUS}} | {{COLOUR}} | {{MEANING}} | {{ACTION or "nothing"}} |
|
||||
|
||||
## 6. How to see an exception
|
||||
|
||||
1. {{e.g. Report tab → filter File Status = Error.}}
|
||||
2. {{e.g. Read the Comments column.}}
|
||||
3. Find that message in section 7.
|
||||
|
||||
## 7. Exception list
|
||||
|
||||
| ID | Message you see | Where | What it means | What you do | Bot retries / call us when |
|
||||
|---|---|---|---|---|---|
|
||||
| E01 | {{EXACT MESSAGE}} | {{TAB → COLUMN, or FILE}} | {{ONE SENTENCE}} | {{STEPS}} | {{e.g. "Bot retries 3 times, wait. Call us if it fails again."}} |
|
||||
|
||||
## 8. How you will know
|
||||
|
||||
{{e.g. "There is no email or alert. Check the Dashboard after every run, and every morning for the night run."}}
|
||||
|
||||
## 9. How to tell us
|
||||
|
||||
- **Where:** {{ESCALATION_CHANNEL}}. Expect an answer within {{RESPONSE_TIME}}.
|
||||
- **Send:** {{e.g. batch ID, time of the problem, E-number from section 7, a screenshot of the screen, the report row}}
|
||||
- **Never send:** passwords, the settings file, or patient or customer data in chat.
|
||||
|
||||
Copy this message:
|
||||
|
||||
```
|
||||
Bot: {{BOT_NAME}} v{{VERSION}}
|
||||
Batch / run ID:
|
||||
Time:
|
||||
E-number and message:
|
||||
What I already did:
|
||||
Screenshot: attached
|
||||
```
|
||||
|
||||
## 10. Don'ts
|
||||
|
||||
- {{DON'T: e.g. "Don't use the mouse or keyboard while it runs. The bot's clicks land in the wrong window."}}
|
||||
- **To stop the bot:** {{THE ONE RIGHT WAY}}
|
||||
|
||||
## 11. Issues seen before
|
||||
|
||||
| When / version | What you saw | What to do now |
|
||||
|---|---|---|
|
||||
| {{DATE / VERSION}} | {{SYMPTOM}} | {{ACTION, or "fixed in vX, nothing to do"}} |
|
||||
@@ -0,0 +1,63 @@
|
||||
# Failure classes
|
||||
|
||||
Twelve kinds of problem Tebra Auto Post hit in its first months with ops. Check every new bot against each one. For each class: what to look for in the code, and where the ops guide (`HANDOVER.md`) or the dev notes (`HANDOVER-DEV.md`) must cover it. Section numbers are the ops guide's.
|
||||
|
||||
## F1. Missing prerequisite on the ops machine
|
||||
**Tebra:** a missing database driver gave a cryptic error only on some laptops; a missing settings file made the duplicate check fail silently; a helper app's shortcut wasn't where the bot searched; some bugs appeared only in the packaged exe, never under `uv run`.
|
||||
**Look for:** drivers, `.env` / settings files, shortcuts or install paths the bot searches, `sys.frozen` branches.
|
||||
**Doc:** the "Before you start" checklist in section 3, and the exact message each missing item produces in section 7.
|
||||
|
||||
## F2. The bot grabs the wrong window, or can't take focus
|
||||
**Tebra:** it matched its own window, and a database tool whose title held the target app's name, then closed the real app. Windows' foreground lock meant clicks landed elsewhere when someone used the machine during a run.
|
||||
**Look for:** window matching by title substring, focus / foreground calls, exclude lists.
|
||||
**Doc:** section 10: which windows must not be open, and hands off the machine.
|
||||
|
||||
## F3. The target app is slower, or different, than the bot expects
|
||||
**Tebra:** a screen took about 98 s under load against a 90 s timeout; two screens shared a header and were confused; controls drawn without accessibility elements; a long list put the target off-screen; a wrapped name was clicked between its lines on a small screen.
|
||||
**Look for:** every timeout value, screen-identification checks, "element not found" paths, screen-size assumptions.
|
||||
**Doc:** a section 7 row for each "not found / did not load" message, and the wait from section 4. Screen-resolution rules go in section 3.
|
||||
|
||||
## F4. Input data the bot reads differently than ops writes it
|
||||
**Tebra:** names containing commas were split into pieces and silently skipped; a `&` in a name broke matching; Excel dates arrived as serial numbers; a new client with no mapping entry got the wrong file prefix.
|
||||
**Look for:** split / separator logic, name matching, date parsing, mapping or config files ops must maintain.
|
||||
**Doc:** input rules in section 3, each with one wrong and one right example. Point at the sample input file if the bot has one.
|
||||
|
||||
## F5. Marked done when nothing was done
|
||||
**Tebra:** a location was marked Success with 0 items when the bot couldn't confirm it was on the right page; a company was marked Success after a crash.
|
||||
**Look for:** where success / complete is set, and whether it checks a positive count or a confirmation first.
|
||||
**Doc:** if a guard exists, a section 7 row for the "left Pending" message. If not, a gap in `HANDOVER-DEV.md`.
|
||||
|
||||
## F6. The action happened but the bot couldn't confirm it
|
||||
**Tebra:** "Payment not confirmed after Save" - the save took longer than the wait, so the row showed Error while the payment really had posted. Re-running risked posting twice.
|
||||
**Look for:** waits after a commit action (save, submit, send), and what the bot writes when the confirmation times out.
|
||||
**Doc:** a section 7 row that tells ops, in bold, to **check in the target app before re-running**, and how to correct the record afterwards.
|
||||
|
||||
## F7. A business exception shown as success
|
||||
**Tebra:** "ERA Errors on posting" and "negative balance - not posted" rows showed green (Completed) although a person had to follow up.
|
||||
**Look for:** status mapping tables; any comment that means "not done" stored under a success status.
|
||||
**Doc:** mark these "not done, needs follow-up" in the section 5 status table, give each a section 7 row, and add the mapping to the gaps in `HANDOVER-DEV.md`.
|
||||
|
||||
## F8. Endless re-runs, or killed by the watchdog
|
||||
**Tebra:** practices with no items re-ran the same company forever; already-processed rows were re-walked slowly after a restart until the watchdog killed the run at exactly 300 s, again and again.
|
||||
**Look for:** auto-rerun loops and their limits, watchdog timeouts, "0 items" handling, heartbeats.
|
||||
**Doc:** every limit in section 4, and in section 7 the signs of a loop ops should report ("the same company restarts more than N times").
|
||||
|
||||
## F9. Stopping the bot the wrong way
|
||||
**Tebra:** closing the app window didn't stop the bot, which kept driving the target app; closing the target app doesn't stop it either.
|
||||
**Look for:** how the child process ends (process-tree kill, parent-death watch), and any Stop button.
|
||||
**Doc:** the one right way to stop it, in section 10.
|
||||
|
||||
## F10. One stuck item blocks the queue
|
||||
**Tebra:** one Error row kept a whole batch Pending for weeks; a run that died in its first seconds locked the upload all day. Ops didn't know which row blocked it, or that yesterday's Pending batch never blocks today's upload.
|
||||
**Look for:** completion gates (what must be true for a batch / company to complete), locks on new uploads, resume logic.
|
||||
**Doc:** in section 7: what blocks what, how to find the blocking item (section 6), and how to release it (edit, discard, clear).
|
||||
|
||||
## F11. The cause is hidden from ops
|
||||
**Tebra:** the real cause was only in a database column the Report tab didn't show, or in the raw log; the friendly on-screen log hid errors; some app messages went to the screen only, never to a file.
|
||||
**Look for:** columns written but never displayed, log filters, messages printed only to the UI.
|
||||
**Doc:** sections 2 and 6 point only at places ops can open (question 2). Every hidden cause becomes a gap in `HANDOVER-DEV.md`.
|
||||
|
||||
## F12. The update didn't arrive, or an old build undid a new one
|
||||
**Tebra:** the launcher failed silently on a self-signed certificate, so users stayed on an old version; the server reported a deploy as done without swapping the container; a stale zip was shipped; each start re-deployed database procedures, so a machine on an old build overwrote newer ones.
|
||||
**Look for:** update / launcher code, version display, anything the app writes to shared resources on start.
|
||||
**Doc:** section 3 (check the version before a run) and section 11. Add "every machine must run the same version" when shared resources are rewritten on start.
|
||||
@@ -0,0 +1,171 @@
|
||||
# Worked example: Tebra Auto Post (v2.5.3), scrubbed
|
||||
|
||||
What the two files look like for a real bot. It is shortened: the real guide lists every status and every message. Client names, IDs, amounts, credentials and server addresses are removed, and the channel name is an example. **Copy the depth and the plain wording, not the content.**
|
||||
|
||||
---
|
||||
|
||||
# File 1: `HANDOVER.md`
|
||||
|
||||
# Tebra Auto Post: ops guide
|
||||
|
||||
Version 2.5.3 · Questions or problems: #rpa-support Teams channel (see section 9)
|
||||
|
||||
## 1. What this bot does
|
||||
|
||||
Posts insurance ERA payments into the Tebra desktop app, company by company and practice by practice, from the input Excel. At the end it turns each downloaded ERA into a PDF with EasyPrint.
|
||||
|
||||
## 2. Where is what
|
||||
|
||||
| Where | What you see there | Open it when |
|
||||
|---|---|---|
|
||||
| **Run tab** | Upload box, sheet preview, **Trigger automation** button, live log, 7 checkpoint boxes | To start a run, and to watch it |
|
||||
| **Dashboard** | Every batch with its status (Pending / Completed / Cleared). Click a batch to see each company and practice | After a run, to see if it finished |
|
||||
| **Report tab** | One row per ERA: File Status (colour), Comments, Check #, Insurance. Search by Batch ID. Exports to Excel | To see which ERA failed and why |
|
||||
| `data/files/Need_attention/` | ERAs whose PDF could not be made | When PDF Converted = No |
|
||||
| `data/files/Xcel/ERA_Summary_<time>.xlsx` | Per-file PDF result: Status, Failure Reason | To see why a PDF failed |
|
||||
|
||||
## 3. How to run
|
||||
|
||||
**Before you start**
|
||||
- [ ] EasyPrint shortcut is on the Desktop, the Public Desktop or the Start Menu.
|
||||
- [ ] Input Excel has the sheets Login, Company, Location, Settings. Download the sample from the Run tab if unsure.
|
||||
- [ ] **One practice per row.** Wrong: `North Clinic, South Clinic` in one cell (the bot splits it and skips both). Right: each on its own row.
|
||||
- [ ] Practice names spelled exactly as in Tebra, including `&`.
|
||||
- [ ] A new practice has a Client ID. Ask us to add it before the first run.
|
||||
- [ ] The title bar shows v2.5.3.
|
||||
|
||||
**Steps**
|
||||
1. Open **Ecare Tebra Automation Tool** from the Desktop.
|
||||
2. Run tab → drop the input Excel on the upload box.
|
||||
3. Check the preview: Login, Company and Location sheets all have rows.
|
||||
4. Click **Trigger automation**.
|
||||
5. Leave the machine alone until the run ends.
|
||||
|
||||
**What a normal run looks like:** the checkpoint boxes turn green one by one. The live log shows each company, practice and ERA. Tebra opens and closes by itself for every company.
|
||||
|
||||
## 4. How long to wait
|
||||
|
||||
| Step | Normal time | The bot waits at most | After that the bot | What you do |
|
||||
|---|---|---|---|---|
|
||||
| Any checkpoint box | — | 5 min (10 min for the ERA list) with no progress | Marks the box red **stuck**, closes Tebra, restarts. Up to 3 times | Nothing. Wait for the 3 restarts |
|
||||
| Open one ERA | not measured | 90 s, 3 tries, then 3 Tebra restarts | Writes the row as Error, moves to the next ERA | Nothing during the run |
|
||||
| Open the payment screen | not measured | 120 s, 4 tries, then 3 Tebra restarts | Pauses the run | See E07 |
|
||||
| Save one payment | about 12 s (slowest seen 27 s) | 45 s + 30 s + 30 s | Checks the ERA list. If the ERA is gone, counts it as posted. If not, Error | See E05 |
|
||||
| One company | depends on ERAs | 3 attempts | Leaves the company Pending | See E08 |
|
||||
| PDF step | not measured | 60 min | Puts the file in `Need_attention/` | See E09 |
|
||||
|
||||
**When do you step in?** Only when the run has ended, or the log says "Stuck - automatic restarts exhausted. Click Resume.". Restarts before that are normal.
|
||||
|
||||
## 5. After the run
|
||||
|
||||
| Ending | Meaning | What you do |
|
||||
|---|---|---|
|
||||
| Batch **Completed** on the Dashboard | Every practice finished | Check the Report tab for amber/grey rows that need follow-up |
|
||||
| Batch **Pending** | At least one practice is not finished | Section 6, then E08 |
|
||||
| "Stuck - automatic restarts exhausted. Click Resume." | The bot gave up after 3 restarts | Click **Resume** once. If it stops again, tell us |
|
||||
|
||||
**The report:** Report tab → search the Batch ID → read File Status and Comments. Export it to Excel from the same tab.
|
||||
|
||||
| Status - Comments | Colour | Meaning | What you do |
|
||||
|---|---|---|---|
|
||||
| Completed - "Posted successfully" | green | Posted and saved | nothing |
|
||||
| Completed - "ERA Errors on posting" | green | **Not posted.** Tebra rejected it | Review it in Tebra by hand |
|
||||
| Completed - "negative balance account … not posted" | green | **Not posted on purpose** | Follow the negative-balance process |
|
||||
| Completed - "Payment method '…' - not posted" | green | Not ACH, skipped | nothing |
|
||||
| Deferred | grey | Check date after the cutoff or in the future | nothing, a later run picks it up |
|
||||
| Error | red | Failed after all retries | Section 7 |
|
||||
|
||||
**Read the Comments column on every green row.** Three different results all show green.
|
||||
|
||||
## 6. How to see an exception
|
||||
|
||||
1. Report tab → search the Batch ID → sort by File Status → look at the red **Error** rows.
|
||||
2. Read the **Comments** column.
|
||||
3. Find that message in section 7.
|
||||
4. If no row is red but the batch is Pending, open the batch on the Dashboard and find the practice that is still Pending.
|
||||
|
||||
## 7. Exception list
|
||||
|
||||
| ID | Message you see | Where | What it means | What you do | Bot retries / call us when |
|
||||
|---|---|---|---|---|---|
|
||||
| E01 | "[login] FAILED for company …" | Live log; company Pending on the Dashboard | Tebra's sign-in window or fields never appeared | Check the username and password in the Login sheet, then Resume | Bot tries the company 3 times. Call us if Resume fails too |
|
||||
| E02 | "Wrong practice opened … leaving Pending" | Live log; practice Pending | The practice Tebra opened has a different name from the input | Fix the spelling in the input to match Tebra exactly (`&`, commas). Resume | Call us if the spelling is already exact |
|
||||
| E03 | "Clearinghouse Reports not found after retries" | Live log; practice Pending | Tebra's menu didn't show up, even after restarts | Resume once | Call us if it happens again |
|
||||
| E04 | "Could not open the ERA to view it" | Report tab, Comments, red | That ERA wouldn't open after 3 tries and 3 restarts | Resume. The bot continues at that ERA | Call us if the same ERA fails again |
|
||||
| E05 | "Payment not confirmed after Save" | Report tab, Comments, red | The bot clicked Save but never saw "saved". **It may have posted** | 1. **Check the payment in Tebra before anything else.** 2. If it posted, edit the row in the Report tab to Completed. 3. Only if it did not post, Resume. **Re-running without checking can post it twice** | Call us if it is not posted and fails again |
|
||||
| E06 | "Save button element not found" | Report tab, Comments, red | The payment screen had no Save button | Nothing. Tell us | Always call us |
|
||||
| E07 | "… still failing after 3 Tebra restarts" | Live log; run paused | The payment screen won't open | Click Resume once | Call us if it pauses again |
|
||||
| E08 | Batch stays **Pending** | Dashboard | One red or unfinished row keeps its practice open | Find the row (section 6). Fix or edit it, or request a Clear (an admin approves it). Yesterday's Pending batch does **not** block today's upload | Call us if you can't find the row |
|
||||
| E09 | File in `Need_attention/` | `ERA_Summary_<time>.xlsx`, Failure Reason | EasyPrint couldn't make the PDF | Nothing. The next run tries again | Call us if it is still there after 2 runs |
|
||||
|
||||
## 8. How you will know
|
||||
|
||||
There is **no email or alert**. The bot only shows results on screen. Check the Dashboard after every run: a batch that is still Pending needs you.
|
||||
|
||||
## 9. How to tell us
|
||||
|
||||
- **Where:** #rpa-support Teams channel. Expect an answer the same working day.
|
||||
- **Send:** Batch ID, time of the problem, E-number, a screenshot of the Run tab and of Tebra, the Report row.
|
||||
- **Never send:** the Login sheet, passwords, the settings file, or patient names in chat.
|
||||
|
||||
```
|
||||
Bot: Tebra Auto Post v2.5.3
|
||||
Batch ID:
|
||||
Time:
|
||||
E-number and message:
|
||||
What I already did:
|
||||
Screenshot: attached
|
||||
```
|
||||
|
||||
## 10. Don'ts
|
||||
|
||||
- **Don't use the mouse or keyboard while it runs.** Windows blocks the bot from taking focus, and its clicks land in the wrong window.
|
||||
- **Don't keep SQL Server Management Studio, or any window with "Tebra" in its title, open.** The bot can grab it instead of Tebra.
|
||||
- **Don't close Tebra to stop the bot.** The bot keeps going.
|
||||
- **To stop the bot:** close the **Ecare Tebra Automation Tool** window.
|
||||
|
||||
## 11. Issues seen before
|
||||
|
||||
| When / version | What you saw | What to do now |
|
||||
|---|---|---|
|
||||
| v2.5.1 | Red "Payment not confirmed" rows that had really posted | Partly fixed. Always check in Tebra first (E05) |
|
||||
| v2.5.0-2.5.3 | Batches Pending for weeks | Request a Clear (E08) |
|
||||
| v2.5.1 | Stayed on 2.5.0 after an update | Check the title bar version after every update. Tell us if it didn't change |
|
||||
| v2.5.2 | Some practices skipped on every run | One practice per row, no commas |
|
||||
| v1.0.x | Bot drove the database tool, then closed Tebra | Close other "Tebra" windows (section 10) |
|
||||
|
||||
---
|
||||
|
||||
# File 2: `HANDOVER-DEV.md`
|
||||
|
||||
## Failure-class check (excerpt)
|
||||
|
||||
- F1 covered in HANDOVER.md section 3 (EasyPrint shortcut); gap 6 (ODBC driver not enforced)
|
||||
- F2 covered in section 10
|
||||
- F4 covered in section 3 (one practice per row); gap 5 (`&` in names)
|
||||
- F6 covered in E05
|
||||
- F7 covered in section 5 (three green results); gap 1
|
||||
- F9 covered in section 10
|
||||
- F10 covered in E08
|
||||
- F11 gap 2, gap 3
|
||||
- F12 covered in section 11; gap 4
|
||||
|
||||
## Gaps to fix before handover (excerpt)
|
||||
|
||||
| # | Gap | Why it hurts ops | Where |
|
||||
|---|---|---|---|
|
||||
| 1 | "ERA Errors" and "negative balance" rows are stored as Completed (green) | Ops thinks they are done | `src/automation/era_log.py` status map |
|
||||
| 2 | The developer cause (TechComments) is in the DB only, not on the Report tab | Ops must ask dev for every red row | `src/db/report.py` |
|
||||
| 3 | The app's own watchdog messages go to the screen only | Lost after the run | `src/ui/main_window.py` `_log()` |
|
||||
| 4 | `ERA_Summary_*.xlsx` is named by time only | Can't be tied to a batch | `src/automation/remittance_pdf.py` |
|
||||
| 5 | `&` in a practice name breaks the title match (fixed in the TVL fork only) | Practice abandoned after 13 tries | `src/automation/orchestrator.py` practice check |
|
||||
| 6 | No check for ODBC Driver 17/18 at start | Cryptic "HYC00" error mid-run | `src/db/database.py` |
|
||||
|
||||
## Incidents (excerpt)
|
||||
|
||||
| When / version | What ops saw | Cause | Fix | Ref |
|
||||
|---|---|---|---|---|
|
||||
| v2.5.1 | "Payment not confirmed" rows that had posted | Save slower than the 20 s wait | 45/30/30 s + grid re-check | bug-206, bug-234 |
|
||||
| v2.5.1 | Users on 2.5.0 for a month | Server marked the deploy done but kept the old container | Stop + Start on the server | bug-243 |
|
||||
| v2.5.2 | 3 practices skipped every run | Split on commas | Split on newline/semicolon only | bug-233 |
|
||||
| v1.0.x | Launcher never updated | Self-signed certificate | Retry without verification | bug-080 |
|
||||
Reference in new issue
Block a user