Skip to content

netresearch/jira-skill / skills/jira-communication

jira-communication

Flagged

Use when handling Jira issues, sprints, boards, links, fields, worklogs, attachments, or users, or on any Jira intent without a key ("create/find a ticket", "pick a project"). Auto-triggers on Jira URLs and issue keys (PROJ-123). Also use when MCP Atlassian tools fail or are unavailable for Jira Server/DC.

FileKindSize
AGENTS.mdmarkdown2.5 KB
CLAUDE.mdmarkdown9 B
SKILL.mdskill md10.4 KB
evals/evals.jsonconfig7.6 KB
references/agile.mdmarkdown1.9 KB
references/attachments.mdmarkdown4.7 KB
references/comments.mdmarkdown14.4 KB
references/creation.mdmarkdown4.0 KB
references/fields-and-users.mdmarkdown7.7 KB
references/intent-verbs.mdmarkdown13.5 KB
references/issue-editing.mdmarkdown11.6 KB
references/jql-cookbook.mdmarkdown8.0 KB
references/jql-quick-reference.mdmarkdown6.3 KB
references/links.mdmarkdown7.8 KB
references/multi-profile.mdmarkdown3.9 KB
references/no-editorializing.mdmarkdown2.3 KB
references/qa-gather.mdmarkdown12.1 KB
references/troubleshooting.mdmarkdown12.0 KB
references/versions.mdmarkdown7.7 KB
references/watchers.mdmarkdown3.9 KB
references/worklog.mdmarkdown8.6 KB
scripts/core/jira-attachment.pyexecutablescript21.2 KB
scripts/core/jira-issue.pyexecutablescript50.6 KB
scripts/core/jira-search.pyexecutablescript9.6 KB
scripts/core/jira-setup.pyexecutablescript20.0 KB
scripts/core/jira-validate.pyexecutablescript14.2 KB
scripts/core/jira-worklog.pyexecutablescript15.5 KB
scripts/lib/__init__.pyscript742 B
scripts/lib/changelog.pyscript8.0 KB
scripts/lib/client.pyscript26.4 KB
scripts/lib/config.pyscript15.9 KB
scripts/lib/errors.pyscript1.8 KB
scripts/lib/input.pyscript3.5 KB
scripts/lib/jql.pyscript375 B
scripts/lib/markup.pyscript33.2 KB
scripts/lib/markup_cli.pyscript11.3 KB
scripts/lib/output.pyscript6.9 KB
scripts/lib/preview.pyscript10.0 KB
scripts/lib/render.pyscript1.8 KB
scripts/lib/ticket_state.pyscript13.3 KB
scripts/lib/users.pyscript7.5 KB
scripts/utility/jira-fields.pyexecutablescript11.7 KB
scripts/utility/jira-link.pyexecutablescript42.9 KB
scripts/utility/jira-qa-gather.pyexecutablescript26.3 KB
scripts/utility/jira-user.pyexecutablescript9.3 KB
scripts/utility/jira-watchers.pyexecutablescript9.1 KB
scripts/utility/jira-weblink.pyexecutablescript11.2 KB
scripts/utility/jira-worklog-query.pyexecutablescript27.4 KB
scripts/workflow/jira-board.pyexecutablescript7.0 KB
scripts/workflow/jira-comment.pyexecutablescript19.2 KB
scripts/workflow/jira-create.pyexecutablescript24.3 KB
scripts/workflow/jira-move.pyexecutablescript23.5 KB
scripts/workflow/jira-sprint.pyexecutablescript8.1 KB
scripts/workflow/jira-transition.pyexecutablescript33.7 KB
scripts/workflow/jira-version.pyexecutablescript29.4 KB
scripts/workflow/tempo-account.pyexecutablescript9.1 KB

references/comments.md

View on GitHub
<!-- SPDX-License-Identifier: CC-BY-SA-4.0 -->
<!-- SPDX-FileCopyrightText: Netresearch DTT GmbH -->

# Comments — Edit, Delete, List, Restrict

## When to load

Load this reference whenever the user wants to edit or delete an existing comment, list comments, needs to get a comment ID for any reason, or wants to post a restricted/internal comment (`--visibility`).

## List and get IDs

```bash
# Pretty list (most recent last)
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-comment.py list PROJ-123

# JSON list — use this to harvest comment IDs for edit/delete
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-comment.py --json list PROJ-123
```

The JSON output has a top-level `comments` array; each entry has `id`, `author.displayName`, `body`, and `updated`.

### `list` shows ten comments by default — pass `--limit 0` when you are reading, not harvesting

```bash
# The whole history, paginated for you
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-comment.py list PROJ-123 --limit 0
```

Ten is the right default for grabbing a recent comment ID. It is the wrong default for answering a question about what a ticket says, and the difference is invisible in the answer: a busy ticket carries its decisions in the middle of its history, and the last ten comments are the part that agreed with you. When the read informs a claim — a QA verdict, a status report, "nobody mentioned X" — use `--limit 0`.

A truncated read now says so on **stderr** as well as in the table, so the notice survives a pipe and appears under `--json` and `--quiet` too. If you see `⚠ PROJ-123: showing 10 of 163 comments`, the answer you are about to give is based on 10.

### Never put a line filter between `list` and your eyes

`| head`, `| tail`, `| grep`, `--max-count` — each of them cuts a comment body mid-sentence and drops whole comments silently, and what is left looks like a complete answer. "X does not appear in this ticket" after a truncated read is a statement about the cut, not about the ticket; it has been wrong in exactly that way, in a public comment that someone else had to correct.

Use the tool's own knobs instead, which cut where the data says to cut rather than where the terminal does:

```bash
# Shorten every body to N characters, keeping all comments and their metadata
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-comment.py list PROJ-123 --limit 0 --truncate 200

# Or select deliberately, in a structured way
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-comment.py --json list PROJ-123 --limit 0 \
  | jq -r '.[] | select(.author.name == "someone") | .body'
```

For a body too large to read in one go, write it to a file and read windows of it — the file keeps the whole thing while you look at part of it, which is the property a pipe destroys.

## Restricted comments (visibility)

`add --visibility role:<project role>` (or `group:<group>`) posts a comment only that project role or group can read — for internal findings on a ticket the customer also reads:

```bash
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-comment.py add PROJ-123 - --visibility role:Developers < finding.txt
```

Before posting, check who will be able to read it. Measured on Jira Server 9.12.3:

- **You must be in the role or group yourself.** Otherwise Jira refuses the comment and the CLI prints Jira's reason, e.g. `You are currently not a member of the group: <group>`. An unknown role fails with `Role with id: <name> does not exist`.
- **A role's members are a project setting**, and a role can hold individual users as well as groups. `GET /rest/api/2/project/<KEY>/role` lists the roles; `GET …/role/<id>` shows their users and groups; `GET /rest/api/2/group/member?groupname=<group>` expands a group. Reading a project's roles needs project admin rights — without them the API answers 401, so ask a project admin.
- **A `[~user]` mention does not grant access.** Mention verification only checks that the user exists; someone outside the role or group still cannot read the comment.
- **`edit` keeps the restriction.** Editing the text of a restricted comment leaves its visibility as it was.
- On Jira Cloud group names can change; Cloud recommends the group `identifier` (ID), which this option does not take — `value` (the name) still works.

Say so explicitly if you pick a different role or group than the one you were asked for.

## Edit an existing comment

```bash
# Full replacement of the body — edits preserve created timestamp, update the "updated" timestamp
# (issue key, comment ID and text are positional arguments)
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-comment.py edit PROJ-123 594276 "Corrected text"
```

Jira appends an "edited" marker in the UI automatically.

## Delete a comment

```bash
# Preview
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-comment.py delete PROJ-123 594276 --dry-run

# Real delete
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-comment.py delete PROJ-123 594276
```

Non-interactive: no confirmation prompt, no stdin — `--dry-run` is the preview, the real call deletes on the spot (no `echo y |` needed). Deleting someone else's comment requires the Delete All Comments permission.

## Multi-line comments

`jira-comment.py add` takes the body as a positional argument. Pass `-` to read the body from stdin, which pairs naturally with a HEREDOC or a file:

```bash
uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-comment.py add PROJ-123 - <<'EOF'
h3. Progress

Deployed to staging, see https://staging.example.com/.
EOF

# Or from a file
cat comment.txt | uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-comment.py add PROJ-123 -

# Preview first: prints the body as it would be posted, posts nothing
cat comment.txt | uv run ${CLAUDE_SKILL_DIR}/scripts/workflow/jira-comment.py add PROJ-123 - --dry-run
```

`--dry-run` works the same on `edit`. The preview runs the escape and the lint, so it shows the repaired text and refuses what those two would refuse. It skips the render call and the mention lookup, which both go to the instance, so a struck-through render or an unknown `[~username]` only surfaces on the real post.

Comments use Jira wiki markup — see the **jira-syntax** skill for formatting.

## Markup lint

The three gates described here — escape, lint, render preview — run on every `--comment` and `--description` that writes wiki markup, not only on comments: `jira-comment.py add`/`edit`, `jira-transition.py do --comment`, `jira-transition.py path --comment`, `jira-worklog.py add --comment`, and the `--description` of `jira-create.py issue` and `jira-issue.py update`. Seven surfaces, and the three flags (`--force`, `--no-auto-escape`, `--no-preflight`) are spelled the same on each. The text below says "the body"; a description is checked identically. Two things are outside: a field written through `--fields-json`, which bypasses every gate by design, and the `--description` of `jira-version.py create`/`update`, where it is unverified whether Jira renders the field as wiki markup at all. `jira-transition path` IS gated; only the placement differs — it checks the comment before the FIRST transition rather than the final one it rides on, because a walk that aborted halfway would otherwise leave the issue in a status nobody chose. All seven take `--dry-run`. Under it the escape and the lint still run, so the preview prints what would be posted; the render call and the write are dropped.

They lint the body before posting: inline block tags (`{code}`, `{noformat}`, `{quote}`, `{panel}` are block-level — a tag with other text on the same line opens a block mid-prose) and unbalanced tag counts abort with an error. Escape literal tag mentions as `\{code\}`. Override with `--force` (findings are then printed as warnings).

Before posting, they also ask the instance how it will render the text (`POST /rest/api/1.0/render`, the endpoint behind Jira's own preview button) and refuse to post anything that comes back struck through. This catches what no local model can: Jira substitutes autolinked issue keys before text effects run, so `OPS-899-x und zu- und` is struck on an instance where OPS-899 exists and clean on one where it does not, because the substituted link creates the opener boundary. A link to a resolved issue is not counted: Jira draws its key in `<del>` inside the link as status styling, which is not a text effect, and the check unwraps exactly that shape before looking for struck spans. `--force` posts anyway; `--no-preflight` skips the call. An unreachable renderer, or a Cloud instance (the endpoint is Server/DC only), prints one warning and gets out of the way — it never blocks a post.

Dashes that Jira would render as a strikethrough span are **repaired rather than reported**: they are escaped before posting and print on stderr which lines they changed. `\-` prints as a plain hyphen, so the posted text reads as written. `--no-auto-escape` keeps the markup verbatim, but does not by itself post text with a live span — the lint and the render check each refuse it independently, so a deliberate strikethrough needs `--no-auto-escape --force`. The grammar is measured against a live Jira Server 9.12 renderer — the recorded cases and the re-recording script live in the source repo (netresearch/jira-skill), not in the standalone skill package — which matters because the shape is counter-intuitive in both directions: `journalctl -b -p crit` is safe (a dash leading a word cannot close a span), while `{{nr-pforum}}-Extensions ... zu- und abschaltbar` is struck through end to end. See the quick reference in the `jira-syntax` skill for the full rule.

The same lint carries a **ticket-language reminder**. Some projects are English-only by team convention (the rule and the project list live in the consuming team skill; the check ships with `NRS`, `NRT`, `SRV*`, `IO*`, `LIC`, `PO`), and language drift is invisible in review because such tickets often already contain German from quoted mails. When a comment on one of those keys reads as German prose — five or more distinct German function words, which a loanword or a short quoted fragment stays below — the lint says so and names the markers it found. The scan reads the whole body and cannot tell a quote from authored text, so a comment carrying a *substantial* German quote is reported too; `--force` is how you post it verbatim. Other projects, customer ones included, are never touched by this check.

The lint also refuses a **reference to another comment by position** — "the comment above", "the comments below", "the above comment", "Kommentar oben", "der obige Kommentar" — because comment order is a per-user setting (`jira.issue.actions.order`; the rule itself is in *Consolidate progress updates*). Only phrases that name a comment are matched: a bare "see above", "the table above" or "siehe oben" usually points inside the same comment and is not flagged, and neither is "the comment above the method", which is about source code. Write "the previous comment" or "the earlier comment", link it with a permalink (`?focusedCommentId=`), or name its heading or timestamp. `--force` posts anyway.

Every command that posts mention-capable wiki markup runs the same mention gate: `jira-comment add`/`edit`, `jira-transition do --comment`, `jira-worklog add --comment`, and the `--description` of `jira-create issue` / `jira-issue update`. Each `[~username]` is verified against Jira before posting (an unverified mention renders as dead text and notifies nobody); an unknown username aborts with candidate suggestions rendered in the form that actually notifies (`[~name]` on Server/DC, `[~accountid:...]` on Cloud, where a plain `[~username]` can never notify and is always flagged). Mentions inside `{code}`/`{noformat}` blocks and backslash-escaped literals (`\[~...]`) are ignored — quoting a log line does not trip the gate. Auth or transport failures abort with the real error, never as "unknown user". Skip with `--no-verify-mentions`.

## Verify rendering after posting

A 2xx on `add`/`edit` proves the write landed, not that the markup renders as intended — Jira renders wiki markup server-side. The rendered HTML is the only proof:

```bash
curl -s -H "Authorization: Bearer $JIRA_PERSONAL_TOKEN" \
  "$JIRA_URL/rest/api/2/issue/<KEY>/comment/<id>?expand=renderedBody" | jq -r '.renderedBody'
```

Grep it for what you fear: `<del>` means something parsed as strikethrough, a literal `\` means a backslash escape reached the reader, and `&#45;` is a correctly escaped dash. This is a manual check — nothing runs it for you. With the pre-flight above left on, a `<del>` here should not happen; seeing one means it was skipped, forced, or that the renderer changed its mind between the preview and the write. Run this after editing any markup-sensitive comment; verified against Jira Server 9.12.

## Comment verbosity: depth for the failing path only

Working-path checks get ONE summary line at most; the non-working path gets the depth; obvious/derivable steps are cut entirely. A human reader cannot filter long tables that mostly say "this works" — verbose investigation comments cause overload and force the reader to re-derive what mattered.

## Consolidate progress updates — edit, don't append

When iterative work on one issue produces multiple status updates, edit the prior comment instead of adding a new one. Watchers and QA reviewers are notified per comment and must wade through progress chatter to find the current state. Reserve new comments for genuinely separate story beats that build on (not restate) earlier ones.

Never point at another comment by position. Comment order is a per-user preference (`jira.issue.actions.order`, `asc` or `desc`, readable via `GET /rest/api/2/mypreferences?key=jira.issue.actions.order`), so "my comment above" names a different comment, or none, for the next reader. Refer to a comment by its heading, its content or its timestamp — "the QA comment (`h3. QA - passed`)", "the deploy comment of 2026-09-01". Words of time — "previous", "earlier", "next", "later" — are fine, because the order in time is the same for every reader. A restricted comment (`--visibility`) can still sit in between for some readers, so on a ticket that has them, pair the time word with the heading or timestamp ("the earlier deploy comment of 2026-09-01"). A permalink is exact: `https://<host>/browse/KEY-1?focusedCommentId=<id>&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#comment-<id>`, with `<id>` from `jira-comment.py --json list`. Inside a single comment, "above" and "below" are fine: one comment renders top to bottom. Editing the original comment avoids the reference altogether.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexUnverifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall