Initial commit

2025-11-30 09:07:01 +08:00
commit bc6aaa6d91
5 changed files with 296 additions and 0 deletions
--- a/skills/jira-cli/reference/jira-cli-reference.md
+++ b/skills/jira-cli/reference/jira-cli-reference.md
@@ -0,0 +1,185 @@
+# jira-cli Detailed Reference
+
+**Assumptions:** Already installed/configured, `JIRA_API_TOKEN` set, `jira init` complete
+
+**Project flag:** Always use `-p PROJ` to specify project explicitly (don't rely on defaults)
+
+---
+
+# Core Workflow: Working on Issue
+
+```bash
+# User: "Work on PROJ-123"
+jira issue view -p PROJ PROJ-123                          # Read requirements
+jira issue assign PROJ-123 $(jira me)                     # Assign to user
+jira issue move PROJ-123 "In Progress"                    # Update status
+# ... implement code ...
+jira issue comment add PROJ-123 "Fixed in $(git rev-parse --short HEAD)"
+jira issue move PROJ-123 "Done"                           # Close
+```
+
+---
+
+# Command Syntax by Intent
+
+## Query Issues
+
+**By filters:**
+```bash
+jira issue list -p PROJ -tBug -aCurrentUser -s"To Do"     # Type, assignee, status
+jira issue list -p PROJ -yHigh -lbackend --created week   # Priority, label, date
+```
+
+**By JQL (complex queries):**
+```bash
+jira issue list -p PROJ --jql 'assignee=currentUser() AND status!="Done"'
+jira issue list -p PROJ --jql 'priority IN (High,Critical) AND created >= -7d'
+```
+
+**Common patterns:**
+- My bugs: `jira issue list -p PROJ -tBug -aCurrentUser`
+- High priority work: `jira issue list -p PROJ -yHigh -s"To Do"`
+- Recent activity: `jira issue list -p PROJ -aCurrentUser --updated -1d`
+
+## View Issue
+
+```bash
+jira issue view -p PROJ PROJ-123                          # Basic view
+jira issue view -p PROJ PROJ-123 --comments 50            # With comments
+jira issue view -p PROJ PROJ-123 --raw                    # JSON output
+jira open PROJ-123                                        # Open in browser
+```
+
+## Create Issue
+
+```bash
+jira issue create -p PROJ -tBug -s"Summary" -yHigh -lbackend
+jira issue create -p PROJ -tStory -s"Feature name"
+```
+
+## Update Issue
+
+```bash
+jira issue assign PROJ-123 $(jira me)                     # Assign to self
+jira issue assign PROJ-123 "user@example.com"             # Assign to user
+jira issue move PROJ-123 "In Progress"                    # Change status
+jira issue comment add PROJ-123 "Comment text"            # Add comment
+jira issue edit -p PROJ PROJ-123 -yHigh -lurgent          # Edit priority/labels
+```
+
+---
+
+# Efficient Data Extraction
+
+**Principle:** Extract only needed fields to minimize context.
+
+```bash
+# Get single field via jq
+jira issue view -p PROJ PROJ-123 --raw | jq -r '.fields.status.name'
+jira issue view -p PROJ PROJ-123 --raw | jq -r '.fields.assignee.displayName'
+
+# Get specific columns only
+jira issue list -p PROJ --plain --no-headers --columns KEY
+jira issue list -p PROJ --plain --columns KEY,STATUS,ASSIGNEE
+
+# Check existence
+jira issue view -p PROJ PROJ-123 --plain > /dev/null 2>&1 && echo "exists"
+```
+
+---
+
+# JQL Reference
+
+**Structure:** `jira issue list -p PROJ --jql 'FIELD OPERATOR VALUE'`
+
+**Operators:** `=`, `!=`, `IN`, `>`, `<`, `>=`, `<=`
+
+**Functions:**
+- `currentUser()` - Current logged-in user
+- `openSprints()` - Active sprints
+- `startOfWeek()`, `startOfDay()` - Date functions
+
+**Date formats:**
+- Relative: `-7d`, `-2w`, `-1m`
+- Absolute: `"2023-12-01"`
+
+**Examples:**
+```bash
+# Multiple conditions
+jira issue list -p PROJ --jql 'project=PROJ AND assignee=currentUser() AND status!="Done"'
+
+# Date ranges
+jira issue list -p PROJ --jql 'created >= -7d AND updated >= startOfWeek()'
+
+# IN operator
+jira issue list -p PROJ --jql 'status IN ("To Do","In Progress")'
+```
+
+---
+
+# Output Formats
+
+**For display:** Default table format
+**For parsing:** `--plain --no-headers --columns KEY`
+**For extraction:** `--raw` with `jq`
+
+```bash
+# Table (default)
+jira issue list -p PROJ
+
+# Plain text for parsing
+jira issue list -p PROJ --plain --no-headers --columns KEY
+
+# JSON for field extraction
+jira issue view -p PROJ PROJ-123 --raw | jq -r '.fields.summary'
+```
+
+---
+
+# Filter Flags Reference
+
+| Flag | Purpose | Example |
+|------|---------|---------|
+| `-t` | Type | `-tBug`, `-tStory`, `-tTask` |
+| `-s` | Status | `-s"To Do"`, `-s"In Progress"` |
+| `-y` | Priority | `-yHigh`, `-yMedium`, `-yLow` |
+| `-a` | Assignee | `-aCurrentUser`, `-a"user@example.com"` |
+| `-l` | Label | `-lbackend`, `-lurgent,critical` |
+| `--created` | Created date | `--created today`, `--created week`, `--created 2023-12-01` |
+| `--updated` | Updated date | `--updated -7d` |
+| `--jql` | Raw JQL query | `--jql 'custom query'` |
+
+---
+
+# User Intent → Command Mapping
+
+| User Says | Command |
+|-----------|---------|
+| "Work on PROJ-123" | `jira issue view -p PROJ PROJ-123` |
+| "What bugs do I have?" | `jira issue list -p PROJ -tBug -aCurrentUser` |
+| "What should I work on?" | `jira issue list -p PROJ -yHigh -s"To Do"` |
+| "Create bug for X" | `jira issue create -p PROJ -tBug -s"X"` |
+| "Close PROJ-123" | `jira issue move PROJ-123 "Done"` |
+| "Add comment to PROJ-123" | `jira issue comment add PROJ-123 "text"` |
+| "What did I work on yesterday?" | `jira issue list -p PROJ -aCurrentUser --updated -1d` |
+
+---
+
+# Best Practices
+
+1. **Always specify project:** Use `-p PROJ` flag explicitly
+2. **Extract minimal data:** Use `--raw | jq` for specific fields instead of reading full issue
+3. **Filter before reading:** Narrow with queries, then read details
+4. **Use plain output for scripts:** `--plain --no-headers --columns KEY`
+5. **Proactive updates:** After code changes, offer to add commits/close issues
+6. **Rate limits:** Add `sleep 0.5` between bulk operations
+
+---
+
+# Troubleshooting
+
+**Auth errors:** Check `echo $JIRA_API_TOKEN` and `cat ~/.config/.jira/.config.yml`
+
+**Issue not found:** Verify project key correct: `jira issue view -p PROJ PROJ-123 --plain`
+
+**Rate limits:** Add delays between bulk operations, use more specific queries