debug-run
Skill1 starsChanged 5 days agoApache-2.0View on GitHub
Use when a flowctl run failed, escalated, errored or looks wrong, or replay is flaky. Reads the run's evidence in a fixed order and classifies the cause as product bug, flowctl bug, System 1 mistake, flaky, wrong assertion, or infrastructure.
1 other project uses a version of this.
Adopted by
Most recently taken up by
- alphacrack/readme2demotheir own version, first seen Jul 5, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- alphacrack/readme2demo★ 9same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository8 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- extend-engineSkill
- review-prSkill
- seeded-bugSkill
- ship-prSkill
- stackSkill
- write-adrSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 17
Only then the trace: bunx playwright show-trace <dir>/trace-<profile>.zip.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Debug a run
Evidence is in <flowsDir>/.runs/<runId>/. For an observe run, the verdict is checks.json, not run.json: a
completed crawl's run.json says passed whatever the checks found (ADR 0033, amendment 2026-11-12).
Read in this order
run.json—status,failed(assertion +got, or step + kind),escalation(reason + controls),error.kind,healed,weakLocators,teardownFailed.decisions.jsonl(explore/heal) — per step: ranked ops with probabilities, chosen control,outcome. Look for lowp,BLOCKED, repeated identical actions, rejectedDONE.network.jsonandconsole.json— 4xx/5xx with bodies, matched requests, JS errors.final.png(and failure screenshots).report.htmlonce the report (T7.1) exists.- Only then the trace:
bunx playwright show-trace <dir>/trace-<profile>.zip. By default it has actions, timings, URLs and console only (run.jsonevidence.trace: "safe", ADR 0030). For DOM snapshots ask the user to rerun withflowctl replay <name> --trace full; that trace holds cookies and bodies, so never attach it to a bug. Credential-looking values and secret inputs show as***innetwork.jsonandgot; that is redaction, not what the app sent.
Classify
| Signal | Likely cause | Next step |
error.kind set | Infrastructure (app_unreachable, profile_expired, system1_unreachable, setup_failed) | Start the app, flowctl login, check network/key, fix the hook. Never report as a product bug |
error.kind flow_invalid / system1_not_allowed / hooks_untrusted / env_not_allowed | The flow file or request (bad YAML, template, a navigation off the env origin), an env not in system1.allowedEnvs, hooks without consent on this machine, an { env } input not allowed for the profile | Fix the flow; add the env to allowedEnvs only if it is not production; ask the user to run flowctl trust hook <name> or flowctl trust add profile <profile> <NAME> secret (never run either yourself) |
error.kind internal | A flowctl bug or a crashed browser | Read error.hint; reproduce; file it as a flowctl bug, never a product bug |
Exit code 3 (trust_missing, trust_tampered, …) | No trust store, project not registered, or a store changed outside flowctl | Ask the user to run flowctl trust init (never run it yourself) |
Escalated destructive_action | System 1 (or the orchestrator) reached a delete/approve-like control on a shared env | Intended? Restart with allowDestructive on data the run created; otherwise hint away from it |
network assertion got a 4xx/5xx | Product bug, or test data | Reproduce by hand or with the API; read the response body in network.json |
network matched nothing | Request not sent, different URL, or not fetch/xhr | failed.got ends with seen: METHOD /path, ... (the requests the run made); compare the glob with it and network.json; check the step that should send it |
text/value failed, network fine | Timing, wrong page, or wrong expectation | Check assertTimeout, the final URL, and the expectation against the source of truth (spec, AC, diff) |
Escalated BLOCKED / low_confidence | Unnamed control or ambiguous goal | weakLocators; give a hint or a directed step; consider adding a label/testId to the app |
Escalated loop / done_rejected | Ambiguous labels, or assertions the flow cannot reach | Read the repeated decision; re-check that every assertion is reachable by the goal |
| Replay step: 0 or >1 matches | UI changed | --heal, then review the YAML diff |
Different statuses across --repeat | Flaky: race, shared data, animation | Make data unique ({{uid}}), add a wait-free assertion, never add sleeps |
Never change an assertion to match what the run observed. Change it only when the source of truth says the expectation was wrong, and say so.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.