repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

update prompts (ci, ff, lm, pr) and add acli skill

03e70bb217b3b8eeed243081b8814065286b0c8b

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (5)

prompts/ci.md

Modified
52 52 - Body only when useful:
53 53 bullets, rationale, tests.
54 54 - Preserve issue IDs.
55 + If exactly one issue is referenced in conversation history or branch name, include `closes #<N>` in the message.
56 + Multiple issues → stop and ask which to close. None → omit.
55 57 - No AI attribution/trailers.

prompts/ff.md

Modified
2 -description: Sync current git/jj branch into trunk via rebase + fast-forward
3 -argument-hint: "[trunk] [test-command]"
2 +description: Rebase current branch onto default branch and push fast-forward
3 +argument-hint: "[target-branch] [test-command]"
6 -# Sync current git/jj branch into trunk via rebase + fast-forward
6 +# Rebase onto default branch and push fast-forward
8 -Sync current branch/bookmark into trunk.
9 -Linear history only.
10 -No merge commits.
11 -Never force-push trunk.
8 +One flow. Works the same for git and jj.
9 +Linear history only. No merge commits. No force-push.
13 -Args:
14 -if `$1` is branch/ref/bookmark → trunk, `${@:2}` → tests.
15 -Else infer trunk, `$ARGUMENTS` → tests.
11 +## Args
17 -If `jj root` succeeds, use jj:
13 +- `$1` → target branch if it names an existing local/remote ref. Remainder → test command.
14 +- No arg → auto-detect default branch, no tests.
19 -1. Inspect:
20 - `jj status`, `jj bookmark list`, `jj git remote list`, `jj log -r
21 - '<trunk>..@'`.
22 -2. Stop on conflicts, dirty unrelated working-copy change, ambiguous
23 - trunk/bookmark, or non-git-backed jj repo when push is needed.
24 -3. Fetch/update:
25 - `jj git fetch --remote <remote>`.
26 -4. Rebase current stack if needed:
27 - `jj rebase -b @ -o <trunk>`.
28 -5. Test as below.
29 -6. Fast-forward trunk bookmark:
30 - `jj bookmark move <trunk> --to @` (never `--allow-backwards`).
31 -7. Push:
32 - `jj git push --remote <remote> --bookmark <trunk>`.
33 - On reject:
34 - fetch, re-evaluate, rebase once if safe, retest, retry.
35 -8. Report:
36 - trunk/remote, change old→new, rebase yes/no, tests, pushed change, follow-up.
16 +## Detect default branch
38 -Otherwise use git:
18 +Never assume a name. Detect dynamically:
40 -1. Inspect
41 - - Run:
42 - `git status --short --branch`, `git branch --show-current`, `git remote
43 - -v`, `git worktree list --porcelain`, `git branch -vv`.
44 - - Stop on:
45 - non-git, detached HEAD, merge/rebase in progress, dirty index/worktree,
46 - dirty trunk worktree.
47 - - Record:
48 - branch, upstream, remote, trunk, HEAD.
20 +**Git:**
21 +`git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/[^/]*/||'`
22 +Empty → `git remote set-head origin --auto` → retry.
23 +Fallback: `trunk` → `main` → `master` → `develop` (first existing local or remote ref wins).
24 +All fail → stop, ask user.
50 -2. Find trunk
51 - - Prefer arg.
52 - - Else infer:
53 - upstream/base metadata → remote HEAD → `main` → `master` → `trunk` →
54 - `develop`.
55 - - Ambiguous → ask.
56 - - If trunk checked out in worktree, use that worktree for trunk ops.
26 +**jj:**
27 +`jj bookmark list 'trunk()'` — uses configured trunk revset.
28 +Empty → try `trunk@origin` → `main@origin` → `master@origin`.
29 +All fail → stop, ask user.
58 -3. Fetch/update trunk
59 - - `git fetch --prune --tags <remote>`.
60 - - If trunk worktree:
61 - `git -C <wt> pull --ff-only`.
62 - - Else if local trunk exists:
63 - `git fetch <remote> <trunk>:<trunk>` (no `+`).
64 - - Else create from remote:
65 - `git branch --track <trunk> <remote>/<trunk>`.
66 - - Trunk divergence → stop.
31 +---
68 -4. If already on trunk
69 - - `git pull --ff-only`.
70 - - Run tests if given/obvious.
71 - - Push if ahead:
72 - `git push <remote> <trunk>`.
73 - - Report.
33 +## Flow
75 -5. Rebase branch
76 - - Check diff/log:
77 - `git log --oneline --left-right --cherry-pick <trunk>...HEAD`, `git diff
78 - --stat <trunk>...HEAD`.
79 - - If needed:
80 - `git rebase <trunk>`.
81 - - Conflict → stop; show status/files/next commands.
82 - - Verify branch still has intended commits/diff.
35 +Decide git or jj: `jj root` succeeds → jj, else git.
84 -6. Test
85 - - Run supplied test cmd, else cheap obvious checks from project files.
86 - - Failure → stop.
87 - No merge/push.
37 +1. **Preflight**
38 + - Git: `git status --short --branch`. Stop if dirty tree or ongoing merge/rebase.
39 + `git branch --show-current`. Stop if detached HEAD (empty output).
40 + - Jj: `jj status`. Stop on conflicts.
41 + - Record: current branch/bookmark, remote (default `origin`).
89 -7. Fast-forward trunk
90 - - Require:
91 - `git merge-base --is-ancestor <trunk> HEAD`.
92 - - If trunk worktree:
93 - `git -C <wt> merge --ff-only <branch-or-sha>`.
94 - - Else:
95 - `git update-ref refs/heads/<trunk> HEAD <old-trunk-sha>`.
43 +2. **Fetch**
44 + - Git: `git fetch --prune --tags <remote>`.
45 + - Jj: `jj git fetch --remote <remote>`.
97 -8. Push
98 - - `git push <remote> <trunk>`.
99 - - Rejected → fetch, re-evaluate, rebase once if safe, retest critical checks,
100 - retry.
101 - - Never force-push trunk.
47 +3. **Rebase onto target**
48 + - Before: record commit count on branch (`git rev-list --count <remote>/<target>..HEAD` / `jj log -r '<target>..@ --template ''` + count).
49 + If >50 → warn, proceed.
50 + - Git: `git rebase <remote>/<target>`.
51 + - Jj: `jj rebase -b @ -o <target>`.
52 + - After: compare commit count. Fewer → warn (empty commits dropped).
53 + - Conflicts → stop; show files, status, next commands.
54 + - Already up-to-date → skip, note in report.
103 -Report:
104 -trunk/remote, branch old→new SHA, rebase yes/no, tests, pushed SHA, follow-up.
56 +4. **Test**
57 + Run given command, or infer cheap checks from project files.
58 + Failure → stop, no push.
60 +5. **Push**
61 + - Git: `git push <remote> <branch>`.
62 + - Jj: `jj bookmark move <bookmark> --to @` (if behind), then `jj git push --bookmark <bookmark>`.
63 + - Rejected → fetch, rebase once, retest, retry **once**.
64 + - Retry also rejected → stop. Report error (likely branch protection or remote history rewrite).
65 + - Never force-push.
67 +---
69 +## Report
71 +branch, target, remote, rebase yes/no, tests, pushed SHA, follow-up.

prompts/lm.md

Added
new file mode 100644
1 +---
2 +description: Land local feature branch into default branch via fast-forward
3 +argument-hint: "[target-branch] [test-command]"
4 +---
6 +# Land local branch into default branch via fast-forward
8 +Fast-forward the default branch to your branch tip, then push.
9 +Linear history only. No merge commits. No force-push.
11 +## Args
13 +- `$1` → target branch if it names an existing local/remote ref. Remainder → test command.
14 +- No arg → auto-detect default branch, no tests.
16 +## Detect default branch
18 +Same as `ff`:
19 +**Git:** `git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/[^/]*/||'`
20 +Empty → `git remote set-head origin --auto` → retry.
21 +Fallback: `trunk` → `main` → `master` → `develop`.
22 +All fail → stop, ask user.
24 +**jj:** `jj bookmark list 'trunk()'`. Empty → `trunk@origin` → `main@origin` → `master@origin`.
25 +All fail → stop, ask user.
27 +---
29 +## Flow
31 +Decide git or jj: `jj root` succeeds → jj, else git.
33 +1. **Preflight**
34 + - Git: `git status --short --branch`. Stop if dirty tree or ongoing merge/rebase.
35 + `git branch --show-current`. Stop if detached HEAD.
36 + - Jj: `jj status`. Stop on conflicts.
37 + - Must be on a branch that is **not** the target branch. Already on target → tell user to use `ff` instead.
38 + - Record: branch, target, remote (default `origin`).
40 +2. **Fetch**
41 + - Git: `git fetch --prune --tags <remote>`.
42 + - Jj: `jj git fetch --remote <remote>`.
44 +3. **Verify ancestor**
45 + - Git: `git merge-base --is-ancestor <remote>/<target> HEAD`. Fail → target has commits not in your branch. Tell user to `ff` first (rebase onto target), then retry `lm`.
46 + - Jj: `jj rebase -b @ -o <target> --dry-run`. Fail → same guidance.
47 + - Check commit messages on branch for `closes #<N>`. If none found and conversation mentions an issue → warn: landing won't auto-close the issue.
49 +4. **Test**
50 + Run given command, or infer cheap checks from project files.
51 + Failure → stop, no land.
53 +5. **Fast-forward target**
54 + - Git: `git update-ref refs/heads/<target> HEAD <old-target-sha>`.
55 + - Jj: `jj bookmark move <target> --to @` (never `--allow-backwards`).
57 +6. **Push**
58 + - Git: `git push <remote> <target>`.
59 + - Jj: `jj git push --bookmark <target>`.
60 + - Rejected → fetch, verify ancestor still holds, retry **once**.
61 + - Retry also rejected → stop. Report error (likely branch protection or concurrent push).
63 +7. **Cleanup** (optional)
64 + - Git: offer to delete landed branch.
65 + - Jj: offer to abandon landed commits / remove bookmark.
67 +---
69 +## Report
71 +branch → target, remote, old/new target SHA, tests, pushed SHA, follow-up.

prompts/pr.md

Modified
2 2 description: Review, checkout, test, and prepare PR merge for git/jj repos
3 -argument-hint: "<pr-url|number|branch|ref> [test-command]"
3 +argument-hint: "[pr-url|number|branch|ref] [test-command]"
6 -# Review, checkout, test, and prepare PR merge for git/jj repos
6 +# Review, checkout, test, and prepare PR merge
8 8 Review PR end-to-end and prepare merge.
9 9 Do **not** merge until explicit user OK.
10 -If `jj root` succeeds, use jj-native status/diff/workspace commands; otherwise
11 -use git.
10 +If `jj root` succeeds, use jj; otherwise use git.
13 -**PR**:
14 -$1\
15 -**Test command override**:
16 -${@:2}
12 +**PR**: $1
13 +**Test command**: ${@:2}
18 -Workflow:
15 +## Forge CLI detection
17 +Detect from git remote URL:
18 +- `github.com` → `gh`
19 +- `codeberg.org` or any Forgejo instance → `fj`
20 +- bare git server → no forge CLI, generic git only
21 +- If forge CLI binary missing → fall back to generic git
23 +0. **Resolve PR**
24 + - If `$1` is set, use it.
25 + - Else scan conversation history for a previously discussed PR (URL, number, branch).
26 + - If none found → stop, ask user to specify.
20 28 1. **Identify**
21 - - Detect VCS:
22 - `jj root` → jj, else git.
23 - Detect host/tooling:
24 - GitHub `gh` if available; otherwise generic git remote.
25 - - Resolve PR metadata:
26 - title, author, base, head, URL, status, CI, labels.
27 - - Fetch latest base/head:
28 - jj `jj git fetch`; git `git fetch`/`gh pr checkout` path.
29 + - Detect VCS: `jj root` → jj, else git.
30 + - Detect forge CLI (above).
31 + - Resolve PR metadata: title, author, base, head, URL, status, CI, labels.
32 + - Fetch latest base/head: `jj git fetch` / `git fetch`.
30 34 2. **Protect local work**
31 - - Check jj `jj status` or git `git status --short`.
32 - - If dirty unrelated work exists:
33 - do not overwrite.
34 - Prefer isolated jj workspace or git worktree.
35 - - Detect repo style via jj `jj workspace list` or git `git worktree list`.
35 + - `jj status` or `git status --short`.
36 + - Dirty unrelated work → do not overwrite. Prefer isolated jj workspace or git worktree.
37 + - Detect repo style: `jj workspace list` / `git worktree list`.
37 39 3. **Checkout**
38 - - jj:
39 - prefer isolated workspace:
40 - `jj workspace add <path> -r <head-rev>`; otherwise `jj new <head-rev>` only
41 - when safe.
42 - - git:
43 - prefer worktree when repo uses worktrees, current tree is dirty, or PR
44 - needs isolation; otherwise branch checkout when clean.
45 - - GitHub path:
46 - use `gh` for metadata/merge; use VCS-native fetch/checkout/workspace for
47 - files.
48 - - Generic path:
49 - fetch PR/head ref or remote branch/bookmark, then create
50 - branch/worktree/workspace.
40 + - jj: prefer `jj workspace add <path> -r <head-rev>`. Otherwise `jj new <head-rev>` when safe.
41 + - git: prefer worktree when dirty or isolation needed. Otherwise branch checkout when clean.
42 + - Forge CLI path: use for metadata/merge only. Use VCS-native fetch/checkout for files.
43 + - Generic path: fetch PR head ref or remote branch, then create branch/worktree/workspace.
52 45 4. **Review diff**
53 - - Compare PR head vs base:
54 - jj `jj diff --from <base> --to <head>`; git `git diff <base>...<head>`.
46 + - jj: `jj diff --from <base> --to <head>`. git: `git diff <base>...<head>`.
55 47 - Read relevant files, tests, docs, configs.
56 - - Check correctness, security, perf, API compat, migrations, UX, error
57 - handling.
48 + - Check correctness, security, perf, API compat, migrations, UX, error handling.
58 49 - Verify PR matches issue/description.
60 51 5. **Test**
61 - - If test override provided, run it.
62 - - Else infer project commands from README, package files, lockfiles, CI,
63 - justfile, Makefile.
64 - - Run focused tests first, then broader suite if reasonable.
52 + - If test command provided, run it.
53 + - Else infer from project files (README, package files, CI, justfile, Makefile).
54 + - Focused tests first, broader suite if reasonable.
65 55 - Include lint/typecheck/build when conventional.
66 - - Capture exact commands and outcomes.
68 57 6. **Report**
69 - - Produce structured report:
70 - - PR summary
71 - - Checkout location + base/head SHAs/change IDs
72 - - Review findings:
73 - blockers / warnings / notes with file:line refs
74 - - Tests run:
75 - command → pass/fail
76 - - Merge readiness:
77 - READY | NOT READY
78 - - Exact merge plan/command to run after OK
58 + - PR summary
59 + - Checkout location + base/head SHAs/change IDs
60 + - Review findings: blockers / warnings / notes with file:line refs
61 + - Tests run: command → pass/fail
62 + - Merge readiness: READY | NOT READY
63 + - Exact merge plan/command to run after OK
79 64 - If not ready, list minimal required fixes.
81 66 7. **Wait**
82 - - Stop after report.
83 - - Ask for explicit OK to merge only if READY.
84 - - On OK:
85 - re-fetch, verify PR still current/mergeable, run critical checks if needed,
86 - then merge using repo convention (`gh pr merge`, platform tool, jj bookmark
87 - move/push, or local git merge).
67 + - Stop after report. Ask for explicit OK to merge only if READY.
68 + - On OK: re-fetch, verify PR still current/mergeable, run critical checks,
69 + then merge using forge CLI or VCS-native (fast-forward preferred).
88 70 Report final status.
89 - - After successful merge:
90 - remove jj workspace or git worktree/branch of PR
71 + - After merge: offer to remove jj workspace or git worktree/branch.

skills/acli/SKILL.md

Added
new file mode 100644
1 +---
2 +name: acli
3 +description: >
4 + Atlassian CLI (acli) for Jira, Confluence, Rovo Dev, and org admin.
5 + Use when: working with Jira issues/projects/boards/sprints, Confluence
6 + pages/spaces/blogs, Atlassian org users, or Rovo Dev. Triggers on:
7 + jira, confluence, rovo, atlassian, work item, sprint, JQL, confluence page/space/blog.
8 +---
10 +# Atlassian CLI (`acli`)
12 +CLI for Atlassian Cloud. Docs: <https://developer.atlassian.com/cloud/acli/>
14 +## Requirements
16 +- `acli` installed (`brew install acli`, `apt`, or from <https://developer.atlassian.com/cloud/acli/guides/install-acli/>)
17 +- Authenticated per product:
19 +```bash
20 +acli jira auth login # Jira
21 +acli confluence auth login # Confluence
22 +acli rovodev auth login # Rovo Dev (needs API token from https://go.atlassian.com/rovo-dev-api-token)
23 +acli admin auth login # Org admin
24 +```
26 +## Auth check
28 +```bash
29 +acli jira auth status
30 +acli confluence auth status
31 +```
33 +## Command Structure
35 +```
36 +acli <product> <resource> <action> [flags]
37 +```
39 +Products: `jira`, `confluence`, `rovodev`, `admin`
41 +## Jira
43 +### Work Items (issues)
45 +```bash
46 +# Create
47 +acli jira workitem create --summary "Title" --project PROJ --type Task
48 +acli jira workitem create --summary "Bug" --project PROJ --type Bug --assignee @me --label "backend,urgent"
49 +acli jira workitem create --description "plain text or ADF JSON" --description-file desc.txt -p PROJ -t Story -s "Title"
51 +# Create from JSON (scaffold first)
52 +acli jira workitem create --generate-json > workitem.json
53 +# edit workitem.json, then:
54 +acli jira workitem create --from-json workitem.json
56 +# Bulk create
57 +acli jira workitem create-bulk --from-csv issues.csv
58 +acli jira workitem create-bulk --from-json issues.json
60 +# View
61 +acli jira workitem view KEY-123
62 +acli jira workitem view KEY-123 --fields summary,status,assignee,description --json
63 +acli jira workitem view KEY-123 --web
65 +# Search (JQL)
66 +acli jira workitem search --jql "project = PROJ AND status = Open" --paginate
67 +acli jira workitem search --jql "assignee = currentUser() AND sprint in openSprints()" --fields "key,summary,priority" --json
68 +acli jira workitem search --jql "project = PROJ" --csv --limit 50
69 +acli jira workitem search --filter 10001 # by saved filter ID
71 +# Edit
72 +acli jira workitem edit --key KEY-123 --summary "Updated title"
73 +acli jira workitem edit --key KEY-1,KEY-2 --assignee user@example.com
74 +acli jira workitem edit --jql "project = PROJ AND status = 'To Do'" --assignee @me
76 +# Transition (change status)
77 +acli jira workitem transition --key KEY-123 --status "In Progress"
78 +acli jira workitem transition --jql "project = PROJ" --status Done --yes
80 +# Clone
81 +acli jira workitem clone --key KEY-123 --to-project OTHER
83 +# Comments
84 +acli jira workitem comment create --key KEY-123 --body "comment text"
85 +acli jira workitem comment create --key KEY-123 --body-file comment.txt
86 +acli jira workitem comment list --key KEY-123
87 +acli jira workitem comment update --key KEY-123 --id COMMENT_ID --body "updated"
88 +acli jira workitem comment delete --key KEY-123 --id COMMENT_ID
90 +# Links
91 +acli jira workitem link create --key KEY-1 --target KEY-2 --type "Blocks"
92 +acli jira workitem link list --key KEY-1
93 +acli jira workitem link type # list available link types
95 +# Attachments
96 +acli jira workitem attachment list --key KEY-123
97 +acli jira workitem attachment delete --key KEY-123 --id ATTACHMENT_ID
99 +# Other
100 +acli jira workitem assign --key KEY-123 --assignee user@example.com
101 +acli jira workitem archive --key KEY-123
102 +acli jira workitem delete --key KEY-123 --yes
103 +acli jira workitem watcher list --key KEY-123
104 +acli jira workitem watcher remove --key KEY-123 --user user@example.com
105 +```
107 +### Projects
109 +```bash
110 +acli jira project list
111 +acli jira project view PROJ
112 +acli jira project create --key PROJ --name "Project Name"
113 +acli jira project update PROJ --name "New Name"
114 +acli jira project archive PROJ
115 +acli jira project delete PROJ
116 +```
118 +### Boards & Sprints
120 +```bash
121 +acli jira board search --project PROJ
122 +acli jira board get BOARD_ID --json
123 +acli jira board list-sprints BOARD_ID
124 +acli jira sprint create --board BOARD_ID --name "Sprint 1"
125 +acli jira sprint view SPRINT_ID
126 +acli jira sprint list-workitems SPRINT_ID
127 +acli jira sprint update SPRINT_ID --state closed
128 +```
130 +### Filters & Fields
132 +```bash
133 +acli jira filter list
134 +acli jira filter search --jql "project = PROJ"
135 +acli jira field create --name "My Field" --type text
136 +```
138 +## Confluence
140 +### Pages
142 +```bash
143 +# View (note: confluence page creation is via API only; acli has view)
144 +acli confluence page view --id PAGE_ID
145 +acli confluence page view --id PAGE_ID --json
146 +acli confluence page view --id PAGE_ID --body-format storage # XHTML storage format
147 +acli confluence page view --id PAGE_ID --body-format atlas_doc_format
148 +acli confluence page view --id PAGE_ID --include-labels --include-version
149 +```
151 +### Spaces
153 +```bash
154 +acli confluence space list
155 +acli confluence space view --key SPACEKEY
156 +acli confluence space create --key SPACEKEY --name "Space Name" --description "desc"
157 +acli confluence space update --key SPACEKEY --name "New Name"
158 +acli confluence space archive --key SPACEKEY
159 +acli confluence space restore --key SPACEKEY
160 +```
162 +### Blogs
164 +```bash
165 +acli confluence blog create --space-id 12345 --title "Post" --body "<p>Content</p>"
166 +acli confluence blog create --space-id 12345 --title "Draft" --status draft --body "text"
167 +acli confluence blog create --space-id 12345 --title "Post" --from-file content.html
168 +acli confluence blog create --from-json payload.json
169 +acli confluence blog list --space-id 12345
170 +acli confluence blog view --id BLOG_ID
171 +```
173 +## Rovo Dev
175 +AI coding agent (beta). Requires separate API token.
177 +```bash
178 +acli rovodev auth login
179 +acli rovodev run
180 +```
182 +## Admin
184 +```bash
185 +acli admin user activate --account-id USER_ID
186 +acli admin user deactivate --account-id USER_ID
187 +acli admin user delete --account-id USER_ID
188 +acli admin user cancel-delete --account-id USER_ID
189 +```
191 +## Output Flags
193 +| Flag | Effect |
194 +| ----------- | --------------------------- |
195 +| `--json` | JSON output |
196 +| `--csv` | CSV output (search only) |
197 +| `--web` | Open in browser |
198 +| `--paginate`| Fetch all pages of results |
199 +| `--limit N` | Cap results |
201 +## Global Flags
203 +```text
204 +--yes / -y Skip confirmation prompts
205 +--json Machine-readable output
206 +```
208 +## JQL Quick Reference
210 +```text
211 +project = PROJ Filter by project
212 +status = Open By status
213 +assignee = currentUser() My issues
214 +assignee = @me (alias in some commands)
215 +sprint in openSprints() Current sprint
216 +type = Bug By issue type
217 +priority = High By priority
218 +text ~ "search term" Full-text search
219 +created >= "2025-01-01" Date range
220 +updated <= -1d Relative date
221 +ORDER BY priority DESC Sorting
222 +```
224 +Combine with `AND` / `OR` / `NOT`. Group with `()`.
225 +Use `--paginate` for large result sets.
227 +## Description & Comment Format
229 +acli accepts plain text for descriptions/comments. For rich formatting, use
230 +Atlassian Document Format (ADF) JSON:
232 +```bash
233 +acli jira workitem create --generate-json # see ADF structure
234 +```
236 +ADF is verbose. For simpler markup conversion, use pandoc:
238 +```bash
239 +# Markdown → Jira wiki markup (for comments/descriptions that accept it)
240 +echo '# Title\n\n**bold** _italic_' | pandoc -f markdown -t jira
241 +# → h1. Title\n\n*bold* _italic_
243 +# Jira wiki markup → Markdown (for reading)
244 +echo 'h1. Title' | pandoc -f jira -t markdown
245 +# → # Title
246 +```
248 +Note: acli's `--description` accepts plain text or ADF JSON, not Jira wiki
249 +markup. Use pandoc's `jira` format for converting existing wiki markup to
250 +readable text. For Confluence, `--body` accepts Confluence storage format (XHTML).
252 +## Common Patterns
254 +### Find my open bugs this sprint
256 +```bash
257 +acli jira workitem search --jql "assignee = currentUser() AND type = Bug AND sprint in openSprints()" --paginate --json
258 +```
260 +### Bulk transition to Done
262 +```bash
263 +acli jira workitem transition --jql "project = PROJ AND status = 'In Review'" --status Done --yes
264 +```
266 +### Create sub-task under epic
268 +```bash
269 +acli jira workitem create --summary "Sub-task" --project PROJ --type "Sub-task" --parent EPIC-1 --assignee @me
270 +```
272 +### Export issues as CSV
274 +```bash
275 +acli jira workitem search --jql "project = PROJ" --fields "key,summary,status,assignee" --csv > issues.csv
276 +```
278 +## Troubleshooting
280 +### "failed to parse JQL query"
282 +JQL field values are case-sensitive. Quote strings with spaces.
283 +Use `=` (exact), `~` (fuzzy/contains), `!=`, `!~` (not contains).
285 +### Auth errors
287 +```bash
288 +acli jira auth status
289 +acli jira auth login # re-authenticate
290 +```
292 +### Rate limiting
294 +Use `--limit` to cap results. Avoid `--paginate` in tight loops.