jungenius-stack/pitfall-expert

---

Your agent said “done” — and the migration isn’t. It agreed with the doomed plan, called single-run luck “reliable”, and you found out when the bill arrived.

pitfall-expert scans the task before work starts: it matches the task against a six-domain library of 100+ pitfall cards in cards/ — each distilled from real incidents and peer-reviewed research — binds every blocking pit to an executable verifier (pre-declared decision table + executed-result write-back), and outputs a three-zone honest report: ✅ verified (evidence chains, quotable sources) / ❓ unverified (5-minute follow-up actions) / 🚫 declared blind spots.

The failure modes come with receipts, because they’ve been measured: agents declare solvable tasks impossible (54.9% of WebArena failures), claim completion while the environment is unchanged (MAST), pass weak test suites (7.8% of “passing” SWE-bench patches are wrong), mistake single-run luck for reliability (pass^8 < 25%), and side with a wrong user over half the time (Science, 2026: 51%). Those exact findings are seed cards in this library — card counts live in cards/; trust the directory over any number in prose.

Everything runs locally: a keyword scan over YAML cards, no network calls, no task text leaving your machine.

Done = fully disclosed, not perfect. Missed pits are forgivable; false “verified” claims are not. 完成等于披露完整，而非结果完美。漏报可原谅，谎报不可原谅。

Quick start

Install the skill

git clone https://github.com/jungenius-stack/pitfall-expert.git && cd pitfall-expert
sh install.sh          # installs to every detected agent's skills dir, cards included

Works with any harness that reads ~/.agents/skills/ (ZCode, DeepSeek Harness), ~/.claude/skills/ (Claude Code), or ~/.workbuddy/skills/. Uninstall: sh install.sh --uninstall.

Ask your agent

先踩坑：我打算把生产数据库从 MySQL 迁到 PostgreSQL
Pitfall-check this before you start: I'm about to migrate our pricing data pipeline

You get a three-zone report like the mini-sample at the bottom of skills/pitfall-expert/SKILL.md.

Use the terminal

node engine/src/cli.js "migrate users.csv into SQLite, watch nulls and encodings" --tier standard

Make it mandatory (recommended)

Skills auto-activate only 20–50% of the time (community measurements). The gate doesn’t rely on anyone’s discipline — see hooks/README.md (PreToolUse: report-by-default, PITFALL_HOOK_MODE=block hard-blocks rm -rf / git push --force) and dsh-plugin/README.md.

Zero-install tryout

No harness? Paste the lite prompt from docs/入门版-贴即用.md into any chat model — it keeps the four survival mechanisms (tier gate, specificity filter, three-zone disclosure, blocking checklist); card matching and verifiers are full-version features.

How it works

Your agent (or the CLI) scans the task against cards/.yaml — every card matched with evidence, every blocking pit bound to a runnable verifier. The skill persona (L0–L5 pipeline, 13 mechanisms) runs the parts engines can’t: assumption dumping, pre-mortem, user-constraint profiling. Then the report passes a six-item DoD machine check (dod_check.py). Skill = the instructions, engine = the muscle, hooks = the seatbelt.

What it can catch

Card counts live in cards/ — trust the directory, not this table. The strategy domain is a declared placeholder: no cards means no cards, stated out loud in every report’s blind-spot zone.

Battle record

Numbers, not adjectives — every claim replay-tested:

• 10/10 real failure-case replays passed (cards distilled from a 56K-char incident log);
• 12/13 coverage on an external blind test — 13 real-world pitfalls from two practitioner talk transcripts (one uncovered item = collaboration-management domain, exactly where the capability table said “no cards”);
• 4 meta-pitfalls caught on ourselves during development (e.g. an allow-list rule that silently passed git push --force) — logged openly in the meta-pitfall registry, now 17 entries including two “looked like pure gain, rolled back same day” matching experiments;
• Dual-source red-team reviews (v0.6): a fresh-context subagent and an out-of-family GLM-4.6 each attacked the design; 20+ failure modes archived, 13 fixed (red team / adversarial review);
• Two independent implementations (built in parallel on two platforms) converged on the same honesty axioms — merged in v0.4. A 240K-star tool (REA) independently ships the same skill+engine+plugin distribution shape.

Report misses & false hits

The library upgrades on real cases. If a pit wasn’t caught (false negative) or an irrelevant card fired (false positive), rerun the scan with --feedback: it emits a de-identified bundle — card IDs, scores, library/engine versions, domain verdict; no task text by default (--with-task to include, review before posting) — ready to paste into the false-negative / false-positive issue templates. Every case becomes a regression sample in the noise battery and the eval set.

node engine/src/cli.js "your task" --tier standard --feedback

Showcase: if it caught a real pit for you, open an issue labeled showcase — real cases become new cards, credited in source_ref.

FAQ

Documentation

• skills/pitfall-expert/SKILL.md — the pipeline itself (L0–L5, M1–M13 mechanisms, mini sample)
• docs/踩坑专家方法论_v0.3.md — methodology source of truth (9 layers, self-bootstrap replay) · Chinese
• docs/cases/ — the replay exam archive (real failure cases + external blind tests)
• docs/01..04 — prior-art survey (15 external solutions, gap confirmed), 34-item mechanism survey, design doc, form-factor comparison · Chinese
• CONTRIBUTING.md — card contributions: four essentials, bilingual triggers, evidence levels

Provenance (honest)

v0.4+ is a merger of two independent implementations built in parallel from one brief on two platforms (ZCode + WorkBuddy). Both converged on identical honesty axioms; each side contributed what it was best at. The merger’s own stumbles are logged as meta-pitfalls ⑨–⑫, not hidden. Translations beyond English/Chinese welcome — see CONTRIBUTING.

License

Code (engine/, skills/, hooks/, dsh-plugin/): MIT. Pitfall-card data & docs (cards/, docs/): CC BY 4.0 — life-saving checklists shouldn’t be locked up.