This document explains why Ouroboros prefers structured GitHub issues.
GitHub is the source of truth for actionable work. Clear issues help maintainers, contributors, and future tooling understand what problem exists, what success looks like, and whether something is ready to implement.
- Bug reports should make reproduction and verification possible.
- Feature requests should explain the problem, the desired outcome, and what “done” looks like.
- Exploratory ideas should usually start in Discussions or Discord before becoming implementation issues.
- Better issue quality reduces clarification churn and off-target PRs.
- Structured issues are easier for both humans and tooling to read.
- Ambiguous issues are hard to review, scope, and verify safely.
- For bugs, include enough detail for someone else to reproduce the problem.
- For features, focus on the problem and acceptance criteria before debating implementation details.
- If an idea is still fuzzy, discuss it first and turn it into a GitHub issue once it is actionable.
- Ask for the minimum missing structure rather than rejecting an idea outright.
- Redirect open-ended brainstorming to Discussions or Discord when needed.
- Avoid starting implementation from issues that are too vague to verify.