bash-discipline
Write bash that fails LOUDLY instead of returning a plausible wrong answer. Use when running sweeps/loops over many items, fetching files with curl, extracting fields from data files, or any time a command's output will become a factual claim. Provides the `bashguard` linter, a trap catalog, and the positive-control discipline.
- License 许可
- MIT
- 最近更新
- 2026-11-06
- Stars
- ★ 4
- Forks
- 0
01 前言 Front Matter
- name
- bash-discipline
- description
- Write bash that fails LOUDLY instead of returning a plausible wrong answer. Use when running sweeps/loops over many items, fetching files with curl, extracting fields from data files, or any time a command's output will become a factual claim. Provides the `bashguard` linter, a trap catalog, and the positive-control discipline.
02 资源文件 1
- 参考文档references/trap-catalog.md6.3 KB
03 SKILL.md 正文
Bash Discipline
The axiom: a command that fails loudly is cheap. A command that returns a plausible wrong number is expensive.
Every rule in this skill comes from a command that exited 0 — or failed in a way that looked like someone else's fault — while the conclusion drawn from it was false. Loud failures self-correct in one round-trip. Silent ones get written into reports, memories, and recommendations.
The tool
bashguard check '<command>' # lint before running (0 clean · 1 warn · 2 high)
bashguard check --brief --stdin # what the PreToolUse hook uses
bashguard rules # list all rules
bashguard explain BG001 # rule + fix + the incident behind it
bashguard selftest # NEGATIVE CONTROL — proves each rule fires AND stays quiet
~/tools/bashguard. The PreToolUse hook pre-bash-guard.sh runs it automatically and is advisory only — it never blocks. Silence one command with BASHGUARD_OFF=1.
After ANY edit to the rules, run bashguard selftest. A linter with a broken regex reports "clean" on everything, which is indistinguishable from clean code — the precise failure shape the tool exists to catch. The selftest caught a real false positive within a minute of the first rule being written.
The three habits (do these regardless of the linter)
1. Positive control before you trust a sweep
Before running a loop over N items and reporting a tally, run one item you KNOW is good and assert it passes. If the control fails, the instrument is broken and the sweep result is void — do not report it.
An all-negative sweep is far more often a broken loop than a real finding. Reference: a 40-item PDF sweep returned 40/40 "unreadable"; the corpus was fine, the loop was concatenating its inputs.
2. Three outcomes, never two
Never collapse to pass/fail. Always distinguish:
| meaning | |
|---|---|
ok |
measured, and it is good |
bad |
measured, and it is genuinely bad |
could not measure |
the instrument did not run — not a finding |
Collapsing the third into the second is how "0 matches" becomes "not present" and how a parse failure becomes "clean."
3. Check the status, not the file
curl -o out URL writes 403 and 404 bodies to disk and exits 0. Anything that consumes out afterward is parsing an error page. Either capture %{http_code} or use --fail.
Trap catalog
Eight rules, each with a real incident: references/trap-catalog.md, or bashguard explain <ID>.
| ID | Severity | Trap |
|---|---|---|
| BG001 | HIGH | for X in $VAR — zsh does not word-split; the loop runs once |
| BG002 | HIGH | field from a CRLF file carries \r, corrupting every URL built from it |
| BG003 | HIGH | curl -o with no status check — error pages written as data |
| BG004 | HIGH | counter mutated in a piped while read — lost to the subshell |
| BG005 | warn | relative script path with no cd — the harness resets cwd between calls |
| BG006 | warn | 2>/dev/null on the command whose result you then count |
| BG007 | warn | pass/fail sweep with no positive control |
| BG008 | warn | pipeline exit status branched on without pipefail |
Related, non-overlapping
pre-bash-negative-result-guard.sh—grep/rgpattern traps (BSD$anchor, ambiguous match)pre-bash-no-truncate-listing.sh—| head -Non enumerations- CLAUDE.md Negative-Result Rule — the judgment-level version of habit #1
- CLAUDE.md "Compared to What?" Rule — calibrating the result once you trust it
This skill covers the mechanical layer: loop, fetch, and data-integrity shapes that are detectable before the command runs.
04 同仓库更多 Skills
zi-search
暂无简介
visualise
Render inline interactive visuals — SVG diagrams, HTML widgets, charts, and explainers — directly in the conversation. Use this skill whenever the user asks to visualize, diagram, chart, illustrate, or explain something visually, or when an explanation would genuinely benefit from a spatial/interactive diagram rather than text. Also triggers for: flowcharts, architecture diagrams, data visualizations, interactive explainers, comparison layouts, UI mockups, and any request containing 'show me', 'draw', 'map out', 'visualize', or 'diagram'. Even when the user doesn't explicitly ask for a visual, use this skill proactively when the topic has spatial, sequential, or systemic relationships that a diagram would clarify better than prose.
video
When the user wants to create, generate, or produce video content using AI tools or programmatic frameworks. Also use when the user mentions 'video production,' 'AI video,' 'Remotion,' 'Hyperframes,' 'HeyGen,' 'Synthesia,' 'Veo,' 'Runway,' 'Kling,' 'Pika,' 'video generation,' 'AI avatar,' 'talking head video,' 'programmatic video,' 'video template,' 'explainer video,' 'product demo video,' 'video pipeline,' or 'make me a video.' Use this for video creation, generation, and production workflows. For video content strategy and what to post, see social-content. For paid video ad creative, see ad-creative.
manim-video
Production pipeline for mathematical and technical animations using Manim Community Edition. Creates 3Blue1Brown-style explainer videos, algorithm visualizations, equation derivations, architecture diagrams, and data stories. Use when users request: animated explanations, math animations, concept visualizations, algorithm walkthroughs, technical explainers, 3Blue1Brown style videos, or any programmatic animation with geometric/mathematical content.
video-use
Edit any video by conversation. Transcribe, cut, color grade, generate overlay animations, burn subtitles — for talking heads, montages, tutorials, travel, interviews. No presets, no menus. Ask questions, confirm the plan, execute, iterate, persist. Production-correctness rules are hard; everything else is artistic freedom.
ui-improver
暂无简介