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/worklog.md

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

# Worklogs — Advanced Logging and Cross-Cutting Queries

## When to load

Load this reference whenever the user wants to log work with a custom start date/time, undo a worklog, or query worklogs across multiple issues by date range, user, project, epic or sprint.

## Before booking: is Jira the system of record?

Check this once per team, before the first `add`. Where a separate time tracker syncs its entries into Jira, that tracker owns time and a direct `jira-worklog.py add` **double-books** — your entry plus the one the tracker syncs in later. The duplicate is easy to miss afterwards, because a synced entry is indistinguishable from a hand-written one on the issue.

The team convention belongs in an `AGENTS.md` or a team runbook, not in this skill — it cannot know your setup. If Jira *is* the system of record, `add` is correct and the rest of this section applies.

## `jira-worklog.py add` — advanced flags

```bash
# Simplest — logs "now" against your account
uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-worklog.py add PROJ-123 2h --comment "Work done"

# Explicit start time
uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-worklog.py add PROJ-123 1h30m \
    --started "2026-04-20T14:00:00" --comment "Research session"
```

Time strings accept `Nw Nd Nh Nm Ns` combinations (Jira semantics, 8h workday).

`--dry-run` prints the entry as it would be added, with its start time and the comment after the markup escape and lint, and adds nothing. It skips the render call and the mention lookup, so an unknown `[~username]` only surfaces on the real run. The time spent is passed on as given; `--started` is converted to Jira's timestamp format where it is recognised and otherwise passed on unchanged. Neither is validated, so a malformed value such as `2x` previews cleanly and is refused by Jira only on the real run.

## `jira-worklog.py delete` — undo a booking

Every `add` prints the new `Worklog ID`, and `list` shows the id of each entry — that id is the handle for `delete`. Use it to undo a booking made against the wrong issue, the wrong duration, or the wrong system (see above).

```bash
# See which entries exist, with their ids
uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-worklog.py list PROJ-123
#   [2026-08-06] Jane Doe: 45m  (id 409062)

# Preview — shows the entry that would go away, deletes nothing
uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-worklog.py delete PROJ-123 409062 --dry-run

# Delete it
uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-worklog.py delete PROJ-123 409062
```

`delete` fetches the entry first and echoes its date, author and duration, so a mistyped id surfaces before anything is removed rather than after. Deleting your own worklog needs the "Delete Own Worklogs" permission; someone else's needs "Delete All Worklogs".

## `jira-worklog-query.py` — cross-cutting query

```bash
# Default: my worklogs for the current week
uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-worklog-query.py

# By project with per-entry detail
uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-worklog-query.py --project PROJ --detail

# By date range, JSON output
uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-worklog-query.py \
    --from 2026-03-01 --to 2026-03-31 --json

# By epic or sprint
uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-worklog-query.py --epic PROJ-1940
uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-worklog-query.py --sprint 916
```

`--detail` shows individual worklog entries grouped by issue. Default output groups by issue with per-issue and grand totals. `--json` emits the raw worklog list — pipe to `jq` for custom reports.

## By Tempo account (customer worked-time)

To get the worked time booked to a **Tempo account** (a customer) for a month — across *all* workers, not just yourself — use `--tempo-account`:

```bash
# Total worked time for a customer account in a month (all workers)
uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-worklog-query.py \
    --tempo-account ACME --from 2026-06-01 --to 2026-06-30 --detail
```

`--tempo-account` forces the Tempo backend and ignores `--user`/`--issue`/`--epic`/`--sprint`/`--project` (the account *is* the filter). Accepts a comma-separated list of account keys.

> **Requires Tempo Timesheets on Jira Server/DC** — the whole Tempo backend (`--tempo-account`, `--backend tempo`, and `--backend auto`'s detection) talks to `/rest/tempo-timesheets/4`. Tempo **Cloud** exposes a different API (`api.tempo.io`) and is **not** supported: `--tempo-account`/`--backend tempo` fail with a clear message, and `--backend auto` falls back to the JQL backend.

Why this exists: the plain worklog query (JQL or the Tempo worker search) can only filter by **worker**, issue, project or date — **not by Tempo account**. Time a customer books via a standby/support package is often logged by someone else on an issue you wouldn't guess, so a per-issue or per-user query silently returns nothing. Under the hood `--tempo-account` calls `POST /rest/tempo-timesheets/4/worklogs/search` with an `accountKey` array — the only endpoint that filters by account directly. It can return far fewer worklogs than the account holds: a technical user's token got a single worklog, its own (see [When the account search comes back short](#when-the-account-search-comes-back-short)). When a wrapper flag is missing, reach for the underlying REST before concluding the data is unreachable:

```bash
set -a; source ~/.env.jira; set +a
curl -sS -H "Authorization: Bearer $JIRA_PERSONAL_TOKEN" -H "Content-Type: application/json" \
  -X POST "${JIRA_URL%/}/rest/tempo-timesheets/4/worklogs/search" \
  -d '{"from":"2026-06-01","to":"2026-06-30","accountKey":["ACME"]}'
# account lookup (key/name/lead): GET /rest/tempo-accounts/1/account/<id>
```

### When the account search comes back short

The account search answers with whatever the token's user may see in Tempo, and a short answer looks exactly like a small account. Measured on Jira Server with Tempo Timesheets 4: for one account over twelve months, a user's token got 707 worklogs, while a technical user's token got 1 — its own. Nothing in the response says that worklogs were left out.

The likely cause is the user's Tempo permission to view other people's worklogs; that permission was not read in the measured case. Where the token can browse the issues, count per issue instead. Search the issues by the account field, then read each issue's worklogs; Jira's issue worklog endpoint returns them to anyone who may browse the issue, except worklogs restricted to a group or role:

```bash
# 1. the issues: "Account" is the Tempo account field. -n defaults to 50 — set it,
#    and page with --start-at when the account has more issues than that.
uv run ${CLAUDE_SKILL_DIR}/scripts/core/jira-search.py --json query \
    '"Account" in (ACME) AND worklogDate >= 2025-10-01' -f key -n 500
# 2. per issue: GET /rest/api/2/issue/<KEY>/worklog
#    (sum timeSpentSeconds of the worklogs whose `started` falls in the window)
```

For the account above, the per-issue count with the technical user's token gave the same 677.6 h as the account search with the user's token. The per-issue sum covers the issues whose Account field holds the account. Whether the account search also counts worklogs that carry a different account than their issue was not measured.

When two totals for the same account still differ, check first whether the two tokens see different issues; in the measured case that was the whole difference. Other causes were not ruled out: worklogs restricted to a group or role, and worklogs that carry a different account than their issue. Find the issues before trusting either number:

1. Collect the issue keys behind each total (the account search returns `issue.key` per worklog) and diff the two sets.
2. For the issues only one side sees, check the other token's rights: `GET /rest/api/2/mypermissions?projectKey=<KEY>&permissions=BROWSE_PROJECTS` for the project, and the issue's `security` field (read with the token that does see it) for an issue security level.

In the case this was measured on, 112 h of the 1,288 h the user's token found in the account search were missing from the technical user's per-issue count: 110.3 h sat on two issues with an issue security level that hid them from the technical user, and 1.7 h in a project it could not browse. Compared issue by issue, every other issue matched to the hour.

## Relative dates

`--from` and `--to` accept plain `YYYY-MM-DD`. For rolling queries, compute the dates in the shell:

```bash
uv run ${CLAUDE_SKILL_DIR}/scripts/utility/jira-worklog-query.py \
    --from "$(date -d 'monday last week' -I)" --to "$(date -I)"
```
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