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

rpa-bot-handoff: one short Handover SOP (max 4 pages) instead of the 11-section guide

Browse Source 
The first real handover (MEK Charge Reconciliation) came out at 9 pages.
Ops want it short: which URL to open and what to click, what shows where
after the click, what to do when an exception comes, and how to email us.

- Output is "<Project Name> Handover SOP" (HANDOVER-SOP.md + .docx) with
  5 sections: how to run, what you see while it runs, result, when
  something goes wrong, email us. HANDOVER-DEV.md is dropped; dev-team
  findings go in the chat.
- At most ~1,400 words; to_docx.py prints the word count and flags overflow,
  and renders *italic* for the variable parts of messages.
- Every quoted message, label and URL is checked against the code. The SOP
  must say what clicking Run again does to the data.
- One scan subagent; failure classes stay as a scan checklist.
- Tebra reference rewritten in the SOP format; test, README, glossary
  updated; ADR-0005 supersedes ADR-0004.

The handoff eval runner (tests/evals/run_handoff_eval.py) still grades an
older 13-section format and was already out of date; not touched here.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
VasanthandClaude Opus 5.5 committed 2026-10-28 16:57:48 +05:30
1 parent 71281bdf91
commit ff2f7fcd4a
13 files changed
+260 -377
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

CLAUDE.md
+1 -1
View File
@@ -1,6 +1,6 @@
# RPA SKILLS # RPA SKILLS
Shared Claude skills for RPA bots, all in `skills/`: `rpa-run-tab` (Tebra-style Run tab), `rpa-dashboard-no-ai`, `rpa-dashboard-ai` and `rpa-bot-handoff` (ops guide for handover). See `README.md` and `PLAN.md`. Shared Claude skills for RPA bots, all in `skills/`: `rpa-run-tab` (Tebra-style Run tab), `rpa-dashboard-no-ai`, `rpa-dashboard-ai` and `rpa-bot-handoff` (short Handover SOP for ops). See `README.md` and `PLAN.md`.
## Agent skills ## Agent skills
GLOSSARY.md
+3 -4
View File
@@ -37,12 +37,11 @@ It is hidden for bots that take no input file.
**Fake bot**: a bundled script that prints the Run tab protocol lines, used to verify the page. The skill never runs the real bot. **Fake bot**: a bundled script that prints the Run tab protocol lines, used to verify the page. The skill never runs the real bot.
**Ops guide**: the `HANDOVER.md` the `rpa-bot-handoff` skill writes in a bot's repo, for the operator who runs the bot and does not read code. 11 sections 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. See ADR-0004. _Avoid_: "handover doc" for the dev notes. **Handover SOP**: the `<Project Name> Handover SOP` the `rpa-bot-handoff` skill writes in a bot's repo (`HANDOVER-SOP.md` plus a Word copy), for the operator who runs the bot and does not read code. At most 4 pages, 5 sections in the operator's order: how to run, what you see while it runs, result, when something goes wrong, email us. See ADR-0005. _Avoid_: "ops guide" (the old 11-section format).
**Dev notes**: the `HANDOVER-DEV.md` written next to the ops guide, for developers only: the failure-class check, the gaps to fix before handover (with file:line) and the full incident list.
**Exception list**: section 7 of the ops guide: one numbered row (`E01`...) per message the operator can see, with where it appears, what it means, what to do, and whether to wait for the bot's retries or call the dev team. **Exception list**: the table in section 4 of the Handover SOP: one numbered row (`E01`...) per message the operator can see, with what it means and what to do, including when to email the dev team.
**Business exception**: the data says no (cutoff date passed, negative balance, already posted). **System exception**: the bot or the target app failed (window not found, timeout, crash). **Business exception**: the data says no (cutoff date passed, negative balance, already posted). **System exception**: the bot or the target app failed (window not found, timeout, crash).
**Failure class**: one of the 12 kinds of problem Tebra Auto Post hit after handover (`F1`-`F12` in `skills/rpa-bot-handoff/templates/failure-classes.md`). Every bot's dev notes account for all 12. **Failure class**: one of the 12 kinds of problem Tebra Auto Post hit after handover (`F1`-`F12` in `skills/rpa-bot-handoff/templates/failure-classes.md`). The SOP scan checks every bot against all 12 so no problem type is missed.
README.md
+1 -1
View File
@@ -8,7 +8,7 @@ Claude skills for RPA projects. Each folder in `skills/` is one skill: copy it i
| `rpa-dashboard-no-ai` | Builds a full dashboard (run panel, overview, report, optional checkpoints, admin and login) for a bot with no AI. Desktop or web. | | `rpa-dashboard-no-ai` | Builds a full dashboard (run panel, overview, report, optional checkpoints, admin and login) for a bot with no AI. Desktop or web. |
| `rpa-dashboard-ai` | The same dashboard, plus confidence bands, review-and-approve and a cost/ROI page, for a bot that uses an LLM or OCR. Install it together with `rpa-dashboard-no-ai`. | | `rpa-dashboard-ai` | The same dashboard, plus confidence bands, review-and-approve and a cost/ROI page, for a bot that uses an LLM or OCR. Install it together with `rpa-dashboard-no-ai`. |
| `sql-review` | Reviews SQL code (SQL Server + pyodbc) against 10 rules through a subagent and writes every issue with a before/after fix plan to `query_tracker.md`. Read-only. | | `sql-review` | Reviews SQL code (SQL Server + pyodbc) against 10 rules through a subagent and writes every issue with a before/after fix plan to `query_tracker.md`. Read-only. |
| `rpa-bot-handoff` | Writes the ops guide `HANDOVER.md` for a bot being handed over: which tab shows what, how to run, how long to wait, where the report is, how to see an exception, how to tell the dev team. Also writes `HANDOVER-DEV.md` with a check against 12 failure classes from Tebra Auto Post. | | `rpa-bot-handoff` | Writes a short `<Project Name> Handover SOP` (at most 4 pages, Markdown and Word) for a bot being handed over: how to run it (URL, what to click), what shows where, where the result is, how a problem shows and what to do, and how to email the dev team. |
| `pr` | Writes the PR body (Summary, Evidence, Merge Danger) and raises the PR to `main` with the `tea` CLI, with Murugeswaran as reviewer. Runs only on `/pr`; asks before creating a branch and before raising the PR. | | `pr` | Writes the PR body (Summary, Evidence, Merge Danger) and raises the PR to `main` with the `tea` CLI, with Murugeswaran as reviewer. Runs only on `/pr`; asks before creating a branch and before raising the PR. |
Run all tests: `uv run --with pytest --with playwright pytest tests` Run all tests: `uv run --with pytest --with playwright pytest tests`
docs/adr/0004-handover-is-an-ops-guide.md
+2
View File
@@ -1,5 +1,7 @@
# The handover is an ops guide in the operator's order, with dev notes kept apart # The handover is an ops guide in the operator's order, with dev notes kept apart
Superseded by ADR-0005.
`rpa-bot-handoff` writes two files: `rpa-bot-handoff` writes two files:
- `HANDOVER.md` is for the operator who runs the bot and does not read code. Its 11 sections follow the operator's own questions, in the order they ask them: where is what, how do I run it, how long do I wait, how do I read the result and the report, how do I see an exception, how will I know, how do I tell the dev team, what must I not do, what happened before. - `HANDOVER.md` is for the operator who runs the bot and does not read code. Its 11 sections follow the operator's own questions, in the order they ask them: where is what, how do I run it, how long do I wait, how do I read the result and the report, how do I see an exception, how will I know, how do I tell the dev team, what must I not do, what happened before.
- `HANDOVER-DEV.md` is for developers. It holds the failure-class check and the gaps to fix before handover, with file:line. - `HANDOVER-DEV.md` is for developers. It holds the failure-class check and the gaps to fix before handover, with file:line.
docs/adr/0005-handover-is-a-short-sop.md
+11
View File
@@ -0,0 +1,11 @@
# The handover is one short SOP, at most 4 pages
Supersedes ADR-0004.
`rpa-bot-handoff` now writes one document: `<Project Name> Handover SOP` (`HANDOVER-SOP.md` and a Word copy), at most 4 pages (about 1,400 words). It has 5 sections in the operator's order: how to run (URL, what to click), what you see while it runs, result, when something goes wrong, email us. The dev notes file is gone; problems the scan finds for the dev team are listed in the chat.
**Why:** the first real handover with ADR-0004's format (MEK Charge Reconciliation, Oct 2026) came out at 9 pages: 11 sections, 19 exception rows, plus a separate dev file. The user said ops need it short: first which URL to open and what to click, then what shows where after the click, then what to do when an exception comes and how to email the dev team, and nothing else. A long guide is not read, so its accuracy doesn't help.
**Accuracy instead of length:** every quoted message, label and URL is checked against the code before handover, and messages the code builds from parts show those parts in italics. The SOP must say what clicking Run again does to the data (fresh run on current data, previous results deleted or kept).
**Kept from ADR-0004:** the operator's words only, every wait is a number from the code, misleading statuses are called out where they show, the bot is never run, and the 12 failure classes are still checked during the scan so no problem type is missed.
skills/rpa-bot-handoff/README.md
+17 -26
View File
@@ -1,41 +1,32 @@
# rpa-bot-handoff # rpa-bot-handoff
A Claude skill that writes the **ops guide** for an RPA bot that is being handed over to an ops team. A Claude skill that writes a short **Handover SOP** for an RPA bot that is being handed over to an ops team.
## What you get ## What you get
**`HANDOVER.md`**: the ops guide, in plain words, for operators who don't read code: **`<Project Name> Handover SOP.docx`** (and `HANDOVER-SOP.md`): at most 4 pages, in plain words, for operators who don't read code:
1. What this bot does 1. How to run: the URL or shortcut, what to click, and what a new click does to the previous results
2. Where is what: which tab, screen, file or folder shows what 2. What you see while it runs: what shows where, a normal run, how long each step may take
3. How to run: checklist and steps with the real button names 3. Result: how a good run ends, where the report is, what each status means
4. How long to wait at each step, in seconds or minutes, and when to step in 4. When something goes wrong: how it shows, each message (E01, E02...) with what to do, the don'ts, how to stop it
5. After the run: what each ending means, where the report is 5. Email us: the address, when to email, and the email to copy
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.docx`**: the same ops guide as a Word document. This is what you give the ops team at the end. Problems the scan finds for the dev team are listed in the chat, not in the SOP.
**`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 ## Install
Copy this folder to `~/.claude/skills/rpa-bot-handoff/`. Copy this folder to `~/.claude/skills/rpa-bot-handoff/`.
## Use ## Use
In your bot project, ask Claude: *"write the ops guide for this bot"* or *"document this bot for handover"*. The skill: In your bot project, ask Claude: *"write the handover SOP for this bot"* or *"document this bot for handover"*. The skill:
1. Scans the code and history with subagents. It never runs the bot. 1. Scans the code with a subagent. 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. 2. Asks up to two things: the email group ops writes to, and where ops runs the bot.
3. Writes both files and checks them. 3. Writes the SOP, checks every quoted message and label against the code, and keeps it under 1,400 words.
4. Turns the ops guide into `HANDOVER.docx` and gives you that document to hand to ops. 4. Turns it into the Word file you give to ops.
## Files ## Files
| File | What it is | | File | What it is |
|---|---| |---|---|
| `SKILL.md` | Steps Claude follows | | `SKILL.md` | Steps Claude follows |
| `templates/HANDOVER.md` | The ops guide skeleton | | `templates/HANDOVER-SOP.md` | The SOP skeleton |
| `templates/HANDOVER-DEV.md` | The dev notes skeleton | | `templates/failure-classes.md` | 12 failure classes from Tebra's first months with ops, used as a scan checklist |
| `templates/failure-classes.md` | 12 failure classes from Tebra's first months with ops | | `templates/reference/tebra-auto-post.md` | The SOP filled in for Tebra, scrubbed |
| `templates/reference/tebra-auto-post.md` | Both files filled in for Tebra, scrubbed | | `templates/to_docx.py` | Turns the SOP into Word and prints the word count (`--selfcheck` tests it) |
| `templates/to_docx.py` | Turns `HANDOVER.md` into `HANDOVER.docx` (`--selfcheck` tests it) |
skills/rpa-bot-handoff/SKILL.md
+50 -73
View File
@@ -1,97 +1,74 @@
--- ---
name: rpa-bot-handoff 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. description: Writes a short Handover SOP for an RPA bot that is being handed over to an ops/support team - "<Project Name> Handover SOP", at most 4 pages, as Markdown and Word. Scans the bot's code with a subagent (never runs it) and writes, in the operator's order - how to run it (which URL or shortcut, what to click), what shows where once it runs, where the result is and what it means, how a problem shows and what to do, and how to email the dev team about it. Every label, message and wait is copied from the code. Use when the user asks to "hand over a bot", "document a bot for ops", "write a handover doc", "handover SOP", "ops guide", "runbook", "support doc", "operator guide" or "how ops should handle bot errors" for an RPA or automation project.
--- ---
# RPA bot handoff # RPA bot handoff
Write two files in the bot's repo: Write one document in the bot's repo: **`<Project Name> Handover SOP`**, as `HANDOVER-SOP.md` and `<Project Name> Handover SOP.docx`. The docx is what ops gets.
- **`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. The reader is an **operator who does not read code**. The SOP answers only what they ask, in this order:
1. How do I run it? Which URL or shortcut, what do I click.
2. What shows where once it runs?
3. Where is the result, and what does it mean?
4. Something went wrong: how does it show, and what do I do?
5. How do I email the dev team about it?
| File | What it is | | File | What it is |
|---|---| |---|---|
| `templates/HANDOVER.md` | The ops guide skeleton: 11 sections. Keep their order. | | `templates/HANDOVER-SOP.md` | The SOP skeleton: 5 sections. Keep their order. |
| `templates/HANDOVER-DEV.md` | The dev notes skeleton. | | `templates/failure-classes.md` | 12 failure classes from Tebra Auto Post. A scan checklist so no problem type is missed. |
| `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 for Tebra, scrubbed. Copy its length and wording, not its content. |
| `templates/reference/tebra-auto-post.md` | A filled example of both files for Tebra, scrubbed. Copy its depth and wording, not its content. | | `templates/to_docx.py` | Turns the finished SOP into the Word file and prints the word count. Needs `python-docx`. |
| `templates/to_docx.py` | Turns the finished `HANDOVER.md` into `HANDOVER.docx`, the document handed to ops. Needs `python-docx`. |
Rules: ## 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 and `HANDOVER.docx`, the Word copy of the ops guide that is handed to ops at the end.
## 1. Scan (subagents are required) - **Short.** At most 4 pages, which is about 1,400 words including tables. A small bot fits in 2. Never pad: a section with nothing to say gets one line.
- **Accurate.** Copy every URL, button label, lane or column name, status and message **exactly** from the code or the screen. Never paraphrase a message the operator will search for. When the code builds a message from parts, write it with the variable parts in italics: "Couldn't download *Location* from *Portal*".
- **Every wait is a number** from the code, in seconds or minutes. Write "not measured" for a normal duration the logs don't show.
- **Write what the code does.** If the screen misleads (green or "Finished" while something failed), say so in one line where it shows.
- **The operator's words only.** No file:line, function names, SQL, env var names or log internals in the SOP.
- **Never run the bot.** Read code, config, logs and history only.
- **Never copy** patient data, customer or client names, credentials, internal IPs, keys or `.env` values into the SOP.
- **Re-runs:** always say what clicking Run (or starting the bot) again does to the data: does it start from the current data, and does it delete or overwrite the previous results.
**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. ## 1. Scan (one subagent, required)
**Subagent A: what the operator sees and does.** Ask it to report: Start one read-only subagent. Tell it: never run the bot, no PHI, client names, credentials or IPs in the report, file:line refs, under 1200 words. Ask it for:
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. 1. **Start:** the URL, shortcut or command ops uses, the sign-in screen, and the exact button that starts a run. What clicking it again does to the previous data and results.
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). 2. **Screen while running:** every area, lane, list or column that changes during a run, its exact label and the texts it shows, in order.
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. 3. **Waits:** every timeout and retry count, in seconds, with its step. What the bot does when it runs out.
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. 4. **Result:** how a run ends on screen (texts, colours), where the result or report is, its name, sheets or columns, and every per-item status with its meaning.
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. 5. **Problems:** every message the operator can see (exact text, where it shows, colour), what triggers it, whether the bot retries, what happens next. Include sign-in and connection messages.
6. **Alerts:** whether the bot sends any email, popup, sound or notification when something fails. If not, say so. 6. **Alerts and stopping:** any email, popup or sound on failure (or none), whether there is a Stop button, and anything ops must not do while it runs.
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 it runs, read `templates/failure-classes.md` and `templates/reference/tebra-auto-post.md`. Check the subagent's report against the 12 classes; ask it a follow-up for any class it skipped.
While they run, read `templates/failure-classes.md` and `templates/reference/tebra-auto-post.md`. ## 2. Ask once (one message, at most 2 questions)
## 2. Ask once (one message, at most 3 questions) 1. **Email:** which email group ops writes to (the address, never a personal phone number), and how fast they get an answer.
2. **Where ops runs it:** the URL or machine, when the code allows more than one.
Send a 5-line summary of what the scan found, then ask: Skip a question the user already answered. Default the rest: title from the project name, today's date, version from the project's version string.
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-SOP.md`
## 3. Write `HANDOVER.md` (the ops guide) Copy `templates/HANDOVER-SOP.md` to the bot's repo root and fill every `{{PLACEHOLDER}}`:
Copy `templates/HANDOVER.md` to the bot's repo root and fill every `{{PLACEHOLDER}}`. Section notes: 1. **How to run:** the URL or shortcut, then numbered steps with the real labels. Then 2 to 4 "before you click" bullets, including what a new click does to the previous results.
2. **What you see while it runs:** a table, one row per area of the screen, in screen order: where, what it shows. Then the normal sequence in 3 to 5 numbered lines. Then the waits table: step, the bot waits at most, then. End with when the operator steps in.
3. **Result:** how a good run ends; how a run that needs a look ends (call out misleading greens). Then where the result is, and a small table of the per-item statuses: status, meaning, what you do.
4. **When something goes wrong:** where problems show and how (colour, list, column). Then one table row per message, numbered `E01`, `E02`...: message (exact), what it means, what you do. Put "check X **before** re-running" in bold. Say "email us" in the row when the operator can't fix it. Then the don'ts in at most 4 bullets, and the one right way to stop the bot.
5. **Email us:** the address and response time, when to email, the subject line and the email body to copy, what to attach, and what never to send (passwords, patient or client data, the result files when they hold patient data).
1. **What this bot does:** at most 2 lines. ## 4. Verify
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) 1. Every message and status in the subagent's report is in section 3 or 4.
2. Search the code for each quoted message, label and URL. Each must exist exactly, or be built by the code from the parts shown in italics.
3. No file:line, function names, env var names, client names, PHI, credentials or IPs.
4. Run `python <skill>/templates/to_docx.py HANDOVER-SOP.md -o "<Project Name> Handover SOP.docx"`. If it reports more than 1,400 words, cut: merge rows, drop explanations, never drop a message.
5. Open the docx with python-docx: 5 numbered section headings, no `**` or `|---` left.
Copy `templates/HANDOVER-DEV.md` and fill it: ## 5. Hand over
- **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 Give the user the path to `<Project Name> Handover SOP.docx`: "Give this to the ops team." Then, in the chat only, list in at most 5 lines the problems the scan found that the dev team should fix (misleading statuses, silent failures, no alerts). They are not part of the SOP.
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.
## 6. Hand over the document
The skill always ends with one document the user can give to ops.
1. Run `python <skill>/templates/to_docx.py HANDOVER.md`. It writes `HANDOVER.docx` next to it. If `python-docx` is missing, run `pip install python-docx` first. If that is not allowed, say so and hand over `HANDOVER.md` instead.
2. Open the `.docx` with python-docx and check that it has 11 numbered section headings and that no `**` or `|---` is left in its text.
3. Give the user the path to `HANDOVER.docx` as the deliverable: "Give this to the ops team." `HANDOVER-DEV.md` stays in the repo for developers and is not handed to ops.
4. Report: sections filled, number of exceptions listed, failure classes covered vs not applicable, and the gaps for the dev team.
skills/rpa-bot-handoff/templates/HANDOVER-DEV.md
-19
View File
@@ -1,19 +0,0 @@
# {{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}} |
skills/rpa-bot-handoff/templates/HANDOVER-SOP.md
+73
View File
@@ -0,0 +1,73 @@
# {{PROJECT_NAME}} Handover SOP
Version {{VERSION}} · {{DATE}} · Problems: email {{EMAIL_GROUP}} (section 5)
{{ONE_LINE: what the bot does, from which app or portal, and what it produces}}
## 1. How to run
1. {{e.g. Open https://... in Chrome / Open "<app>" from the Desktop.}}
2. {{e.g. Sign in with the team password.}}
3. {{e.g. Click "Run".}}
4. {{e.g. Wait until the status says "Finished" or "Stopped" (section 2).}}
**Before you click {{RUN_LABEL}}:**
- {{WHAT A NEW CLICK DOES: e.g. "Every click starts a fresh run on today's data. It deletes the previous run's reports first, so download them before you click."}}
- {{e.g. "Only one run at a time. A greyed-out button means a run is going."}}
## 2. What you see while it runs
| Where on the screen | What it shows |
|---|---|
| {{AREA, exact label}} | {{TEXTS IT SHOWS, in order}} |
**A normal run:**
1. {{e.g. Both lanes say "Signing in…".}}
2. {{e.g. Each lane fills: "3 of 10 locations".}}
3. {{e.g. Status "Finished", last line "Finished. Your reports are ready to download below."}}
| Step | The bot waits at most | Then |
|---|---|---|
| {{STEP}} | {{e.g. 3 min}} | {{e.g. skips that location / stops / retries 3 times}} |
**Step in only when:** {{e.g. the run has ended, or nothing new has appeared for 10 minutes}}.
## 3. Result
- **Good run:** {{HOW IT ENDS ON SCREEN}}
- **Needs a look:** {{HOW IT ENDS, including any misleading green or "Finished"}}
**Where:** {{e.g. Reports box → Download. Excel: Summary sheet, Reconciliation sheet, Result column.}}
| Status | Meaning | What you do |
|---|---|---|
| {{STATUS}} | {{ONE LINE}} | {{ACTION or "nothing"}} |
## 4. When something goes wrong
**How it shows:** {{e.g. a red or orange dot in the activity list under the Run button; the lane turns red}}.
| ID | Message you see | What it means | What you do |
|---|---|---|---|
| E01 | {{EXACT MESSAGE}} | {{ONE LINE}} | {{STEPS. "Email us" when ops can't fix it}} |
**Don't:**
- {{DON'T + short reason}}
**To stop it:** {{THE ONE RIGHT WAY}}
## 5. Email us
Email **{{EMAIL_GROUP}}** when section 4 says "email us", or when the same error comes back after one re-run. Answer: {{RESPONSE_TIME}}.
```
Subject: {{PROJECT_NAME}} - E<number> - <date>
Run started: <time from the screen>
Error: E<number> - <the message, copied>
Where: <location / item>
What I did: <e.g. ran it again once>
Attached: screenshot of the screen
```
**Never send:** passwords, {{SENSITIVE: e.g. the Excel reports (they hold patient names)}}.
skills/rpa-bot-handoff/templates/HANDOVER.md
-92
View File
@@ -1,92 +0,0 @@
# {{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"}} |
skills/rpa-bot-handoff/templates/reference/tebra-auto-post.md
+71 -144
View File
@@ -1,171 +1,98 @@
# Worked example: Tebra Auto Post (v2.5.3), scrubbed # 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.** What the SOP looks like for a real bot: about 2.5 pages. Client names, IDs, amounts, credentials and server addresses are removed, and the email address is an example. **Copy the length and the plain wording, not the content.**
--- ---
# File 1: `HANDOVER.md` # Tebra Auto Post Handover SOP
# Tebra Auto Post: ops guide Version 2.5.3 · 28 Oct 2026 · Problems: email rpa-support@example.com (section 5)
Version 2.5.3 · Questions or problems: #rpa-support Teams channel (see section 9) Posts insurance ERA payments into the Tebra desktop app, company by company and practice by practice, from the input Excel, then turns each ERA into a PDF.
## 1. What this bot does ## 1. How to run
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. 1. Open **Ecare Tebra Automation Tool** from the Desktop. Check the title bar shows v2.5.3.
2. **Run** tab → drop the input Excel on the upload box.
## 2. Where is what 3. Check the preview: the Login, Company and Location sheets all have rows.
| 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**. 4. Click **Trigger automation**.
5. Leave the machine alone until the run ends. 5. Leave the mouse and keyboard 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. **Before you click Trigger automation:**
- One practice per row. Wrong: `North Clinic, South Clinic` in one cell (both are skipped). Right: one per row, spelled exactly as in Tebra.
- Every click starts a new batch from the Excel you uploaded. ERAs already posted are not posted again.
- Close SQL Server Management Studio and any other window with "Tebra" in its title.
## 4. How long to wait ## 2. What you see while it runs
| Step | Normal time | The bot waits at most | After that the bot | What you do | | Where on the screen | What it shows |
|---|---|---|---|---| |---|---|
| 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 | | **Run** tab → checkpoint boxes | 7 boxes, grey → green as each step finishes; red **stuck** when a step makes no progress |
| 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 | | **Run** tab → live log | Each company, practice and ERA as it is posted |
| Open the payment screen | not measured | 120 s, 4 tries, then 3 Tebra restarts | Pauses the run | See E07 | | **Dashboard** | The batch: Pending while running, Completed when every practice is done |
| 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 | | **Report** tab | One row per ERA: File Status (colour) and Comments |
| 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. **A normal run:**
1. Tebra opens by itself and signs in to the first company.
2. The checkpoint boxes turn green one by one; the live log lists each ERA.
3. Tebra closes and reopens for the next company.
4. The Dashboard shows the batch as **Completed**.
## 5. After the run | Step | The bot waits at most | Then |
| 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 | | Any checkpoint box | 5 min with no progress (10 min for the ERA list) | Marks it red **stuck**, restarts Tebra, up to 3 times |
| Batch **Pending** | At least one practice is not finished | Section 6, then E08 | | Open one ERA | 90 s, 3 tries, then 3 Tebra restarts | Writes the row as Error, moves on |
| "Stuck - automatic restarts exhausted. Click Resume." | The bot gave up after 3 restarts | Click **Resume** once. If it stops again, tell us | | Save one payment | 45 s + 30 s + 30 s | Checks the ERA list; Error if still there (E03) |
| PDF of one ERA | 60 min | Moves the file to `Need_attention` |
**The report:** Report tab → search the Batch ID → read File Status and Comments. Export it to Excel from the same tab. **Step in only when:** the run has ended, or the log says "Stuck - automatic restarts exhausted. Click Resume.".
| Status - Comments | Colour | Meaning | What you do | ## 3. Result
- **Good run:** the batch is **Completed** on the Dashboard and the Report tab has no red rows.
- **Needs a look:** the batch stays **Pending**, or a row is red. **Three different results show green**: read the Comments of every green row.
**Where:** Report tab → search the Batch ID → File Status and Comments. Export with the Excel button.
| Status - Comments | Meaning | What you do |
|---|---|---|
| Completed - "Posted successfully" | Posted | Nothing |
| Completed - "ERA Errors on posting" | **Not posted.** Tebra rejected it | Review it in Tebra by hand |
| Completed - "negative balance account … not posted" | **Not posted on purpose** | Follow the negative-balance process |
| Deferred (grey) | Check date after the cutoff | Nothing; a later run picks it up |
| Error (red) | Failed after all retries | Section 4 |
## 4. When something goes wrong
**How it shows:** a red row on the Report tab (read Comments), a red **stuck** box on the Run tab, or a batch still **Pending** on the Dashboard.
| ID | Message you see | What it means | What you do |
|---|---|---|---| |---|---|---|---|
| Completed - "Posted successfully" | green | Posted and saved | nothing | | E01 | "[login] FAILED for company …" | Tebra's sign-in never appeared | Check the Login sheet, then click **Resume**. Email us if it fails again |
| Completed - "ERA Errors on posting" | green | **Not posted.** Tebra rejected it | Review it in Tebra by hand | | E02 | "Wrong practice opened … leaving Pending" | The practice name doesn't match Tebra | Fix the spelling in the Excel, click **Resume** |
| Completed - "negative balance account … not posted" | green | **Not posted on purpose** | Follow the negative-balance process | | E03 | "Payment not confirmed after Save" | The bot clicked Save but never saw "saved". **It may have posted** | **Check the payment in Tebra before re-running.** If posted, set the row to Completed. If not, click **Resume** |
| Completed - "Payment method '…' - not posted" | green | Not ACH, skipped | nothing | | E04 | "Save button element not found" | The payment screen had no Save button | Email us |
| Deferred | grey | Check date after the cutoff or in the future | nothing, a later run picks it up | | E05 | "Stuck - automatic restarts exhausted. Click Resume." | 3 restarts didn't help | Click **Resume** once. Email us if it stops again |
| Error | red | Failed after all retries | Section 7 | | E06 | Batch stays **Pending** | One red or unfinished row keeps its practice open | Find the red row (Report tab), fix or edit it. Email us if you can't find it |
**Read the Comments column on every green row.** Three different results all show green. **Don't:**
- Use the mouse or keyboard while it runs: its clicks land in the wrong window.
- Close Tebra to stop the bot: the bot keeps going.
## 6. How to see an exception **To stop it:** close the **Ecare Tebra Automation Tool** window.
1. Report tab → search the Batch ID → sort by File Status → look at the red **Error** rows. ## 5. Email us
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 Email **rpa-support@example.com** when section 4 says "email us", or when the same error comes back after one Resume. Answer: same working day.
| 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 Subject: Tebra Auto Post - E<number> - <date>
Batch ID:
Time: Batch ID: <from the Dashboard>
E-number and message: Error: E<number> - <the message, copied>
What I already did: Where: <company / practice / check number>
Screenshot: attached What I did: <e.g. clicked Resume once>
Attached: screenshot of the Run tab and of Tebra
``` ```
## 10. Don'ts **Never send:** the Login sheet, passwords, or patient names.
- **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 |
skills/rpa-bot-handoff/templates/to_docx.py
+27 -14
View File
@@ -1,11 +1,13 @@
"""Turn the ops guide (HANDOVER.md) into a Word document ops can open, print and pass around. """Turn the Handover SOP (HANDOVER-SOP.md) into a Word document ops can open, print and pass around.
python to_docx.py HANDOVER.md # writes HANDOVER.docx next to it python to_docx.py HANDOVER-SOP.md # writes HANDOVER-SOP.docx next to it
python to_docx.py HANDOVER.md -o guide.docx python to_docx.py HANDOVER-SOP.md -o "<Project Name> Handover SOP.docx"
python to_docx.py --selfcheck python to_docx.py --selfcheck
Prints the word count: the SOP must stay at or under MAX_WORDS (about 4 pages).
Handles what the template uses: # headings, paragraphs, - bullets, - [ ] checkboxes, 1. steps, Handles what the template uses: # headings, paragraphs, - bullets, - [ ] checkboxes, 1. steps,
| tables |, ``` blocks, **bold** and `code`. Needs python-docx (pip install python-docx). | tables |, ``` blocks, **bold**, *italic* and `code`. Needs python-docx (pip install python-docx).
""" """
import argparse import argparse
import re import re
@@ -16,13 +18,16 @@ from pathlib import Path
from docx import Document from docx import Document
from docx.shared import Pt from docx.shared import Pt
INLINE = re.compile(r"(\*\*[^*]+\*\*|`[^`]+`)") MAX_WORDS = 1400 # about 4 pages with tables
INLINE = re.compile(r"(\*\*[^*]+\*\*|\*[^*\s][^*]*\*|`[^`]+`)")
def add_runs(par, text): def add_runs(par, text):
for part in INLINE.split(text): for part in INLINE.split(text):
if part.startswith("**") and part.endswith("**"): if part.startswith("**") and part.endswith("**"):
par.add_run(part[2:-2]).bold = True par.add_run(part[2:-2]).bold = True
elif len(part) > 2 and part.startswith("*") and part.endswith("*"):
par.add_run(part[1:-1]).italic = True
elif part.startswith("`") and part.endswith("`"): elif part.startswith("`") and part.endswith("`"):
par.add_run(part[1:-1]).font.name = "Consolas" par.add_run(part[1:-1]).font.name = "Consolas"
elif part: elif part:
@@ -82,18 +87,24 @@ def convert(md_text, out_path):
return doc return doc
def words(md_text):
return len(re.findall(r"[A-Za-z0-9][\w'’.-]*", re.sub(r"^\|[\s:|-]+\|\s*$", "", md_text, flags=re.M)))
def selfcheck(): def selfcheck():
example = Path(__file__).parent / "reference" / "tebra-auto-post.md" example = Path(__file__).parent / "reference" / "tebra-auto-post.md"
guide = example.read_text(encoding="utf-8").split("# File 2:")[0].split("# File 1: `HANDOVER.md`")[1] sop = "# " + example.read_text(encoding="utf-8").split("\n---\n", 1)[1].split("\n# ", 1)[1]
out = Path(tempfile.mkdtemp()) / "HANDOVER.docx" out = Path(tempfile.mkdtemp()) / "HANDOVER-SOP.docx"
convert(guide, out) convert(sop, out)
doc = Document(out) doc = Document(out)
heads = [p.text for p in doc.paragraphs if p.style.name.startswith("Heading")] heads = [p.text for p in doc.paragraphs if p.style.name.startswith("Heading")]
assert [h.split(".")[0] for h in heads if h[:1].isdigit()] == [str(n) for n in range(1, 12)], heads assert doc.paragraphs[0].text.endswith("Handover SOP"), doc.paragraphs[0].text
assert len(doc.tables) >= 6, len(doc.tables) assert [h.split(".")[0] for h in heads if h[:1].isdigit()] == [str(n) for n in range(1, 6)], heads
assert doc.tables[0].cell(0, 0).text == "Where", doc.tables[0].cell(0, 0).text assert len(doc.tables) >= 4, len(doc.tables)
assert doc.tables[0].cell(0, 0).text == "Where on the screen", doc.tables[0].cell(0, 0).text
assert not any("**" in p.text or "|---" in p.text for p in doc.paragraphs) assert not any("**" in p.text or "|---" in p.text for p in doc.paragraphs)
print(f"selfcheck ok: {len(heads)} headings, {len(doc.tables)} tables -> {out}") assert words(sop) <= MAX_WORDS, words(sop)
print(f"selfcheck ok: {len(heads)} headings, {len(doc.tables)} tables, {words(sop)} words -> {out}")
if __name__ == "__main__": if __name__ == "__main__":
@@ -109,5 +120,7 @@ if __name__ == "__main__":
ap.error("give the HANDOVER.md path, or --selfcheck") ap.error("give the HANDOVER.md path, or --selfcheck")
src = Path(a.md) src = Path(a.md)
out = Path(a.out) if a.out else src.with_suffix(".docx") out = Path(a.out) if a.out else src.with_suffix(".docx")
convert(src.read_text(encoding="utf-8"), out) text = src.read_text(encoding="utf-8")
print(f"wrote {out}") convert(text, out)
n = words(text)
print(f"wrote {out} ({n} words{'' if n <= MAX_WORDS else f', OVER the {MAX_WORDS}-word limit: cut it'})")
tests/test_templates.py
+4 -3
View File
@@ -58,9 +58,10 @@ def test_handoff_lists_twelve_failure_classes():
assert len(re.findall(r"^## F\d+\.", classes, re.MULTILINE)) == 12 assert len(re.findall(r"^## F\d+\.", classes, re.MULTILINE)) == 12
def test_handoff_ops_guide_has_eleven_sections_in_order(): def test_handoff_sop_has_five_sections_in_order():
guide = (ROOT / "skills" / "rpa-bot-handoff" / "templates" / "HANDOVER.md").read_text(encoding="utf-8") sop = (ROOT / "skills" / "rpa-bot-handoff" / "templates" / "HANDOVER-SOP.md").read_text(encoding="utf-8")
assert [int(n) for n in re.findall(r"^## (\d+)\.", guide, re.MULTILINE)] == list(range(1, 12)) assert re.search(r"^# \{\{PROJECT_NAME\}\} Handover SOP$", sop, re.MULTILINE)
assert [int(n) for n in re.findall(r"^## (\d+)\.", sop, re.MULTILINE)] == list(range(1, 6))
def test_handoff_docx_selfcheck(): def test_handoff_docx_selfcheck():