GitHub Issues That Actually Include Reproduction Steps

Your GitHub issues fill with titles like broken and bodies that say doesn't work on my machine. Engineers close them as incomplete. Reporters feel ignored. The same report arrives three more times under slightly different wording. Maintainers spend twenty minutes asking "what version?" on tickets that should never have reached the queue.

Auto-responders that paste a CONTRIBUTING.md link help polite contributors and annoy everyone else. Long issue forms reduce volume and also reduce signal from busy users filing production outages. Free-text chaos means triage is archaeology. LLM replies that apologize and guess root cause without logs waste maintainer trust.

What maintainers actually need is structured intake: reproduction steps, environment, logs, validated before a human triages or before the bot promises a timeline. ValGuard does not replace GitHub's API. It replaces the hope that contributors will voluntarily format reports the way your triage runbook expects.

For why validation belongs before side effects in any production AI flow, see why "it usually works" isn't good enough for production AI.

Why Issue Bots Feel Hostile or Useless

Template walls. Ten required fields before submit filters drive-by complaints and also drive away engineers who have a stack trace and ninety seconds.

No validation, only nagging. Bots comment "please add repro steps" on every issue whether or not the body already contains them. Noise trains everyone to ignore the bot.

LLM triage without gates. A model drafts "thanks, we think this is a race in module X" from a title alone. Wrong guesses erode trust faster than silence.

Duplicate flows for bugs and features. Feature scoring needs impact and roadmap fields. Bug intake needs reproduction rigor. One generic form produces neither.

Premature closure. Strict bots close issues missing one field. Reporter reopens with "still broken." Maintainer now has two notifications and zero new data.

No maintainer-in-the-loop on promises. Auto-replies that imply fix timelines or root cause without human review become liabilities for OSS teams and internal platforms alike.

The common thread: nothing deterministically checks whether the issue JSON is complete before the workflow advances to triage draft or human assignment.

What Good Bug Intake Looks Like

Strong bug pipelines share traits whether the repo has three contributors or three hundred.

Required fields with teeth. Title, reproduction steps, environment (OS, runtime, version, browser), and error output. Placeholders such as "TBD" and "N/A" fail validation. An honest "no logs" needs a different path than a free-text excuse, and we cover that below.

Auto-reply that cites what is missing. Not a generic CONTRIBUTING link. "Add steps 1-N and the output of app --version" is actionable.

Triage draft only after pass. Maintainer edits the bot's suggested labels and reply. The bot does not commit to ship dates.

Re-validation on edits. New comments that change reproduction steps re-run intake checks. Cheap at scale when validation is milliseconds.

Separation from feature requests. Route "add dark mode" to a different playbook. Bug rigor frustrates feature filers; feature scoring frustrates bug reporters.

Deterministic validation on JSON intake catches placeholder text before your team sees the ticket. Probabilistic models can draft friendly asks for missing fields; rules decide whether the ticket is ready for triage.

Market Context: OSS Fatigue and Internal Platform Teams

Open source maintainers burn out on duplicate, incomplete issues. Internal platform teams face the same shape with different scale: hundreds of microservices, shared SDKs, and Slack threads that become "file a ticket" with no repro attached.

Popular OSS projects. High visibility, low bandwidth. Bots are necessary; bad bots become meme fodder. The bar is helpful specificity without closing valid outages.

Enterprise inner source. Employees expect white-glove support. Validators enforce the same bar as external contributors without maintainer shame spirals.

DevOps and on-call. Incidents compressed into GitHub issues need environment and timestamp fields for correlation with dashboard logs and deployment markers.

AI-generated issue summaries. Teams paste logs into ChatGPT, paste summary into GitHub. Summaries drop stack traces. Intake validation forces primary sources back into the ticket.

The tooling ecosystem offers templates, forms, and Actions. Few combine extraction, schema validation, and conditional auto-reply in one auditable pipeline. That gap is where incomplete tickets still reach humans.

The Intake-First Model Maintainers Want

Treat issue handling as a short orchestration graph, not a single model call.

Extract. Raw issue title and body become structured JSON: issue_title, reproduction_steps, environment, error_logs, optional expected_vs_actual.

Validate. The shipped github_issue_intake_agent template runs seven rules in priority order:

• valid_format requires JSON.
• required_fields requires the keys issue_title, reproduction_steps, environment, and error_logs.
• no_markdown_fenced_wrapper and no_duplicate_json_keys catch malformed model output.
• type_checking expects all four fields to be strings.
• min_length requires at least 40 characters.
• forbidden_patterns blocks "TBD," "N/A," "not sure," and "no logs."

Read that list carefully, because it sets the limits. We ran reports through the shipped pack. A report whose four fields are all empty strings passes every rule, because required_fields checks that the key exists and min_length counts the whole JSON text. Minimum step counts, version-string checks, and phrases like "doesn't work" or "see above" are not in the template. Add them as extra forbidden_patterns entries or custom rules for your repo.

The "no logs" pattern also cuts the other way. A report that says "no logs, mobile Safari has no console" is blocked, even though it is the explicit, reasoned absence we want. "Console output unavailable on iOS Safari" passes. If your reporters will use the first phrasing, remove that pattern and require non-empty error_logs some other way.

Branch.

• Fail: Auto-reply listing missing fields. Issue stays open. No triage draft yet.

• Pass: Draft triage reply for maintainer review: acknowledgment, suggested labels, links to docs, request for minimal repro repo if policy requires. Human sends or edits.

Log. Every validation result per issue event. Filter failures in observability when tuning required fields.

The GitHub Issue Auto-Responder playbook is intake-first, distinct from feature-scoring workflows.

Stage 1: Extract issue structure. Model or parser maps free text to JSON. Probabilistic step. The intake validation rules above run on this output.

Stage 2a: Request missing details. When intake validation blocks, generate a specific auto-reply. Steps, browser version, stack trace, commit hash. No premature close.

Stage 2b: Draft triage reply. When intake passes, draft helpful triage content under maintainer templates. Labels suggestion, related issues, docs links. Your policy, your tone.

Wire to GitHub via webhooks or Actions. ValGuard validates content and structure; you keep hosting and permissions on GitHub.

On our benchmark hardware the seven-rule intake pack evaluates in about 1.2 µs at p50. A guarded request through the proxy adds about 0.36 ms at p50 with a mocked upstream, excluding the model call. See the latency methodology for what each number includes. That is cheap enough to run on every new issue and on every comment that triggers a re-parse.

Benefits: Signal Up, Maintainer Hours Down

Fewer incomplete tickets in the human queue. Engineers triage bugs, not blank versions.

Specific bot replies. Contributors get a checklist, not a lecture. Completion rates rise when the ask is narrow.

Maintainer control on outward promises. Triage drafts wait for human send. Bots stop implying ETAs.

Audit trail for heated threads. "We asked for repro three times" becomes queryable rule history, not scrollback archaeology.

Consistent standards across repos. Same playbook forked per org: stricter env fields for CLI tools, lighter bar for docs typos if you split playbooks.

Shadow mode for tuning. Run validators on last month's issues. See how many would have triggered missing-field replies before enabling on newcomers.

Less duplicate work. Same vague issue filed five times still fails until one reporter adds steps. The other four get the same constructive auto-reply without maintainer copy-paste.

Practical Checklist: GitHub Issue Intake Validation

1. Define required JSON fields. At minimum: title, reproduction steps, environment, error logs. The shipped template types all four as strings, so send numbered steps as one string.

2. Reject placeholders. "TBD" and "N/A" are in the shipped list. Add "see screenshot" without an attachment URL and "latest" without a version string yourself.

3. Validate before triage draft. No suggested labels or root-cause language until pass.

4. Auto-reply with missing field list. Bullet what failed. Link to minimal example issue if you have one.

5. Re-run on edit. Issue comment edits re-trigger extract and validate.

6. Separate bug and feature playbooks. Different required fields, different bot voice.

7. Human gate on send. Draft only; maintainer approves in Actions or bot command.

8. Cap LLM apologizing. Templates for missing-info replies reduce sycophantic noise.

9. Log validation in shadow first. Tune env requirements against historical issues before enforce blocks triage.

10. Wire observability. Dashboard filtered by playbook shows fail reasons: missing logs vs vague steps.

11. Document for contributors. README states what the bot checks. Surprise creates hostility.

12. Avoid auto-close on first fail. Ask twice with specificity; close only under explicit policy after stale period.

For hands-on setup, start with the first playbook tutorial and fork the playbook template.

Closing: From "It Crashes Sometimes" to Triage-Ready

Incomplete issues are not malice. They are friction. Contributors report pain quickly; formatting repro steps slowly. Maintainers pay the difference in calendar time.

ValGuard turns vague reports into either structured JSON ready for engineering or a polite, specific request for what is missing, before a human spends twenty minutes on version archaeology.

Deploy the playbook on one noisy repo in shadow mode. Count how many open issues would fail intake today. Enable enforce on new issues when the missing-field replies read fair to your top contributors.

Book a technical walkthrough with our team →

Start free in shadow mode →