github-issue-creator

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

Current Behavior (for bugs)

Expected Behavior

User Impact

Business/Project Impact

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]

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

Definition of Done

• [ ]
• [ ]
• [ ]

Test Scenarios

1. Scenario:

- Given:

- When:

- Then:

1. Scenario:

- Given:

- When:

- Then:

Edge Cases to Consider

Out of Scope (for this issue)

Related Issues

• Fixes #
• Related to #
• Blocks #

References

Notes

---

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

We need to add a new endpoint POST /api/users/avatar

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

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

• 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

Make the UI better

Better user experience

```

Why it's wrong: "Better" is subjective, not testable.

Better version:

```markdown

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

• 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

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

Add a Redis cache for session data

```

Why it's wrong: Proposes solution without explaining problem.

Better version:

```markdown

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

• Session list loads in under 1 second for 100 sessions
• UI shows loading indicator during fetch
• List remains responsive during load

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

```

Example 1: Bug Report

```markdown

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

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.

• [ ] 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

1. 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

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.

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.

Backward Compatibility

• [ ] Must support existing flat session structure

Data Persistence

• [ ] Folder structure must persist across restarts

• [ ] 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

```

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.