Initial commit
This commit is contained in:
398
skills/github-issues-quick-reference/SKILL.md
Normal file
398
skills/github-issues-quick-reference/SKILL.md
Normal file
@@ -0,0 +1,398 @@
|
||||
---
|
||||
description: Quick reference for GitHub Issues management via gh CLI with priority workflow
|
||||
disable-model-invocation: false
|
||||
---
|
||||
|
||||
# GitHub Issues Quick Reference
|
||||
|
||||
## Overview
|
||||
|
||||
Manage GitHub Issues using the gh CLI with priority-based workflow. All issue operations should use the gh CLI to ensure consistency and proper metadata management.
|
||||
|
||||
**Reference Commands**: Use `/gh-create-issue`, `/gh-close-issue`, `/gh-triage`, `/gh-status-report` for guided workflows.
|
||||
|
||||
---
|
||||
|
||||
## Priority System
|
||||
|
||||
### Three-Tier Priority Labels
|
||||
|
||||
- **P1 (Critical)**: Blocks core functionality, security issues, affects all users, data loss
|
||||
- **P2 (High)**: Significant impact but has workaround, affects some users
|
||||
- **P3 (Normal)**: Standard workflow items, minor bugs, feature requests
|
||||
|
||||
### Setting Up Priority Labels
|
||||
|
||||
```bash
|
||||
gh label create P1 --description "Critical priority - blocks core functionality" --color d73a4a
|
||||
gh label create P2 --description "High priority - significant impact" --color fbca04
|
||||
gh label create P3 --description "Normal priority - standard workflow" --color 0e8a16
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Essential Commands
|
||||
|
||||
### Viewing Issues
|
||||
|
||||
**IMPORTANT**: Use `--json` format for structured, parseable output:
|
||||
|
||||
```bash
|
||||
gh issue view 59 --json title,body,labels,state,number,author,assignees,createdAt,updatedAt
|
||||
```
|
||||
|
||||
**Recommended JSON fields**:
|
||||
- `title` - Issue title
|
||||
- `body` - Full description
|
||||
- `labels` - All labels (including priority)
|
||||
- `state` - OPEN or CLOSED
|
||||
- `number` - Issue number
|
||||
- `author` - Creator
|
||||
- `assignees` - Assigned users
|
||||
- `createdAt` - Creation timestamp
|
||||
- `updatedAt` - Last modified
|
||||
|
||||
**Basic Commands**:
|
||||
|
||||
| Action | Command |
|
||||
|----------------------------|----------------------------------------------|
|
||||
| List all issues | `gh issue list` |
|
||||
| List open issues | `gh issue list --state open` |
|
||||
| Filter by priority | `gh issue list --label P1` |
|
||||
| Filter by assignee | `gh issue list --assignee @me` |
|
||||
| View specific issue | `gh issue view 42 --json title,body,labels,state,number` |
|
||||
| Search issues | `gh issue list --search "keyword"` |
|
||||
|
||||
### Creating Issues
|
||||
|
||||
```bash
|
||||
# Basic issue
|
||||
gh issue create --title "Issue title" --body "Description"
|
||||
|
||||
# With priority and labels
|
||||
gh issue create \
|
||||
--title "Authentication fails" \
|
||||
--body "Users cannot log in with SSO" \
|
||||
--label "P1,bug" \
|
||||
--assignee "@alice"
|
||||
|
||||
# Interactive creation
|
||||
gh issue create
|
||||
```
|
||||
|
||||
### Updating Issues
|
||||
|
||||
| Action | Command |
|
||||
|----------------------------|----------------------------------------------|
|
||||
| Add label | `gh issue edit 42 --add-label "P2"` |
|
||||
| Remove label | `gh issue edit 42 --remove-label "P3"` |
|
||||
| Change title | `gh issue edit 42 --title "New title"` |
|
||||
| Assign to user | `gh issue edit 42 --add-assignee "@bob"` |
|
||||
| Add to milestone | `gh issue edit 42 --milestone "v1.0"` |
|
||||
|
||||
### Comments
|
||||
|
||||
```bash
|
||||
# Add comment (ALWAYS include -cc signature)
|
||||
gh issue comment 42 --body "Update here
|
||||
|
||||
-cc"
|
||||
|
||||
# Add comment with file
|
||||
gh issue comment 42 --body-file comment.md
|
||||
```
|
||||
|
||||
**CRITICAL**: Always end comments with `-cc` signature on its own line.
|
||||
|
||||
### Closing Issues
|
||||
|
||||
```bash
|
||||
# Close with comment
|
||||
gh issue close 42 --comment "Fixed in PR #43
|
||||
|
||||
Tested locally and in staging
|
||||
|
||||
-cc"
|
||||
|
||||
# Close without comment (not recommended)
|
||||
gh issue close 42
|
||||
```
|
||||
|
||||
### Reopening Issues
|
||||
|
||||
```bash
|
||||
gh issue reopen 42 --comment "Issue has resurfaced
|
||||
|
||||
-cc"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Workflow Examples
|
||||
|
||||
### Report a Bug (P1)
|
||||
|
||||
```bash
|
||||
gh issue create \
|
||||
--title "Login fails with SSO for all users" \
|
||||
--body "## Description
|
||||
Users cannot authenticate using SSO since deployment.
|
||||
|
||||
## Steps to Reproduce
|
||||
1. Go to login page
|
||||
2. Click 'Login with SSO'
|
||||
3. Redirected to error page
|
||||
|
||||
## Expected Behavior
|
||||
User should be authenticated and redirected to dashboard
|
||||
|
||||
## Actual Behavior
|
||||
Error: 'Invalid OAuth state'
|
||||
|
||||
## Environment
|
||||
- Production environment
|
||||
- All users affected
|
||||
- Started after deployment at 2pm" \
|
||||
--label "P1,bug"
|
||||
```
|
||||
|
||||
### Create Feature Request (P3)
|
||||
|
||||
```bash
|
||||
gh issue create \
|
||||
--title "Add dark mode to dashboard" \
|
||||
--body "## Feature Description
|
||||
Support dark mode theme in the user dashboard.
|
||||
|
||||
## Problem Statement
|
||||
Users working at night find the bright interface uncomfortable.
|
||||
|
||||
## Proposed Solution
|
||||
Add theme toggle in user settings.
|
||||
|
||||
## Acceptance Criteria
|
||||
- [ ] User can toggle between light and dark mode
|
||||
- [ ] Preference is saved per user
|
||||
- [ ] All dashboard components support dark mode" \
|
||||
--label "P3,enhancement"
|
||||
```
|
||||
|
||||
### Close Fixed Issue
|
||||
|
||||
```bash
|
||||
gh issue close 42 --comment "Fixed by implementing new auth flow in PR #43
|
||||
|
||||
## Changes Made
|
||||
- Updated OAuth state validation
|
||||
- Added session persistence
|
||||
- Improved error handling
|
||||
|
||||
## Testing
|
||||
- Tested locally with all SSO providers
|
||||
- Verified in staging environment
|
||||
- Monitored production for 1 hour post-deployment
|
||||
|
||||
No issues detected.
|
||||
|
||||
-cc"
|
||||
```
|
||||
|
||||
### Triage and Prioritize
|
||||
|
||||
```bash
|
||||
# List unlabeled issues
|
||||
gh issue list --state open
|
||||
|
||||
# View issue details with structured data
|
||||
gh issue view 45 --json title,body,labels,state,number,author,assignees
|
||||
|
||||
# Assign priority after assessment
|
||||
gh issue edit 45 --add-label "P2"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Priority Assessment Guidelines
|
||||
|
||||
### When to Use P1
|
||||
|
||||
- System is down or unusable
|
||||
- Security vulnerabilities discovered
|
||||
- Data loss or corruption occurring
|
||||
- All users blocked from core functionality
|
||||
- Production outage in progress
|
||||
|
||||
### When to Use P2
|
||||
|
||||
- Significant feature broken but workaround exists
|
||||
- Performance severely degraded
|
||||
- Affects substantial subset of users
|
||||
- Important business functionality impaired
|
||||
|
||||
### When to Use P3
|
||||
|
||||
- Minor bugs with minimal impact
|
||||
- UI/UX improvements
|
||||
- Feature requests
|
||||
- Technical debt
|
||||
- Documentation updates
|
||||
- Refactoring tasks
|
||||
|
||||
---
|
||||
|
||||
## Comment Signature
|
||||
|
||||
**CRITICAL RULE**: Every comment you post MUST end with:
|
||||
|
||||
```
|
||||
-cc
|
||||
```
|
||||
|
||||
This signature must be on its own line at the end of every comment. It identifies comments as being written by Claude Code for transparency and accountability.
|
||||
|
||||
Example:
|
||||
```
|
||||
Fixed the authentication issue and deployed to production.
|
||||
|
||||
-cc
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### DO
|
||||
|
||||
- ✅ Always assign priority labels (P1/P2/P3)
|
||||
- ✅ Write descriptive, action-oriented titles
|
||||
- ✅ Include reproduction steps for bugs
|
||||
- ✅ Add acceptance criteria for features
|
||||
- ✅ Link related PRs and commits
|
||||
- ✅ Use the `-cc` signature in all comments
|
||||
- ✅ Update priority if circumstances change
|
||||
|
||||
### DON'T
|
||||
|
||||
- ❌ Create issues without priority labels
|
||||
- ❌ Forget the `-cc` signature in comments
|
||||
- ❌ Use vague titles like "Fix bug"
|
||||
- ❌ Close issues without explaining resolution
|
||||
- ❌ Leave P1 issues unassigned
|
||||
|
||||
---
|
||||
|
||||
## Guided Workflows
|
||||
|
||||
For step-by-step guidance, use these commands:
|
||||
|
||||
| Task | Command |
|
||||
|-----------------------------|----------------------|
|
||||
| Create issue with guidance | `/gh-create-issue` |
|
||||
| Close issue properly | `/gh-close-issue` |
|
||||
| Triage open issues | `/gh-triage` |
|
||||
| Generate status report | `/gh-status-report` |
|
||||
|
||||
---
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Check Status Before Work
|
||||
|
||||
```bash
|
||||
# See what needs attention
|
||||
gh issue list --label P1 --state open
|
||||
|
||||
# Check your assignments
|
||||
gh issue list --assignee @me --state open
|
||||
```
|
||||
|
||||
### After Fixing a Bug
|
||||
|
||||
```bash
|
||||
# Close with summary
|
||||
gh issue close 42 --comment "Fixed in PR #43
|
||||
|
||||
Changes: {summary}
|
||||
Testing: {what was tested}
|
||||
|
||||
-cc"
|
||||
```
|
||||
|
||||
### Weekly Review
|
||||
|
||||
```bash
|
||||
# Generate status report
|
||||
/gh-status-report
|
||||
|
||||
# Or manually:
|
||||
gh issue list --label P1 --state open
|
||||
gh issue list --label P2 --state open
|
||||
gh issue list --state closed --limit 10
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Filters
|
||||
|
||||
```bash
|
||||
# Critical issues
|
||||
gh issue list --label P1 --state open
|
||||
|
||||
# Unassigned issues
|
||||
gh issue list --state open --json number,title,assignees | jq '.[] | select(.assignees == [])'
|
||||
|
||||
# Stale issues (older than 30 days)
|
||||
gh issue list --state open --json number,title,createdAt
|
||||
|
||||
# My issues
|
||||
gh issue list --assignee @me --state open
|
||||
|
||||
# Recent activity
|
||||
gh issue list --state closed --limit 20
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration with Workflow
|
||||
|
||||
### After Code Changes
|
||||
|
||||
1. Search for related issues: `gh issue list --search "keyword"`
|
||||
2. Add update comments with `-cc` signature
|
||||
3. Close issues when resolved
|
||||
4. Create follow-up issues if needed
|
||||
|
||||
### During Planning
|
||||
|
||||
1. Review open issues: `/gh-status-report`
|
||||
2. Triage new issues: `/gh-triage`
|
||||
3. Assign priorities and team members
|
||||
4. Break down large issues into smaller tasks
|
||||
|
||||
### In Standups/Reviews
|
||||
|
||||
1. Filter by assignee to see progress
|
||||
2. Check P1 issues for blockers
|
||||
3. Review recently closed issues
|
||||
4. Update priorities based on new information
|
||||
|
||||
---
|
||||
|
||||
## Golden Rules
|
||||
|
||||
1. **Always assign priority** (P1/P2/P3) when creating or triaging issues
|
||||
2. **Always use `-cc` signature** in comments
|
||||
3. **Be descriptive** in titles and descriptions
|
||||
4. **Link related items** (PRs, commits, other issues)
|
||||
5. **Document resolutions** when closing issues
|
||||
6. **Use guided commands** for complex workflows
|
||||
|
||||
---
|
||||
|
||||
## Full Documentation
|
||||
|
||||
For complete documentation and advanced features:
|
||||
- Use `/gh-create-issue` for guided issue creation
|
||||
- Use `/gh-close-issue` for guided issue closure
|
||||
- Use `/gh-triage` for priority management
|
||||
- Use `/gh-status-report` for comprehensive reporting
|
||||
578
skills/issue-templates/SKILL.md
Normal file
578
skills/issue-templates/SKILL.md
Normal file
@@ -0,0 +1,578 @@
|
||||
---
|
||||
description: Templates for creating well-structured GitHub issues for bugs, features, and tasks
|
||||
disable-model-invocation: false
|
||||
---
|
||||
|
||||
# GitHub Issue Templates
|
||||
|
||||
Comprehensive templates for creating different types of GitHub issues. Use these templates to ensure consistency and completeness when creating issues.
|
||||
|
||||
---
|
||||
|
||||
## Bug Report Template
|
||||
|
||||
Use this template when reporting bugs, errors, or unexpected behavior.
|
||||
|
||||
```markdown
|
||||
## Description
|
||||
|
||||
Brief, clear description of the bug in 1-2 sentences.
|
||||
|
||||
## Steps to Reproduce
|
||||
|
||||
1. Go to [specific page or action]
|
||||
2. Click on [button/link]
|
||||
3. Enter [specific data]
|
||||
4. Observe the error
|
||||
|
||||
## Expected Behavior
|
||||
|
||||
What should happen when following the steps above.
|
||||
|
||||
## Actual Behavior
|
||||
|
||||
What actually happens. Include error messages, stack traces, or screenshots.
|
||||
|
||||
## Environment
|
||||
|
||||
- **Browser/OS**: Chrome 120 / macOS 14.2
|
||||
- **Version/Branch**: v2.1.0 / main
|
||||
- **Environment**: Production / Staging / Local
|
||||
|
||||
## Reproduction Rate
|
||||
|
||||
- [ ] Always (100%)
|
||||
- [ ] Frequently (>50%)
|
||||
- [ ] Sometimes (<50%)
|
||||
- [ ] Rare (<10%)
|
||||
|
||||
## Screenshots/Logs
|
||||
|
||||
[Attach screenshots, error logs, or console output if applicable]
|
||||
|
||||
## Additional Context
|
||||
|
||||
- When did this start happening?
|
||||
- Does it affect all users or specific users?
|
||||
- Any recent changes that might be related?
|
||||
- Workarounds discovered?
|
||||
|
||||
## Impact Assessment
|
||||
|
||||
- **Users Affected**: All / Subset / Single user
|
||||
- **Severity**: Critical / High / Medium / Low
|
||||
- **Business Impact**: [Describe impact on business operations]
|
||||
|
||||
## Suggested Priority
|
||||
|
||||
- [ ] P1 - Critical (blocks core functionality, affects all users)
|
||||
- [ ] P2 - High (significant impact but has workaround)
|
||||
- [ ] P3 - Normal (minor impact, can be scheduled)
|
||||
```
|
||||
|
||||
### Example Bug Report
|
||||
|
||||
```markdown
|
||||
## Description
|
||||
|
||||
Users cannot log in with SSO authentication, receiving "Invalid OAuth state" error.
|
||||
|
||||
## Steps to Reproduce
|
||||
|
||||
1. Navigate to https://app.example.com/login
|
||||
2. Click "Login with SSO"
|
||||
3. Enter corporate email
|
||||
4. Redirected to error page with "Invalid OAuth state"
|
||||
|
||||
## Expected Behavior
|
||||
|
||||
User should be authenticated and redirected to dashboard.
|
||||
|
||||
## Actual Behavior
|
||||
|
||||
Error page displays "Invalid OAuth state parameter" and user cannot proceed.
|
||||
|
||||
## Environment
|
||||
|
||||
- **Browser/OS**: All browsers / All OS
|
||||
- **Version/Branch**: v2.3.1 / production
|
||||
- **Environment**: Production
|
||||
|
||||
## Reproduction Rate
|
||||
|
||||
- [x] Always (100%)
|
||||
|
||||
## Screenshots/Logs
|
||||
|
||||
```
|
||||
Error: OAuth state mismatch
|
||||
at validateState (auth.js:45)
|
||||
at processCallback (oauth.js:123)
|
||||
```
|
||||
|
||||
## Additional Context
|
||||
|
||||
- Started after deployment at 2:00 PM UTC today
|
||||
- Affects ALL users attempting SSO login
|
||||
- Username/password login still works
|
||||
- Related to PR #123 which updated OAuth library
|
||||
|
||||
## Impact Assessment
|
||||
|
||||
- **Users Affected**: All SSO users (~80% of user base)
|
||||
- **Severity**: Critical
|
||||
- **Business Impact**: Users cannot access application, blocking all work
|
||||
|
||||
## Suggested Priority
|
||||
|
||||
- [x] P1 - Critical (blocks core functionality, affects all users)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Feature Request Template
|
||||
|
||||
Use this template when proposing new features or enhancements.
|
||||
|
||||
```markdown
|
||||
## Feature Description
|
||||
|
||||
Clear, concise description of the proposed feature in 1-2 sentences.
|
||||
|
||||
## Problem Statement
|
||||
|
||||
What problem does this feature solve? Who experiences this problem?
|
||||
|
||||
## Proposed Solution
|
||||
|
||||
Detailed description of how the feature should work:
|
||||
|
||||
- User interaction flow
|
||||
- UI/UX considerations
|
||||
- Technical approach (high-level)
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] User can [specific action]
|
||||
- [ ] System responds with [expected behavior]
|
||||
- [ ] Edge case [X] is handled properly
|
||||
- [ ] Feature works on [platforms/browsers]
|
||||
|
||||
## User Stories
|
||||
|
||||
**As a** [type of user]
|
||||
**I want** [goal/desire]
|
||||
**So that** [benefit/value]
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
What other approaches were considered and why were they rejected?
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Requires [feature/component]
|
||||
- Blocks [other feature]
|
||||
- Depends on [external service/library]
|
||||
|
||||
## Success Metrics
|
||||
|
||||
How will we measure if this feature is successful?
|
||||
|
||||
- [ ] [Metric 1]
|
||||
- [ ] [Metric 2]
|
||||
|
||||
## Priority Suggestion
|
||||
|
||||
- [ ] P1 - Critical (essential for launch/key business need)
|
||||
- [ ] P2 - High (important enhancement with clear value)
|
||||
- [ ] P3 - Normal (nice-to-have improvement)
|
||||
|
||||
## Additional Context
|
||||
|
||||
- Mockups or wireframes
|
||||
- User research or feedback
|
||||
- Competitive analysis
|
||||
- Technical considerations
|
||||
```
|
||||
|
||||
### Example Feature Request
|
||||
|
||||
```markdown
|
||||
## Feature Description
|
||||
|
||||
Add dark mode theme option to the application dashboard and user interface.
|
||||
|
||||
## Problem Statement
|
||||
|
||||
Users working in low-light environments or during evening hours find the bright interface uncomfortable and experience eye strain. Multiple users have requested a dark mode option in feedback surveys.
|
||||
|
||||
## Proposed Solution
|
||||
|
||||
Implement a theme toggle in user settings:
|
||||
|
||||
1. Add theme selector in user preferences (Settings > Appearance)
|
||||
2. Offer "Light", "Dark", and "Auto (system)" options
|
||||
3. Persist user preference to database
|
||||
4. Apply theme across all dashboard components
|
||||
5. Use CSS variables for easy theme switching
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] User can toggle between light and dark mode in settings
|
||||
- [ ] User can select "Auto" to follow system theme
|
||||
- [ ] Theme preference is saved per user account
|
||||
- [ ] Theme persists across sessions and devices
|
||||
- [ ] All dashboard components support both themes
|
||||
- [ ] Text remains readable in both themes (WCAG AA contrast)
|
||||
- [ ] Theme applies immediately without page refresh
|
||||
|
||||
## User Stories
|
||||
|
||||
**As a** dashboard user
|
||||
**I want** to switch to dark mode
|
||||
**So that** I can work comfortably in low-light environments without eye strain
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
1. **Single dark mode only**: Rejected - some users prefer light mode
|
||||
2. **Browser extension**: Rejected - requires external dependency
|
||||
3. **Time-based auto-switch**: Rejected - too complex for MVP
|
||||
|
||||
## Dependencies
|
||||
|
||||
- CSS variable system (already implemented)
|
||||
- User preferences API (needs enhancement)
|
||||
- Component library updates (all components must support theming)
|
||||
|
||||
## Success Metrics
|
||||
|
||||
- [ ] 30%+ of users enable dark mode within first month
|
||||
- [ ] Reduced complaints about interface brightness
|
||||
- [ ] Positive feedback in user surveys
|
||||
|
||||
## Priority Suggestion
|
||||
|
||||
- [ ] P1 - Critical
|
||||
- [x] P2 - High (frequently requested feature with clear user value)
|
||||
- [ ] P3 - Normal
|
||||
|
||||
## Additional Context
|
||||
|
||||
- Figma mockups: [link]
|
||||
- User survey results: 67% requested dark mode
|
||||
- Similar feature in competitor products
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task Template
|
||||
|
||||
Use this template for development tasks, technical work, or non-user-facing improvements.
|
||||
|
||||
```markdown
|
||||
## Objective
|
||||
|
||||
What needs to be accomplished? Be specific and actionable.
|
||||
|
||||
## Context
|
||||
|
||||
Why is this task needed? What's the background or motivation?
|
||||
|
||||
## Requirements
|
||||
|
||||
Detailed list of what must be completed:
|
||||
|
||||
- [ ] Requirement 1
|
||||
- [ ] Requirement 2
|
||||
- [ ] Requirement 3
|
||||
|
||||
## Technical Approach
|
||||
|
||||
High-level technical plan or considerations:
|
||||
|
||||
1. [Step or component 1]
|
||||
2. [Step or component 2]
|
||||
3. [Step or component 3]
|
||||
|
||||
## Files/Components Affected
|
||||
|
||||
- `path/to/file1.js`
|
||||
- `path/to/file2.py`
|
||||
- `component/Module`
|
||||
|
||||
## Testing Requirements
|
||||
|
||||
- [ ] Unit tests for [component]
|
||||
- [ ] Integration tests for [workflow]
|
||||
- [ ] Manual testing of [scenario]
|
||||
- [ ] Performance testing if applicable
|
||||
|
||||
## Documentation Requirements
|
||||
|
||||
- [ ] Update README
|
||||
- [ ] Update API docs
|
||||
- [ ] Add inline code comments
|
||||
- [ ] Update changelog
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Requires completion of #[issue-number]
|
||||
- Blocked by [external factor]
|
||||
- Depends on [library/service]
|
||||
|
||||
## Definition of Done
|
||||
|
||||
- [ ] Implementation complete and tested
|
||||
- [ ] Code reviewed and approved
|
||||
- [ ] Tests added and passing
|
||||
- [ ] Documentation updated
|
||||
- [ ] No regressions introduced
|
||||
- [ ] Deployed to staging/production
|
||||
|
||||
## Priority
|
||||
|
||||
- [ ] P1 - Critical (blocking other work)
|
||||
- [ ] P2 - High (important technical improvement)
|
||||
- [ ] P3 - Normal (standard development work)
|
||||
|
||||
## Estimated Effort
|
||||
|
||||
[Small / Medium / Large] or [hours/days estimate]
|
||||
```
|
||||
|
||||
### Example Task
|
||||
|
||||
```markdown
|
||||
## Objective
|
||||
|
||||
Refactor authentication middleware to support multiple OAuth providers (GitHub, Google, Microsoft).
|
||||
|
||||
## Context
|
||||
|
||||
Currently auth middleware only supports GitHub OAuth. New enterprise customers require Google and Microsoft SSO support. The existing implementation is tightly coupled to GitHub, making it difficult to extend.
|
||||
|
||||
## Requirements
|
||||
|
||||
- [ ] Abstract OAuth provider interface
|
||||
- [ ] Implement provider-specific adapters for GitHub, Google, Microsoft
|
||||
- [ ] Update configuration to support multiple providers
|
||||
- [ ] Maintain backward compatibility with existing GitHub auth
|
||||
- [ ] Add provider selection to login UI
|
||||
|
||||
## Technical Approach
|
||||
|
||||
1. Create `OAuthProvider` interface with standard methods
|
||||
2. Extract GitHub-specific code into `GitHubProvider` adapter
|
||||
3. Implement `GoogleProvider` and `MicrosoftProvider` adapters
|
||||
4. Update middleware to route to appropriate provider based on config
|
||||
5. Add provider selection dropdown to login page
|
||||
6. Update user model to store provider type
|
||||
|
||||
## Files/Components Affected
|
||||
|
||||
- `src/middleware/auth.js` - Main refactoring
|
||||
- `src/providers/github.js` - New file
|
||||
- `src/providers/google.js` - New file
|
||||
- `src/providers/microsoft.js` - New file
|
||||
- `src/config/oauth.js` - Configuration updates
|
||||
- `src/components/LoginForm.jsx` - UI updates
|
||||
- `src/models/User.js` - Schema updates
|
||||
|
||||
## Testing Requirements
|
||||
|
||||
- [ ] Unit tests for each provider adapter
|
||||
- [ ] Integration tests for full auth flow with each provider
|
||||
- [ ] Test backward compatibility with existing GitHub users
|
||||
- [ ] Test provider switching for users
|
||||
- [ ] Manual testing of UI provider selection
|
||||
|
||||
## Documentation Requirements
|
||||
|
||||
- [ ] Update README with OAuth configuration examples
|
||||
- [ ] Document provider interface in code
|
||||
- [ ] Add setup guide for each OAuth provider
|
||||
- [ ] Update environment variable documentation
|
||||
|
||||
## Dependencies
|
||||
|
||||
- OAuth credentials for Google and Microsoft (in progress)
|
||||
- No blocking dependencies
|
||||
|
||||
## Definition of Done
|
||||
|
||||
- [ ] All three providers implemented and tested
|
||||
- [ ] Existing GitHub auth continues to work
|
||||
- [ ] Tests added for all providers (100% coverage)
|
||||
- [ ] Code reviewed and approved
|
||||
- [ ] Documentation complete
|
||||
- [ ] Deployed to staging for QA testing
|
||||
- [ ] No performance regressions
|
||||
|
||||
## Priority
|
||||
|
||||
- [ ] P1 - Critical
|
||||
- [x] P2 - High (important for enterprise customer contracts)
|
||||
- [ ] P3 - Normal
|
||||
|
||||
## Estimated Effort
|
||||
|
||||
Large (3-5 days)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Documentation Update Template
|
||||
|
||||
Use this template for documentation improvements or additions.
|
||||
|
||||
```markdown
|
||||
## Documentation Need
|
||||
|
||||
What documentation is missing or needs improvement?
|
||||
|
||||
## Target Audience
|
||||
|
||||
Who will use this documentation?
|
||||
- [ ] End users
|
||||
- [ ] Developers
|
||||
- [ ] DevOps/Operations
|
||||
- [ ] Contributors
|
||||
|
||||
## Scope
|
||||
|
||||
What should be documented:
|
||||
|
||||
- [ ] Topic 1
|
||||
- [ ] Topic 2
|
||||
- [ ] Topic 3
|
||||
|
||||
## Existing Documentation
|
||||
|
||||
What documentation already exists that relates to this?
|
||||
|
||||
## Proposed Changes
|
||||
|
||||
What should be added, updated, or removed:
|
||||
|
||||
1. [Change 1]
|
||||
2. [Change 2]
|
||||
3. [Change 3]
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] Documentation is clear and accurate
|
||||
- [ ] Examples are provided
|
||||
- [ ] Common issues are addressed
|
||||
- [ ] Links are functional
|
||||
|
||||
## Priority
|
||||
|
||||
- [ ] P1 - Critical (blocking users/developers)
|
||||
- [ ] P2 - High (frequently needed info)
|
||||
- [ ] P3 - Normal (nice-to-have)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Command to Create Issue
|
||||
|
||||
Use these commands with the templates above:
|
||||
|
||||
```bash
|
||||
# Interactive issue creation (will prompt for all fields)
|
||||
gh issue create
|
||||
|
||||
# Create from template (save template to file first)
|
||||
gh issue create --body-file bug-report.md --title "Issue title" --label "P1,bug"
|
||||
|
||||
# Quick bug report
|
||||
gh issue create \
|
||||
--title "Brief bug description" \
|
||||
--body "$(cat <<'EOF'
|
||||
## Description
|
||||
[Bug description]
|
||||
|
||||
## Steps to Reproduce
|
||||
1. Step 1
|
||||
2. Step 2
|
||||
|
||||
## Expected vs Actual
|
||||
Expected: [...]
|
||||
Actual: [...]
|
||||
EOF
|
||||
)" \
|
||||
--label "P1,bug"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Template Selection Guide
|
||||
|
||||
| Issue Type | Template to Use | Labels to Add |
|
||||
|--------------------------|--------------------------|----------------------|
|
||||
| Bug or error | Bug Report | `bug`, `P1/P2/P3` |
|
||||
| New feature | Feature Request | `enhancement`, `P2/P3` |
|
||||
| Technical work | Task | `task`, `P2/P3` |
|
||||
| Performance issue | Bug Report | `bug`, `performance` |
|
||||
| Security vulnerability | Bug Report (urgent) | `security`, `P1` |
|
||||
| Documentation gap | Documentation Update | `documentation`, `P3` |
|
||||
| Refactoring | Task | `refactor`, `P3` |
|
||||
| Technical debt | Task | `tech-debt`, `P3` |
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### When Creating Issues
|
||||
|
||||
1. **Choose the right template** for the issue type
|
||||
2. **Fill in all sections** - don't leave blanks
|
||||
3. **Be specific and actionable** in descriptions
|
||||
4. **Assign priority** based on impact and urgency
|
||||
5. **Add relevant labels** beyond just priority
|
||||
6. **Link related issues** and PRs
|
||||
7. **Include reproduction steps** for bugs
|
||||
8. **Define acceptance criteria** for features
|
||||
|
||||
### Template Customization
|
||||
|
||||
These templates can be customized per repository:
|
||||
- Save templates to `.github/ISSUE_TEMPLATE/` directory
|
||||
- GitHub will show them in the issue creation UI
|
||||
- Customize sections based on team needs
|
||||
- Add repository-specific fields
|
||||
|
||||
---
|
||||
|
||||
## Using Templates with Guided Commands
|
||||
|
||||
The `/gh-create-issue` command will help you use these templates interactively:
|
||||
|
||||
```bash
|
||||
# Use guided workflow
|
||||
/gh-create-issue
|
||||
|
||||
# The command will:
|
||||
# 1. Ask for issue type (bug/feature/task)
|
||||
# 2. Load appropriate template
|
||||
# 3. Guide you through filling it out
|
||||
# 4. Create the issue with proper labels and priority
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Golden Rules
|
||||
|
||||
1. **Always use a template** - ensures completeness
|
||||
2. **Always assign priority** - P1/P2/P3
|
||||
3. **Be thorough** - complete all sections
|
||||
4. **Be specific** - actionable details
|
||||
5. **Think about the reader** - they may have no context
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- Use `github-issues-quick-reference` skill for gh CLI commands
|
||||
- Use `/gh-create-issue` for guided issue creation
|
||||
- Use `/gh-triage` for prioritizing existing issues
|
||||
Reference in New Issue
Block a user