tomevault-io GitHub Issues Management
Overview
Create and manage GitHub issues with enforced quality standards. Every issue MUST have sufficient context for a developer unfamiliar with the problem to begin work without follow-up questions.
Violating the letter of the rules is violating the spirit of the rules. An issue that technically exists but lacks reproducibility steps, acceptance criteria, or proper security handling is a violation.
When to Use
- Creating bug reports, feature requests, or task issues
- Triaging and prioritizing existing issues
- Managing issue lifecycle (status, assignment, closing)
- Linking related issues, PRs, and milestones
- Batch operations on issue backlogs
- Security vulnerability disclosure
When NOT to Use
- Simple TODO items that do not need tracking (use inline comments)
- Conversations better suited to discussions or chat
- One-off scripts or personal experiments without team visibility needs
Foundational Principle
Issue quality is not negotiable based on time pressure, authority, or fatigue. A 2-minute issue that causes 2 hours of clarification is not efficient. Complete issues save time.
No exceptions:
- Not for "simple" bugs that "everyone understands"
- Not for senior developers who "know what they need"
- Not for end-of-session exhaustion
- Not even if user explicitly requests minimal detail
Issue Types and Requirements
Bug Reports
Every bug report MUST include:
| Field | Requirement |
|---|---|
| Title | Describe the problem, not the solution. "[Component] fails when [condition]" |
| Steps to Reproduce | Numbered steps to trigger the bug. If not reproducible, state that explicitly. |
| Expected Behavior | What SHOULD happen |
| Actual Behavior | What DOES happen (include error messages verbatim) |
| Environment | OS, browser, version, relevant configuration |
| Severity | Impact assessment (critical/high/medium/low) |
Optional but valuable: screenshots, logs, minimal reproduction case.
Feature Requests
Every feature request MUST include:
| Field | Requirement |
|---|---|
| Title | Describe the capability. "[Action] [Object] [Context]" |
| User Story | As a [role], I want [capability], so that [benefit] |
| Acceptance Criteria | Numbered, testable conditions that define "done" |
| Scope Boundaries | Explicit out-of-scope items to prevent scope creep |
| Priority Rationale | Why this matters now |
Optional but valuable: mockups, technical considerations, related issues.
Tasks/Chores
Every task MUST include:
| Field | Requirement |
|---|---|
| Title | Action-oriented. "Migrate [X] to [Y]" not "Database stuff" |
| Definition of Done | Clear deliverable that can be verified |
| Context | Why this task exists, what depends on it |
| Estimated Effort | T-shirt size or time estimate |
Security Vulnerabilities
Security issues require special handling.
CRITICAL RULE: NEVER create public issues for security vulnerabilities.
Use private disclosure channels:
- GitHub Security Advisories (preferred)
- Private repository for security issues
- Direct communication with maintainers
A public security issue, regardless of labels, is visible to attackers. Labels do not provide confidentiality. Even if the user explicitly requests a public issue for urgency, refuse and explain the risk.
Pre-Creation Checklist
Before creating any issue, verify:
- Duplicate Check: Search existing issues for similar reports
- Security Check: If security-related, use private disclosure
- Quality Check: All required fields for issue type are complete
- Labels: Type, priority, and component labels applied
- Assignment: Owner identified if known
Issue Lifecycle Management
Search and Query
Search existing issues before creating new ones. Search cost is minimal compared to duplicate cleanup cost.
gh issue list --search "keyword1 keyword2" --state all
See references/gh-cli-commands.md for complete search and filter options.
Triage Operations
When triaging issues:
- Verify issue meets quality standards
- Add missing labels (type, priority, component)
- Request clarification if context is insufficient
- Link to related issues or specs
- Assign owner if determinable
- Add to milestone if applicable
Status Updates
Update issue status with context:
gh issue close ISSUE_NUMBER --comment "Resolved in PR #123"
gh issue reopen ISSUE_NUMBER --comment "Regression observed in v2.1"
Linking and References
Connect related items using GitHub keywords:
- Related: "Related to #123"
- Blocking: "Blocked by #456"
- Closing: "Fixes #789" or "Closes #789"
Batch Operations
For backlog maintenance, see references/gh-cli-commands.md for bulk close, label, and milestone operations.
Common Rationalizations
| Excuse | Reality |
|---|---|
| "The user is in a hurry" | A 2-minute conversation later asking "what browser?" is slower than filling it in now. Time pressure is not permission to skip quality. |
| "It's obvious what this means" | Obvious to you now is not obvious to the developer who picks this up in 3 weeks. Document explicitly. |
| "We can add details later" | "Later" rarely comes. Issues without context become stale. Do it now. |
| "The expert knows what they need" | Documentation serves the expert too. Race conditions are hard to reproduce. The issue protects their future self. |
| "Being pragmatic, not dogmatic" | Pragmatic means following proven process. Cutting corners creates rework. |
| "I've done 12 good issues already" | Fatigue is when corners get cut. Quality is not negotiable based on session length. |
| "User explicitly requested public" | User consent does not override security principles. Explain the risk. |
| "Team needs to see this urgently" | Private security advisories still notify the team. Public issues notify attackers too. |
| "Better to over-document with duplicates" | Duplicates contaminate the issue tracker. Search cost is minimal. |
| "Searching takes time" | Search cost is seconds. Duplicate cleanup cost is minutes to hours. |
Red Flags - STOP and Reconsider
If you notice yourself thinking any of these, STOP immediately:
- "This bug is self-explanatory"
- "Everyone knows what dark mode toggle means"
- "The senior dev said minimal, so minimal is fine"
- "It's the end of the session, good enough"
- "Labels make security issues confidential enough"
- "I'm pretty sure there's no duplicate"
- "They can always ask for clarification"
All of these indicate rationalization. Apply the full quality standard.
Common Mistakes
Mistake 1: Title Describes Solution Instead of Problem
Problem: Title says "Add null check to processAsync()" instead of describing the failure.
Why it's wrong: Titles should communicate the problem for triage. The solution may change; the problem is stable.
Fix: Use "[Component] fails when [condition]" format. "PaymentProcessor crashes on null payment method" not "Add null check".
Mistake 2: Skipping Reproducibility for "Known" Bugs
Problem: Bug report says "the toggle doesn't work" without steps because "it's obvious".
Why it's wrong: Obvious bugs often have non-obvious triggers. "Doesn't work" could mean 10 different failure modes.
Fix: Always include steps. If truly simple, the steps are quick to write: "1. Open settings 2. Click dark mode toggle 3. Observe no change".
Mistake 3: Public Disclosure of Security Issues
Problem: Creating public issue for vulnerability because user requested it or team needs visibility.
Why it's wrong: Public issues are visible to attackers. Even with security labels, the vulnerability details are exposed.
Fix: Always use private disclosure. GitHub Security Advisories notify the team without exposing details publicly.
Mistake 4: Creating Without Searching
Problem: Creating issue immediately, noting "may be related to existing issues".
Why it's wrong: "May be related" notes do not prevent duplicate confusion. Duplicate issues fragment discussion and waste triage effort.
Fix: Search first. Takes seconds. If found, add context to existing issue instead of creating duplicate.
Mistake 5: Partial Templates Under Pressure
Problem: Filling only title and brief description when user seems rushed.
Why it's wrong: Incomplete issues require follow-up. The time "saved" is spent later on clarification.
Fix: Complete templates prevent thrashing. A complete issue means developers can start immediately.
Quality Validation
Before submitting, verify the issue passes this checklist:
Bug Reports
- Title describes problem, not solution
- Steps to reproduce are numbered and complete
- Expected vs actual behavior clearly stated
- Environment specified
- Severity assessed
- Not a duplicate (searched first)
Feature Requests
- Title describes capability
- User story follows "As a... I want... So that..." format
- Acceptance criteria are numbered and testable
- Scope boundaries defined
- Not a duplicate (searched first)
Security Issues
- NOT created as public issue
- Uses GitHub Security Advisory or private channel
- Impact assessment included
- Remediation suggestions if known
Templates and References
| Resource | Description |
|---|---|
examples/bug-report-template.md |
Bug report template with correct/incorrect examples |
examples/feature-request-template.md |
Feature request template with user story format |
examples/task-template.md |
Task/chore template with definition of done |
examples/security-advisory-template.md |
Private disclosure template (NEVER public) |
references/gh-cli-commands.md |
Complete gh CLI command reference |
Related Skills
- OPTIONAL:
humaninloop:authoring-requirements- Detailed requirements authoring - OPTIONAL:
humaninloop:authoring-user-stories- User story format guidance - OPTIONAL:
humaninloop:validation-task-artifacts- Task validation standards
Converted and distributed by TomeVault — claim your Tome and manage your conversions.