bugbash

Name: bugbash
Author: av

199stars9forks

How to install bugbash?

av/facts/bugbash

$npx -y skills add av/facts --skill bugbash

Installs into the current project.

Summary

Systematically explore and test any software project (CLI, API, Backend, Library, etc.) to find bugs, usability issues, and edge cases. Produces a structured report with full reproduction evidence (exact commands, inputs, logs, and tracebacks) for every issue.

Files · 1

View on GitHub

SKILL.md

1	# Bugbash (General Software)
2
3	Systematically explore a software project, find issues, and produce a report with full reproduction evidence for every finding. This skill applies to CLIs, APIs, Backends, Libraries, and other non-web interfaces.
4
5	## Setup
6
7	Identify the Target (e.g., a CLI binary, an API base URL, a Python package).
8
9	\| Parameter \| Default \| Example override \|
10	\|-----------\|---------\|-----------------\|
11	\| Target \| _(required)_ \| `./my-cli`, `http://localhost:8080`, `import mylib` \|
12	\| Output directory \| `/tmp/dogfood-output/` \| `Output directory: ./qa-reports` \|
13	\| Scope \| Full project \| `Focus on the auth middleware` \|
14
15	## Workflow
16
17	```
18	1. Initialize Set up output dirs, report file, build/start the software
19	2. Orient Discover surface area (help menus, API schemas, exported functions)
20	3. Explore Systematically test features, inputs, and edge cases
21	4. Document Record exact inputs, outputs, and logs for each issue
22	5. Wrap up Update summary counts, finalize report
23	```
24
25	### 1. Initialize
26
27	```bash
28	mkdir -p {OUTPUT_DIR}/logs {OUTPUT_DIR}/evidence
29	```
30
31	Create a `report.md` in the output directory and fill in the header fields. Include:
32	- Target
33	- Date
34	- Environment Details (OS, language version)
35	- Summary Counts (Critical, High, Medium, Low)
36
37	If the software needs to be built or started (e.g., `npm run build`, `docker-compose up`, `cargo build`), do that now. Keep track of the startup logs and run servers in the background if necessary (e.g., using `&` and redirecting output).
38
39	### 2. Orient
40
41	Map out the surface area of the software before testing.
42
43	- For CLIs: Run `{TARGET} --help`, list subcommands, check environment variable configurations.
44	- For APIs: Fetch OpenAPI/Swagger specs, list route definitions in code, or run a schema discovery tool.
45	- For Libraries: Inspect exported modules, classes, and public methods.
46
47	Save this initial mapping to `{OUTPUT_DIR}/surface-area.txt`.
48
49	### 3. Explore
50
51	Work through the surface area systematically.
52
53	- Happy Paths: Test the primary use cases. Does it do what it claims to do?
54	- Invalid Inputs: Pass wrong types, extremely large strings, negative numbers, malformed JSON.
55	- Missing Context: Run commands without required environment variables, missing config files, or unauthenticated API calls.
56	- Boundary Conditions: File not found, permission denied, port already in use.
57
58	At each step:
59	Capture standard output, standard error, exit codes, and HTTP status codes.
60
61	### 4. Document Issues (Repro-First)
62
63	Document issues as you find them. Do not wait until the end. Every issue must be reproducible by a human reading the report.
64
65	For each issue, capture:
66	1. Description: What is the bug or UX issue?
67	2. Severity: Critical (crash/data loss), High (broken core feature), Medium (broken edge case), Low (UX issue/typo).
68	3. Repro Steps: Exact commands run, API requests made (e.g., `curl` commands), or code executed.
69	4. Expected vs Actual Behavior: What should have happened vs what actually happened.
70	5. Evidence:
71	- Stdout/Stderr output
72	- Stack traces or panic messages
73	- Log file snippets
74	- Exit codes
75
76	Save verbose evidence (like full crash dumps or multi-megabyte log files) to `{OUTPUT_DIR}/evidence/issue-{NNN}.txt` and reference it in the report. For short errors, embed them directly in the report using markdown code blocks.
77
78	### 5. Wrap Up
79
80	Aim to find 5-10 well-documented issues. Depth of evidence matters more than total count — 5 issues with full repros beat 20 with vague descriptions.
81
82	After exploring:
83	1. Re-read the report and update the summary severity counts so they match the actual issues. Every issue block must be reflected in the totals.
84	2. Stop any background processes (e.g., API servers) started during initialization.
85	3. Tell the user the report is ready and summarize findings: total issues, breakdown by severity, and the most critical items.
86
87	## Guidance
88
89	- Repro is everything. Every issue needs proof. Provide the exact `curl` command, CLI invocation, or script used to trigger the bug. A reader should be able to copy-paste the commands to see the exact same failure.
90	- Verify reproducibility. Before documenting an issue, verify it is reproducible with at least one retry. If it's flaky, note that and try to identify the conditions.
91	- Capture the environment state. Often bugs depend on the environment (files present, variables set). Note `pwd`, env vars, or local files if they are part of the repro.
92	- Write findings incrementally. Append each issue to the report as you discover it. If the session is interrupted, findings are preserved. Never batch all issu

People who liked this also viewed

6 picks

Type

bugbash

199stars9forks

View on GitHub

How to install bugbash?

av/facts/bugbash

$npx -y skills add av/facts --skill bugbash

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Bugbash (General Software)
2
3	Systematically explore a software project, find issues, and produce a report with full reproduction evidence for every finding. This skill applies to CLIs, APIs, Backends, Libraries, and other non-web interfaces.
4
5	## Setup
6
7	Identify the Target (e.g., a CLI binary, an API base URL, a Python package).
8
9	\| Parameter \| Default \| Example override \|
10	\|-----------\|---------\|-----------------\|
11	\| Target \| _(required)_ \| `./my-cli`, `http://localhost:8080`, `import mylib` \|
12	\| Output directory \| `/tmp/dogfood-output/` \| `Output directory: ./qa-reports` \|
13	\| Scope \| Full project \| `Focus on the auth middleware` \|
14
15	## Workflow
16
17	```
18	1. Initialize Set up output dirs, report file, build/start the software
19	2. Orient Discover surface area (help menus, API schemas, exported functions)
20	3. Explore Systematically test features, inputs, and edge cases
21	4. Document Record exact inputs, outputs, and logs for each issue
22	5. Wrap up Update summary counts, finalize report
23	```
24
25	### 1. Initialize
26
27	```bash
28	mkdir -p {OUTPUT_DIR}/logs {OUTPUT_DIR}/evidence
29	```
30
31	Create a `report.md` in the output directory and fill in the header fields. Include:
32	- Target
33	- Date
34	- Environment Details (OS, language version)
35	- Summary Counts (Critical, High, Medium, Low)
36
37	If the software needs to be built or started (e.g., `npm run build`, `docker-compose up`, `cargo build`), do that now. Keep track of the startup logs and run servers in the background if necessary (e.g., using `&` and redirecting output).
38
39	### 2. Orient
40
41	Map out the surface area of the software before testing.
42
43	- For CLIs: Run `{TARGET} --help`, list subcommands, check environment variable configurations.
44	- For APIs: Fetch OpenAPI/Swagger specs, list route definitions in code, or run a schema discovery tool.
45	- For Libraries: Inspect exported modules, classes, and public methods.
46
47	Save this initial mapping to `{OUTPUT_DIR}/surface-area.txt`.
48
49	### 3. Explore
50
51	Work through the surface area systematically.
52
53	- Happy Paths: Test the primary use cases. Does it do what it claims to do?
54	- Invalid Inputs: Pass wrong types, extremely large strings, negative numbers, malformed JSON.
55	- Missing Context: Run commands without required environment variables, missing config files, or unauthenticated API calls.
56	- Boundary Conditions: File not found, permission denied, port already in use.
57
58	At each step:
59	Capture standard output, standard error, exit codes, and HTTP status codes.
60
61	### 4. Document Issues (Repro-First)
62
63	Document issues as you find them. Do not wait until the end. Every issue must be reproducible by a human reading the report.
64
65	For each issue, capture:
66	1. Description: What is the bug or UX issue?
67	2. Severity: Critical (crash/data loss), High (broken core feature), Medium (broken edge case), Low (UX issue/typo).
68	3. Repro Steps: Exact commands run, API requests made (e.g., `curl` commands), or code executed.
69	4. Expected vs Actual Behavior: What should have happened vs what actually happened.
70	5. Evidence:
71	- Stdout/Stderr output
72	- Stack traces or panic messages
73	- Log file snippets
74	- Exit codes
75
76	Save verbose evidence (like full crash dumps or multi-megabyte log files) to `{OUTPUT_DIR}/evidence/issue-{NNN}.txt` and reference it in the report. For short errors, embed them directly in the report using markdown code blocks.
77
78	### 5. Wrap Up
79
80	Aim to find 5-10 well-documented issues. Depth of evidence matters more than total count — 5 issues with full repros beat 20 with vague descriptions.
81
82	After exploring:
83	1. Re-read the report and update the summary severity counts so they match the actual issues. Every issue block must be reflected in the totals.
84	2. Stop any background processes (e.g., API servers) started during initialization.
85	3. Tell the user the report is ready and summarize findings: total issues, breakdown by severity, and the most critical items.
86
87	## Guidance
88
89	- Repro is everything. Every issue needs proof. Provide the exact `curl` command, CLI invocation, or script used to trigger the bug. A reader should be able to copy-paste the commands to see the exact same failure.
90	- Verify reproducibility. Before documenting an issue, verify it is reproducible with at least one retry. If it's flaky, note that and try to identify the conditions.
91	- Capture the environment state. Often bugs depend on the environment (files present, variables set). Note `pwd`, env vars, or local files if they are part of the repro.
92	- Write findings incrementally. Append each issue to the report as you discover it. If the session is interrupted, findings are preserved. Never batch all issu

People who liked this also viewed

6 picks

Type