chore(chat-plugin): sync robotcode skill from agent-plugins

Mirror plugins/robotcode from robotframework-agent-plugins (b94e5e4): the command-line debugger guide (references/debugging.md) and a Debug mode plus debugger section in SKILL.md, the reference-style refresh of the existing pages, guidance to debug a single failing test by selector (-t/-bl) rather than by file path, and the new 'fix a whole failing run' workflow.

Author: d-biehl

chat-plugins/.upstream.json

@@ -1,5 +1,5 @@
 {
   "source": "github.com/robotcodedev/robotframework-agent-plugins",
-  "sha": "e431937e1fbb4c038bf8fc4910ae910c046deb77",
-  "syncedAt": "2026-05-29T22:47:26+00:00"
+  "sha": "b94e5e4a0eabe1c8c7fe0f249467a8751dcb5b33",
+  "syncedAt": "2026-06-05T01:11:39+00:00"
 }

chat-plugins/robotcode/skills/robotcode/SKILL.md

@@ -1,6 +1,18 @@
 ---
 name: robotcode
-description: Robot Framework and RobotCode guidance for test automation projects — project structure, keywords, libraries, resources, variables, tags, suites, tests, profiles, configuration, execution, discovery, static analysis, result inspection, installation, CLI workflows, and editor tooling. Also covers the RobotCode REPL for interactive, step-by-step work — exploring a system under test or a keyword/library, and developing test cases and keywords one line at a time (use even when the user does not say "REPL"). Always use project-local `robotcode libdoc` first for library, resource, and keyword documentation — before Context7, web search, or generic knowledge — and fall back only when libdoc cannot answer. Inspect finished runs with `robotcode results` rather than loading large raw `output.xml` files.
+description: >-
+  Robot Framework and RobotCode guidance for test automation projects — project
+  structure, keywords, libraries, resources, variables, tags, suites, tests,
+  profiles, configuration, execution, discovery, static analysis, result
+  inspection, debugging, installation, CLI workflows, and editor tooling. Also
+  covers the RobotCode REPL for interactive, step-by-step work — exploring a
+  system under test or a keyword/library, and developing tests and keywords one
+  line at a time (use even when the user does not say "REPL") — and the
+  command-line debugger (`robotcode robot-debug`) for debugging Robot Framework
+  test files. Always use project-local `robotcode libdoc` first for library,
+  resource, and keyword documentation — before Context7, web search, or generic
+  knowledge — and fall back only when libdoc cannot answer. Inspect finished runs
+  with `robotcode results` rather than loading large raw `output.xml` files.
 license: Apache-2.0
 ---
 
@@ -14,10 +26,11 @@ RobotCode must run from the project's Python environment. Do not use isolated ru
 
 Decide what the user actually wants *before* reaching for a command — these intents have different entry points, and mixing them up is the most common mistake (especially writing a `.robot` test file when the user asked you to *do* something). Several can chain in one task (explore → author → run → inspect).
 
-- **Explore / do it for me** — *"go to … and check", "fetch …", "try this keyword", "does X work?", "why does this fail?", "so I can watch".* A one-off, interactive task — **not** a test. Start a REPL and drive it live; when the user wants to watch, open the browser **non-headless** and keep the session open. **Do not write a `.robot` file** — see [references/repl.md](references/repl.md). Offer to turn it into a test *afterwards*, only if the user then asks.
+- **Explore / do it for me** — *"go to … and check", "fetch …", "try this keyword", "does X work?", "so I can watch".* A one-off, interactive task — **not** a test. (For "why does *this test* fail?" use Debug or Inspect below, not this.) Start a REPL and drive it live; when the user wants to watch, open the browser **non-headless** and keep the session open. **Do not write a `.robot` file** — see [references/repl.md](references/repl.md). Offer to turn it into a test *afterwards*, only if the user then asks.
 - **Author tests or keywords** — *"write / create / add a test or suite".* Reuse existing keywords (`libdoc`) and conventions (`discover`), prototype uncertain steps in the REPL, write, then check with `analyze code` before running. See [references/authoring.md](references/authoring.md).
 - **Run tests** — *"run the tests", "execute the smoke suite".* `robotcode robot` (see *Running tests*), then summarize via `results`.
-- **Inspect a finished run** — *"what failed?", "did it pass?", "why did X fail?"* — `robotcode results` over the existing `output.xml`/`output.json`; no re-run needed (works on CI artifacts and a colleague's run too). See [references/results.md](references/results.md).
+- **Inspect a finished run** — *"what failed?", "did it pass?", "why did X fail?"* — `robotcode results` over the existing `output.xml`/`output.json`; no re-run needed (works on CI artifacts and a colleague's run too). Try this **first** for "why did X fail?". See [references/results.md](references/results.md).
+- **Debug a live run** — *"fix this test", "fix it", "why does this test fail?", "why won't this test run?", "step through it", "set a breakpoint at line X", "pause where it fails and show me the variables", "what is `${response}` at that point?"* — when a test fails, go to the failure in its **real context, fast**: read the error with `results`, then run the **actual** failing test under the debugger (`robotcode robot-debug`, selecting that one test by name — `-bl "<longname>"` from `results`, or `-t "<name>"`, **not** the whole file: a bare path runs every test in it and may pause on a different one) and pause at the failure (on by default) to inspect the **live** stack and variables. **Don't** detour into external tools (a separate browser / system-under-test session, an MCP probe) or generic exploration first, and **don't reconstruct or paste the test into a REPL** — those work in a *different context*, miss the suite's variables and setup, and send you chasing the wrong cause. Distinct from `results` (a finished run) and the REPL (exploration / building a keyword); reach for it when the recorded log isn't enough. Like the REPL it's an interactive prompt — **step through it live**, command by command, ending with `.continue`/`.detach`/`.abort`; never start it and wait for its exit. See [references/debugging.md](references/debugging.md).
 - **Analyze / lint the code** — *"find issues", "are there unused keywords?", "check my robot code".* `robotcode analyze code` (static analysis: missing keywords, wrong args, unresolved variables).
 - **Inventory / understand the project** — *"what tests/tags/suites exist?", "which tests have tag X?", "how big is this?", "what's my effective config?"* — `robotcode discover` (tree without running) and `config` / `profiles`. **Never read or grep `.robot` files to answer this** — see *Discovery* below for why a file scan gives the wrong answer.
 - **Look up a keyword or library** — *"what does X do?", "what args does it take?"* — `robotcode libdoc` (see *Documentation lookup priority* below).
@@ -45,11 +58,12 @@ For non-obvious RobotCode CLI details that are not library/resource keyword docu
 
 - **Setup** — If robotcode is missing, read [references/install.md](references/install.md).
 - **Cross-cutting** — Global options, output formats, profiles, tags, suites, tests.
-- **Commands** — Discovery, static analysis, library info, REPL, runs, configuration.
+- **Commands** — Discovery, static analysis, library info, REPL, runs, debugging, configuration.
 - **Results** — Inspecting finished runs; full reference in [references/results.md](references/results.md). **Always read this file before issuing any `robotcode results` command — do not guess flags from `--help` output alone.**
 - **Scale** — Large-project tactics in [references/large-projects.md](references/large-projects.md).
 - **Recipes** — Multi-step workflows in [references/workflows.md](references/workflows.md).
 - **REPL** — Interactive exploration and step-by-step development of tests and keywords in [references/repl.md](references/repl.md).
+- **Debugging** — Pausing a live run at a breakpoint and inspecting the stack/variables (`robotcode robot-debug`, `repl --break`) in [references/debugging.md](references/debugging.md).
 - **Authoring** — Writing/extending tests and reusable keywords (reuse → prototype → analyze → run) in [references/authoring.md](references/authoring.md).
 - **Reference** — Gotchas that prevent common agent mistakes.
 
@@ -153,6 +167,8 @@ Useful flags:
 - `-xm / -xe {error|warn|info|hint|all}` — mask severities from the exit code.
 - `--collect-unused` — include unused keyword / variable diagnostics.
 - `--output-format {concise|json|json-indent|sarif|github|gitlab}` + `--output-file <FILE>` — machine-readable / CI reports (SARIF, GitHub annotations, GitLab Code Quality).
+- `--show-tracebacks` — restore the Robot Framework tracebacks and `PYTHONPATH` dumps that the default concise output now hides; use only when a diagnostic's full body is needed.
+- `--full-paths` — emit absolute paths instead of project-relative ones.
 
 The exit code is a bitmask: `1` errors, `2` warnings, `4` infos, `8` hints. Check bits, not exact values. Default text output is one diagnostic per line — `path:line:col: [SEVERITY] CODE: message` (the tag is the full word, e.g. `[ERROR]`, `[WARN]`) — plus a summary. For structured consumption use `-f json` or `--output-format`. For commit-focused linting and suppression workflows, see [references/workflows.md](references/workflows.md).
 
@@ -190,6 +206,20 @@ Runs can be long. Use the maximum timeout your tool supports or run in the backg
 
 Robot returns the number of failed tests, capped at 250. Non-zero means failures or execution errors; inspect with `robotcode results summary`.
 
+## Debugging a run — `robotcode robot-debug`
+
+`robotcode robot-debug` (alias `run-debug`) runs a real suite through the same runner as `robotcode robot` but pauses at breakpoints and opens a `pdb`-style debug prompt with the live call stack, per-frame variables, introspection of the loaded keywords / libraries / resources (with their docs and sources), and the ability to run any keyword in the paused context. It takes the **full `robotcode robot` option set** plus trigger flags; the same debugger is always attached to `robotcode repl`, where breakpoints can be set up front with `--break` or interactively at the prompt with `.break`. Comes from the `repl` extra.
+
+```bash
+robotcode robot-debug -bl "Suite.Login Works"            # debug ONE known test: only it runs, pause lands inside it
+robotcode robot-debug --break login.robot:42 -t "Login Works"  # break at a line, but scope the run to that test
+robotcode robot-debug tests/                              # whole suite: pause at the first uncaught failure (default)
+robotcode robot-debug --break "Submit Login" tests/      # keyword breakpoint across a suite
+robotcode repl --break "Open Browser"                    # break at the REPL prompt
+```
+
+Reach for it over `results` when a recorded log isn't enough and you need the **live** state at the failure point. **Like the REPL, it's an interactive prompt — step through it live**, command by command (stop → `.where` / `.vars` / `.print ${x}` → choose the next step), and end with `.continue` / `.detach` / `.abort`; never start it and block on its exit. (An agent that can't drive a terminal can pipe a fixed command sequence instead — a fallback, see the reference.) Full breakpoint triggers, debug commands, and the interactive workflow are in [references/debugging.md](references/debugging.md).
+
 ## Configuration & profiles
 
 | Goal | Command |
@@ -236,9 +266,10 @@ For large projects, see [references/large-projects.md](references/large-projects
 For multi-step workflows, see [references/workflows.md](references/workflows.md):
 
 - Run tests and report failures.
-- Investigate a failing test without rerunning first.
+- Investigate a single failing test without rerunning first.
 - Lint only changed Robot files.
 - Analyze a project and manage suppressions / exit-code masks.
+- Fix a whole failing run: triage by cause, debug one representative per cause, re-validate with `--rerunfailed` against a *pinned* output file (intermediate runs overwrite `output.xml`).
 
 ## Gotchas — agent-correction notes
 
@@ -250,4 +281,6 @@ For multi-step workflows, see [references/workflows.md](references/workflows.md)
 - `uvx` / `pipx` isolates RobotCode from the project and gives wrong answers for real projects.
 - `No profiles defined.` is an empty result, not an error.
 - REPL syntax is not `.robot` file syntax.
+- **"Fix this test" / "why does it fail or not run?"** → go to the failure in its **real context, fast**: (1) read the actual error with `robotcode results` (`show --failed --message-chars 0`, `log`) — it often already names the cause (an unresolved or mis-composed variable, a wrong value); (2) if that's not enough, debug the **actual** test with `robotcode robot-debug -bl "<longname>"` (or `-t "<name>"`) — select the one failing test, don't hand the debugger the whole file (a bare path runs every test in it and may pause on a different one) — and inspect the live variables/stack at the failure. **Don't** first reach for external tools (a separate browser or system-under-test session, an MCP probe), reconstruct the test in a REPL, or start generic exploration — those run in a *different context*, can't see the suite's variables and setup, and routinely send you chasing a symptom in the live system when the real fault was a variable, value, or setup in the test itself.
+- `robotcode robot-debug` and `repl` are interactive prompts — step through them live, command by command, and end with `.continue` / `.detach` / `.abort`. Don't start one and wait for its exit code: with no input it sits at the prompt forever. (An agent without interactive terminal control can pipe a fixed sequence as a fallback.) At the `(rdb)` prompt `Ctrl-C` / `Ctrl-D` *resume* the run, they don't kill it — use `.abort` to actually stop. `Error: No such command 'robot-debug'` means the `repl` extra is missing.
 - "What tests/tags/suites exist?" — and any "which tests have tag X / are in suite Y" question — is answered with `robotcode discover`, never by reading or grepping `.robot` files. The effective set is resolved at runtime (paths, config, profiles, variables, pre-run modifiers); static sources don't show it.

chat-plugins/robotcode/skills/robotcode/references/authoring.md

@@ -1,8 +1,8 @@
 # Authoring tests and keywords with RobotCode
 
-Read this when the task is to **write, create, or extend** a `.robot`/`.resource` test, task, or reusable keyword. This is *not* a one-off exploration (that's [repl.md](repl.md)) and not running existing tests (that's workflows A in [workflows.md](workflows.md)). The focus here is the **robotcode-supported authoring loop**: reuse what already exists, prototype the uncertain parts live, write, check statically *before* running, then validate — using RobotCode's project-aware tooling at each step instead of guessing.
+Authoring tests, tasks, and reusable keywords with RobotCode follows a project-aware loop: **reuse** what already exists → **prototype** the uncertain parts live → **write** → **check statically before running** → **validate** — leaning on RobotCode's tooling at each step instead of guessing. This file covers that loop and the `robotcode` commands behind each step.
 
-This file is about the workflow and the RobotCode commands that support it; Robot Framework's own syntax is assumed knowledge (or look it up with `libdoc`).
+It applies whenever the task is to write, create, or extend a `.robot`/`.resource` test, task, or keyword — as opposed to a one-off exploration ([repl.md](repl.md)) or running existing tests (workflow A in [workflows.md](workflows.md)). Robot Framework's own syntax is assumed knowledge (or look it up with `libdoc`).
 
 ## Contents