菜单
The workflow for turning a newly diagnosed readme2demo run failure into a permanent, tested defense. Use after debug-run identifies a failure mechanism that is not yet in CLAUDE.md's known-failure-classes table.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Debug a failed, unverified, or low-quality readme2demo pipeline run. Use when a run fails at any stage, verify won't pass, the demo video is short or missing steps, generated docs lack detail, or the user pastes readme2demo CLI output showing a failure.
Add a new AI agent backend (engine) to readme2demo, or fix parsing for an existing one (claude-code stream-json drift, openhands trajectory changes). Use when adding support for a new coding agent or when transcripts stop parsing after an agent CLI upgrade.
Docker usage in readme2demo — the base image, hardened sandbox lifecycle, the Docker-socket opt-in, and diagnosing container/daemon failures. Use when touching sandbox.py, images/base/Dockerfile, render.py, verify.py, or when a run fails with a docker/daemon/permission/disk error.
Git and GitHub operations for maintaining the readme2demo repo — branching, conventional commits, PRs, releases, and the never-commit rules. Use when committing, opening a PR, tagging a release, or doing any git/gh operation on this repo.
Python coding standards, testing patterns, and pydantic/typing conventions for the readme2demo codebase. Use when writing or reviewing any Python in src/readme2demo/ or tests/, adding a module, or before committing code changes.
How readme2demo handles TARGET-repo languages and toolchains (Go, Node, Python, Rust, Terraform, etc.) inside the sandbox — version currency, install patterns, and the agent rules that keep runs honest. Use when a run fails on a toolchain install/version, or when extending language support in the base image or agent prompt.
| name | add-failure-class |
| description | The workflow for turning a newly diagnosed readme2demo run failure into a permanent, tested defense. Use after debug-run identifies a failure mechanism that is not yet in CLAUDE.md's known-failure-classes table. |
Every robustness feature in this repo came from a real failed run processed through exactly these steps. Do them in order; skipping the test or the CLAUDE.md entry is how knowledge evaporates.
Name the mechanism, not the symptom. "verify exit 1" is a symptom; "findings tools exit nonzero on success and set -e kills the assertion" is a mechanism. You must be able to say which two components disagreed about an assumption.
Pick the owning module (one, occasionally two):
prompts/agent.md rule AND a detector in
normalize.py (rule 6 + repo_files_edited is the template)distill.normalize_cmd / _grounded_candidates
(always symmetric, both directions tested)distill._render_commands_sh (assertion block) or
verify.pytemplates/demo.tape.j2 / render.py gatesCode first, prompt second. If the fix involves an LLM behaving differently, the prompt edit gets a sibling code-level check or validation — prompts alone are not defenses.
Regression test named for the run. Docstring starts with
"""Regression (<repo> run): ...""" describing the real failure. Must
fail on the old code. Tests stay free of docker/network/API.
Repair the triggering run cheaply (see debug-run skill) and give the exact resume command.
Document: add a numbered entry to CLAUDE.md "Known failure classes" (symptom → mechanism → defense location). If the class is user-visible, consider a line in README or the troubleshooting-relevant prompt.
Full suite green (python -m pytest tests/ -q) before claiming done.
New equivalences (like the 2>&1 or pipe-variant rules) must:
is_grounded docstring's accepted-forms list.