# Github Issue Creator > Create well-structured GitHub issues focused on user problems and outcomes, not implementation. Use when user reports bugs or requests features to ensure clear, testable requirements without premature implementation details. - Skill: `edanstarfire/github-issue-creator` (Agent Skill) - Install (CLI): `npx skillmds@latest add edanstarfire/github-issue-creator` - Raw SKILL.md: https://api.skillmd.com/api/skills/edanstarfire/github-issue-creator/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: EdanStarfire (https://skillmd.com/u/edanstarfire) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/edanstarfire/github-issue-creator --- # GitHub Issue Creator ## Instructions ### When to Invoke This Skill - User reports a bug or problem - User requests a new feature - User suggests quality of life improvement - Need to document user need before implementation - Converting vague request into clear issue ### Core Principle **Issues describe WHAT and WHY, not HOW.** Issues are contracts between user needs and development outcomes. They should enable: - Clear understanding of the problem/need - Objective evaluation of completeness - Testing whether solution succeeds - Flexibility in implementation approach **Separate concerns:** - **Issue** = User problem, expected outcome, acceptance criteria - **Implementation Plan** = Technical approach (comes later, in comments or design docs) - **PR Description** = What was actually implemented - **Code Comments** = Why specific code decisions were made ### Issue Structure #### Template ```markdown ## Problem / Need ### Current Behavior (for bugs) ### Expected Behavior ## Impact ### User Impact ### Business/Project Impact ## User Perspective ### User Story (optional but recommended) As a [type of user] I want to [action/capability] So that [benefit/outcome] ### User Journey 1. User does X 2. [Current: System does Y / Expected: System should do Z] 3. User experiences [problem/benefit] ## Quality Standards ### Backward Compatibility - [ ] Must not break existing functionality - [ ] Can break existing functionality (explain why) - [ ] New feature (no compatibility concern) ### Data Persistence - [ ] Changes must persist across restarts - [ ] Changes must persist across sessions - [ ] Transient state (no persistence needed) ### Performance - [ ] No performance requirements - [ ] Must complete within [time] - [ ] Must handle [scale] concurrent users/operations ### Security - [ ] No security implications - [ ] Requires authentication/authorization - [ ] Handles sensitive data ## Acceptance Criteria ### Definition of Done - [ ] - [ ] - [ ] ### Test Scenarios 1. **Scenario:** - **Given:** - **When:** - **Then:** 2. **Scenario:** - **Given:** - **When:** - **Then:** ### Edge Cases to Consider - - ### Out of Scope (for this issue) - - ## Additional Context ### Related Issues - Fixes # - Related to # - Blocks # ### References - - - ### Notes --- ## ⚠️ Implementation Details **Implementation planning happens AFTER issue is approved.** Once this issue is accepted: 1. Create implementation plan in comments or design doc 2. Break down into technical tasks 3. Identify files/functions to modify 4. Plan testing approach 5. Execute implementation **Do NOT include in initial issue:** - Specific files to modify - Specific function names - Exact variable names - Detailed code structure - UI mockups (unless critical to understanding the need) ``` ### Conversation Flow to Create Issue #### 1. Extract User Need **Ask clarifying questions:** - What are you trying to accomplish? - What happens currently? - What should happen instead? - Who is affected by this? - Why is this important? **Avoid asking:** - How should we implement this? (too early) - Which files should we change? (not user concern) - What should we name variables? (implementation detail) #### 2. Understand Impact **Explore:** - How often does this happen? - How severe is the impact? - Who experiences this? - What's the workaround (if any)? - What happens if we don't fix this? #### 3. Define Expected Behavior **Focus on observable outcomes:** - ✅ "User should see error message explaining what went wrong" - ❌ "Display error in a red div with class 'error-message'" - ✅ "Data should persist across browser sessions" - ❌ "Store data in localStorage using JSON.stringify()" - ✅ "Response time should be under 2 seconds" - ❌ "Implement caching using Redis" #### 4. Establish Acceptance Criteria **Use Given-When-Then format:** ``` Given: When: Then: ``` **Make criteria testable:** - ✅ "Submit button is disabled when form is invalid" - ❌ "Form validation should work properly" - ✅ "Clicking 'Delete' shows confirmation dialog before deletion" - ❌ "Add confirmation for delete" #### 5. Identify Quality Standards **Ask about:** - Can this break existing features? - Does data need to persist? - Are there performance requirements? - Are there security concerns? #### 6. Clarify Scope **What's included:** - Core functionality needed **What's excluded (out of scope):** - Nice-to-haves for future - Related but separate features - Edge cases that can wait ### Issue Quality Checklist Before creating the issue, verify: **Problem/Need is Clear:** - [ ] Anyone can understand what's wrong or needed - [ ] Current vs expected behavior is obvious - [ ] Context is sufficient **Impact is Explained:** - [ ] Who is affected - [ ] Why it matters - [ ] Severity/priority is justified **User Perspective is Maintained:** - [ ] Written from user's viewpoint - [ ] Focuses on outcomes, not internals - [ ] Describes behavior, not code **Acceptance Criteria are Testable:** - [ ] Each criterion is objective - [ ] Can verify each with test - [ ] No ambiguous terms ("better", "improved", "nice") **Quality Standards are Defined:** - [ ] Backward compatibility addressed - [ ] Data persistence specified - [ ] Performance needs stated (if any) **Implementation Details are Absent:** - [ ] No specific file names - [ ] No function/class names - [ ] No UI mockups (unless essential) - [ ] No technical architecture **Scope is Bounded:** - [ ] Focus is narrow enough - [ ] Out of scope is documented - [ ] Related issues are linked ### Creating the Issue **Command:** ```bash gh issue create --title ": " --body "$(cat <<'EOF' EOF )" ``` **Title Format:** - `feat: ` - `fix: ` - `chore: ` - `docs: ` - `perf: ` **Title Guidelines:** - Brief (50 chars or less) - User-focused ("Add dark mode toggle") - Not implementation-focused ("Refactor CSS variables") - Descriptive without being technical ### Common Anti-Patterns to Avoid #### ❌ Anti-Pattern 1: Implementation in Disguise ```markdown ## Problem We need to add a new endpoint POST /api/users/avatar ## Solution 1. Add route in web_server.py 2. Create upload handler in storage.py 3. Update User model with avatar_url field ``` **Why it's wrong:** This is an implementation plan, not a user need. **Better version:** ```markdown ## Problem Users cannot upload profile avatars ### Current Behavior User profiles display only default avatar ### Expected Behavior Users can upload custom avatar image that displays on their profile ## Acceptance Criteria - User can select image file from device - Uploaded avatar displays immediately - Avatar persists across sessions - Avatar size is limited to 2MB ``` #### ❌ Anti-Pattern 2: Vague Requirements ```markdown ## Problem Make the UI better ## Expected Better user experience ``` **Why it's wrong:** "Better" is subjective, not testable. **Better version:** ```markdown ## Problem Users struggle to find the delete button for sessions ### Current Behavior Delete button only appears on hover and users miss it ### Expected Behavior Delete button should be visible at all times for easy access ### User Impact Users accidentally accumulate old sessions, cluttering their workspace ## Acceptance Criteria - Delete button is visible without hover - Button placement is consistent across all session items - Button has clear "Delete" label or icon ``` #### ❌ Anti-Pattern 3: Mixed Concerns ```markdown ## Feature Request Add dark mode and refactor CSS to use variables and update documentation and add unit tests for theme switching ``` **Why it's wrong:** Multiple separate concerns bundled together. **Better version:** Create separate issues: 1. `feat: Add dark mode toggle for user interface` 2. `chore: Update UI documentation for theming` 3. (CSS refactoring happens during implementation, not separate issue) 4. (Tests are part of acceptance criteria, not separate issue) #### ❌ Anti-Pattern 4: Solution Instead of Problem ```markdown ## Feature Request Add a Redis cache for session data ``` **Why it's wrong:** Proposes solution without explaining problem. **Better version:** ```markdown ## Problem Session list takes 5+ seconds to load when user has 100+ sessions ### Current Behavior Every page load fetches all session data from disk Page is unresponsive during loading ### User Impact Users with many sessions experience slow, frustrating interface Unable to work efficiently ## Acceptance Criteria - Session list loads in under 1 second for 100 sessions - UI shows loading indicator during fetch - List remains responsive during load ## Performance Requirement Support up to 500 sessions per user with sub-2-second load times --- Note: Redis, caching, pagination, or other solutions can be explored during implementation planning ``` ## Examples ### Example 1: Bug Report ```markdown ## Problem WebSocket connection fails to reconnect after network interruption ### Current Behavior When user's network connection drops (WiFi disconnect, laptop sleep): - WebSocket connection is lost - Messages stop flowing - UI shows "connected" status incorrectly - User must refresh page to reconnect ### Expected Behavior When network connection is restored: - WebSocket automatically reconnects - UI shows "reconnecting" status - Messages resume flowing - No page refresh required ## Impact ### User Impact Users lose work when network drops and don't realize connection is broken. Must manually refresh and potentially lose unsent messages. ### Frequency Common for laptop users who move between locations or close laptop lid. ## Acceptance Criteria - [ ] Connection automatically reconnects when network restored - [ ] UI accurately reflects connection state (connected/reconnecting/disconnected) - [ ] Unsent messages are queued and sent after reconnection - [ ] No data loss during reconnection ### Test Scenarios 1. **Scenario:** Network interruption during active session - **Given:** User has active session with WebSocket connected - **When:** Network disconnects then reconnects after 10 seconds - **Then:** WebSocket reconnects automatically, queued messages sent 2. **Scenario:** Laptop sleep/wake cycle - **Given:** User has active session - **When:** User closes laptop lid then reopens after 1 hour - **Then:** WebSocket reconnects, session resumes without refresh ``` ### Example 2: Feature Request ```markdown ## Problem / Need Users cannot organize sessions into folders or categories ### Current Situation All sessions appear in flat list within project. Users with 20+ sessions struggle to find specific session. ## Impact ### User Impact Users waste time scrolling through long session lists. No way to separate active vs archived sessions. ### User Story As a developer managing multiple features, I want to organize sessions into folders, So that I can quickly find sessions related to specific work areas. ## Quality Standards ### Backward Compatibility - [ ] Must support existing flat session structure ### Data Persistence - [ ] Folder structure must persist across restarts ## Acceptance Criteria - [ ] Users can create named folders within projects - [ ] Users can move sessions between folders - [ ] Users can rename folders - [ ] Users can delete empty folders - [ ] Folder structure persists across browser sessions ### Out of Scope - Folder-level settings (separate feature) - Sharing folders between projects ``` ## Summary This skill creates issues that clearly describe user problems and expected outcomes without constraining implementation approach, enabling flexible technical solutions while maintaining clear success criteria.