---
name: create-jira-tickets
description: Create Jira tasks from a tickets.md file under an existing epic using the Atlassian CLI (acli)
disable-model-invocation: true
---

# Create Jira Tickets from Ticket Doc

Parse a `tickets.md` file and create Jira tasks under an existing epic in the `PP` project using `acli`.

## Usage

```
/create-jira-tickets [path/to/tickets.md] [--epic <PP-NNNN>] [--notion <URL>]
```

- `path/to/tickets.md` — optional; defaults to `tickets.md` in the current directory or any subdirectory.
- `--epic <PP-NNNN>` — the existing Jira epic key to nest tasks under. If not provided, ask the user for it before creating any tickets.
- `--notion <URL>` — optional Notion page URL; if provided, each ticket description links to it instead of "see tickets.md".

## Prerequisites

- **`acli` (Atlassian CLI)** must be installed. See [Atlassian CLI docs](https://developer.atlassian.com/cloud/acli/) for installation.
- **`acli` must be authenticated**: follow the `acli jira auth login` instructions in the Atlassian CLI docs, and prefer `--web` login or piping/redirecting the token rather than passing `--token <token>` directly on the command line.


## Expected Input Format

The `tickets.md` file must follow this structure:

```markdown
# PP-NNNN — Epic Title

### Ticket Summary

| Ticket    | Title          | Service  | Blocked by  |
|-----------|----------------|----------|-------------|
| Ticket 01 | Short title    | svc-name | —           |
| Ticket 02 | Short title    | svc-name | Ticket 01   |

---

### Ticket PP-XXXX (01) — Service: Short Title

**Service**: service-name | **Blocked by**: — | **Blocks**: Ticket 02

#### Summary

1–3 sentence description of what this ticket does.

#### Acceptance Criteria

- Bulleted list of verifiable outcomes.
- Unit test cases included here.

#### Implementation Details

(Excluded from Jira — kept in this doc or Notion.)

#### Notes

Optional free-form notes. If present, append to the Jira description after Acceptance Criteria.

---

### Ticket PP-XXXX (02) — Service: Short Title

**Service**: service-name | **Blocked by**: Ticket 01 | **Blocks**: —

#### Summary
...
```

Key rules the skill relies on:
- Top-level `#` heading provides the epic title.
- Each ticket section opens with `### Ticket PP-XXXX (NN) —`.
- The bold metadata line (`**Service** | **Blocked by** | **Blocks**`) immediately follows the heading.
- `#### Summary`, `#### Acceptance Criteria`, `#### Implementation Details`, and `#### Notes` (optional) are the expected sub-section names.
- Tickets with placeholder `PP-XXXX` numbers are created; tickets with real `PP-NNNN` numbers are skipped.

## What this skill does

1. **Read** the tickets markdown file to extract:
    - The epic title (from the top-level `#` heading — strip the ticket prefix if present, e.g. `PP-NNNN — Workstation Roles CDC Lambda` → use as epic summary)
    - Each ticket section (`### Ticket PP-XXXX (NN) — ...`):
        - **Summary** (the `#### Summary` block)
        - **Acceptance Criteria** (the `#### Acceptance Criteria` block — formatted as a bulleted list)
        - **Service** and **Blocked by** / **Blocks** metadata from the bold line under the heading
        - **Notes** block if present (append to description)

2. **Check acli auth** — run `acli jira project list --limit 1` to confirm the CLI is authenticated. If it fails, tell the user to run `acli jira auth login` first.

3. **Resolve the epic key** — use the `--epic` argument if provided. Otherwise ask: "What is the Jira epic key to nest these tasks under? (e.g. PP-1411)"

4. **Create each child ticket** in dependency order (unblocked tickets first):
    - **Summary**: strip the `PP-XXXX (NN) — ` prefix from the heading; the remainder (`service-name: Short Title`) is the full Jira summary.
    - **Description**: Summary paragraph + Acceptance Criteria only (append Notes block if present) — do NOT include Implementation Details. End with: `\n\nFull implementation details: <Notion URL from --notion arg, or "see tickets.md" if not provided>`.
    - Write the description to a unique temp file (for example, using `mktemp`) to avoid shell escaping issues and filename collisions, then run:
      ```
      BODY_FILE="$(mktemp)"
      # write the generated description into "$BODY_FILE" here
      acli jira workitem create \
        --project PP \
        --type Task \
        --summary "<service-name>: <Short Title>" \
        --description-file "$BODY_FILE" \
        --parent <epic key>
      rm -f "$BODY_FILE"
      ```
    - Capture the Jira key printed in the command output (e.g. `PP-1412`) and add it to the mapping table.

5. **Print a mapping table** of placeholder → real Jira key:
   ```
   | Placeholder | Jira Key | Title |
   |-------------|----------|-------|
   | Ticket 01   | PP-1412  | ...   |
   ```

6. **Ask the user** if they want to:
   a. Update the `tickets.md` file to replace `PP-XXXX` placeholders with real keys.
   b. Add `Blocked by` links between tickets using acli (requires the key mapping from step 5).
   c. Both.

7. If the user confirms (a) or (c): update the tickets markdown file using the mapping table from step 5:
    - Replace each `PP-XXXX` placeholder in section headings with the real Jira key.
    - Replace each `Ticket 0X` cross-reference in **Blocked by** / **Blocks** metadata lines and the summary table with the real Jira key.

8. If the user confirms (b) or (c): for each ticket that has a `Blocked by` reference, run:
   ```
   acli jira workitem link create --out <blocked ticket key> --in <blocking ticket key> --type Blocks --yes
   ```
   **Direction convention**: `--out` = the ticket being blocked, `--in` = the ticket doing the blocking.
   The acli confirmation message will read `(blocked Blocks blocker)` which looks backwards — that is expected and correct.

## Notes

- The `acli jira workitem create` command reference: https://developer.atlassian.com/cloud/acli/reference/commands/jira-workitem-create/
- Jira project: `PP` (Permissions Platform) at `theorchard.atlassian.net`
- Implementation Details sections are intentionally excluded from Jira — they live in Notion or the local markdown doc.
- If a Notion page URL is provided via `--notion`, include it in each ticket description.
- Tickets with `PP-XXXX` placeholder numbers should all be created; tickets that already have real `PP-NNNN` numbers should be skipped (already created).
- The `acli jira workitem link` command uses a subcommand structure: `link create`, `link delete`, `link list`, `link type` — there are no `--inward-issue` / `--outward-issue` top-level flags.
- To list link types: `acli jira workitem link type`. The correct type name for this project is `Blocks`.
- To delete a link: `acli jira workitem link delete --id <link-id> --yes`. Get IDs from `acli jira workitem link list --key <PP-NNNN> --json`.
- The `acli jira workitem create` output includes the created key (e.g. `PP-1412`) — parse it to build the mapping table.
- `acli jira workitem create` does NOT support `--yes` — omit it; the command is non-interactive by default.
- To update an existing ticket's description (e.g. a previously-created ticket that needs revising), use `workitem edit`, not `workitem update` (which doesn't exist):
  ```
  BODY_FILE="$(mktemp)" && acli jira workitem edit --key <PP-NNNN> --description-file "$BODY_FILE" --yes && rm -f "$BODY_FILE"
  ```