Files
solidcraft/skills/solidcraft-reporting/SKILL.md
T
raykholo 309eda87a2 Agent skill for reproducible bug reports (#3983) (#3984)
* claim: #3983

* Agent skill for reproducible bug reports (#3983)

skills/solidcraft-reporting has an agent gather the version, steps and
exact error, reproduce the problem in a fresh design (a command script or
one batch with rollback off), shrink it while it still fails, check the
numbers with measure and a screenshot, keep private designs out, search
for duplicates, and write the report in one shape: Reproduced on, Steps
with a minimal script, Expected, Actual, Attachments.

Listed in skills/README.md and docs/mcp.md; the bug template's steps
field points agents to it. The skill-name check now covers its files.

* Reporting skill: GitHub takes a design only as a .zip
2026-10-25 17:56:18 +00:00

58 lines
6.9 KiB
Markdown

---
name: solidcraft-reporting
description: Use when a SolidCraft user says something went wrong - the app crashed or closed, a command failed or gave the wrong shape, a number is off, a design no longer rebuilds, something hangs - and wants it reported or fixed upstream. Turns the problem into a minimal, reproducible bug report with exact steps, a command script, expected and actual results and a screenshot.
---
# SolidCraft reporting
A report the maintainers can act on reproduces in a fresh design, in as few steps as possible, with the exact message and numbers. Build that here, so nobody has to rebuild the problem from a description. Use `reference.md` from `solidcraft-modeling` for command shapes, and `reference/report-template.md` (next to this file) for the report.
Written against SolidCraft 0.18.2. Report what you observed, never a guessed cause: "the fillet fails with `…`", not "the kernel can't handle tangent edges".
## 1. Gather (ask only for what you cannot find)
- **Version and OS.** Help → About in the app, `solidcraft --version` or `solidcraft-cli --version`; the MCP server reports its version in `initialize` (`serverInfo.version`). Note whether the user built from source.
- **What the user did**, in order, what they expected and what happened instead.
- **The exact error text**, copied, not paraphrased: a failed `execute` or `batch` step's `failed.error`, the timeline feature's `error` in `inspect_design {"measure":false,"sketches":false}`, or the message in the app.
- **If the app closed or froze:** `crash_reports {}` first. A matching report has the version, the command that crashed, the commands before it and a replay. `solidcraft-cli crashes replay <id>` checks that it still happens. Its `design.solidcraft` is the user's design: see Privacy.
## 2. Reproduce in a fresh design
Start from nothing, so the report does not depend on the user's file.
- **Headless:** write the steps as a command script `{"commands":[...]}` and run `solidcraft-cli run repro.json`. A failing feature fails the run and names the feature. This never touches the design open in the app.
- **Over MCP:** `new_design {}`, then the steps in one `batch {"commands":[...],"rollback":false}`. With `rollback: false` the steps before the failure stay, so you can inspect the state it failed in. When the server is bridged to the app and the open design is `dirty`, ask before `new_design`.
- Find commands and parameters with `list_commands {"filter":"fillet"}` and `describe_command {"id":"solid.fillet"}`, not the unfiltered catalog.
- **Only in the user's design:** `solidcraft-cli script design.solidcraft --out repro.json` writes its history as a command script. `solidcraft-cli eval repro.json` replays it and prints the measurements; `solidcraft-cli run repro.json` stops at the first failing feature. If the script rebuilds without the problem, say so in the report: it then depends on something the history does not hold (an import, a file the design links to).
- **Interactive only** (a dialog, a pick, a drag, the viewport): write the clicks as numbered app steps. A script cannot show those.
- Check that it fails the same way twice. A problem that comes and goes is still worth reporting; say how often it happened.
## 3. Minimise
Shrink while the same failure, with the same message, still happens. Re-run after every change:
1. Drop steps from the end, then from the middle: other bodies, features after the failing one, cosmetic steps (appearance, names, views).
2. Replace sketches with `solid.box` or `solid.cylinder` where the failure survives it.
3. Round the dimensions (10, 20, 2.5) and replace parameter expressions with numbers, unless an expression is the problem.
4. Stop when removing anything more makes it pass. Note the boundary when you find one ("fails at radius 5, works at 4.9").
**Hangs and slow commands:** never wait forever. Cap every run: `timeout 120 solidcraft-cli run repro.json --timings` prints the milliseconds of each step when the run finishes. A run that is killed prints nothing, so find the slow step by running the script one step longer at a time. Over MCP, `batch {"commands":[...],"timings":true}` reports every step's time, the failing one included. Report the step, the time, and how the time grows when you double a count or a size.
## 4. Check the claim
- Wrong geometry: `measure {}` (volume, area, bounding box, centre of mass) against a value you computed by hand. Put both numbers in the report.
- Wrong pick or wrong face: `body_topology {"body":"Body1"}` shows what was there to pick.
- A look at it: `screenshot {"view":"iso"}` after the `rollback: false` batch, or `solidcraft-cli snapshot repro.json --out shot.png --view iso`. `snapshot` fails with the script when a step fails, so for a failing command snapshot the script without that step and show the state it fails on. Look at the image before you attach it.
- Re-run the final minimal script from scratch once more. Its output goes into the report as it is.
## 5. Privacy
- Never attach, upload or quote the user's design, a crash report's `design.solidcraft`, or file contents without asking. The minimal synthetic script is the default attachment.
- GitHub does not accept `.solidcraft` attachments. A design the user agrees to share goes up as a `.zip`: a `.solidcraft` file is a ZIP already, so copy or rename it to `name.solidcraft.zip`, or zip it. SolidCraft opens either kind of `.zip`.
- Strip home folders, user names, part and project names and file paths from messages and logs (`/home/alice/clients/acme/bracket.solidcraft` → `bracket.solidcraft`).
- Check screenshots for other windows, file names and anything personal.
## 6. Search, then write
- Search before writing: `gh issue list -R tangency-labs/solidcraft --state all --search "fillet radius"` with two or three words from the error and the command. If one matches, add the minimal script and your version to it as a comment, instead of filing a new one.
- Write the report with `reference/report-template.md`. Title `<Area>: <what fails>`, such as `Fillet: a radius above half the edge's face fails with "…"`.
- Show the user the finished report. File it only after they approve: `gh issue create -R tangency-labs/solidcraft --label bug --title "…" --body-file report.md`, or let them paste it into **Report a bug** in the app's title bar, which adds a screenshot they review first.
## Traps
- **The wrong version.** The CLI on `PATH` can be older or newer than the app the user ran. Reproduce with the user's version and say which one you used.
- **Fixed already.** If it does not reproduce on the latest release or `main` but does on the user's version, say so: it saves a report.
- **Edge picks** snap to the nearest edge with no distance limit and no error, so a repro can pick a different edge than the user did. Check the face count or `body_topology` after the step.
- **A success can be the bug.** A cut that misses its body still reports success. Measure, don't trust the reply.