simple-issue-description

Simple Issue Description Write an issue a maintainer can understand in under a minute. Focus on what someone experiences and what should happen instead. Workflow Read the supplied notes, conversation, issue, PR description, or diff. In a PR, also check for spec, design doc, or README changes — they often state the intent better than the description does. Identify the concrete problem. State who or what is affected when the source makes that clear. Describe the desired behavior without prescribing an implementation. Keep only context that helps someone understand or reproduce the problem. If the source is a PR or diff, describe the problem the change tries to solve, not the files or code it changes. Draft the issue immediately unless the problem and desired behavior cannot be determined. In that case, ask one short clarifying question. One issue per problem. If the source bundles unrelated problems, draft the issue for the most significant one, list the others in a line each, and tell the contributor to split them into separate issues and separate pull requests. If the source adds a capability instead of fixing a misbehavior, do not stage the absence as a bug. Describe what a user cannot do today and the full user experience of the feature: who uses it, from where, and what they see. Do not invent user impact, reproduction steps, or certainty that the source does not support. If the source only shows cleanup, refactoring, or a possible code smell, say that no concrete problem is clear instead of manufacturing an issue — this rule wins over step 6. Reply with two or three sentences: what the source shows, and what evidence would make it issue-worthy. Show more Installs 997 Repository every-app/open-seo GitHub Stars 14.3K First Seen Aug 12, 2026 Security Audits Gen Agent Trust Hub Pass Socket Pass Snyk Warn