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

skills/rpa-bot-handoff/SKILL.md
+50 -73
View File
@@ -1,97 +1,74 @@
---
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
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.
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.
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 |
|---|---|
| `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. |
| `templates/to_docx.py` | Turns the finished `HANDOVER.md` into `HANDOVER.docx`, the document handed to ops. Needs `python-docx`. |
| `templates/HANDOVER-SOP.md` | The SOP skeleton: 5 sections. Keep their order. |
| `templates/failure-classes.md` | 12 failure classes from Tebra Auto Post. A scan checklist so no problem type is missed. |
| `templates/reference/tebra-auto-post.md` | A filled example for Tebra, scrubbed. Copy its length 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`. |
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.
## Rules
## 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:
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.
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. **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. **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 and retry count, in seconds, with its step. What the bot does when it runs out.
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. **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 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.
**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:
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.
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.
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.
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. Verify
## 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:
- **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. Hand over
## 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.
## 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.
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.