Initial commit

This commit is contained in:
Zhongwei Li
2025-11-30 09:07:55 +08:00
commit e04084c903
11 changed files with 1597 additions and 0 deletions

View 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

View 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