---
description: "Turn a rendered analysis document into a Jira story tree: derive stories from the document's own rule ids, check coverage both ways, preview every byte, then create only what does not already exist. Use when an analysis is final and the work needs tickets."
description-tr: "Yazılmış bir analiz dokümanını Jira story ağacına çevirir: story'leri dokümanın kendi kural kimliklerinden türetir, kapsamı iki yönlü kontrol eder, yazılacak her baytı önizler, sonra yalnız var olmayanı açar."
allowed-tools: Bash, Read, AskUserQuestion
argument-hint: "[analysis.md] [--project KEY]  -  optional; with no argument, pick from the documents this run emitted"
not-for: create-jira, jira
---

# multi-agent analysis-jira

**Input**: $ARGUMENTS

Reads an analysis document as a work breakdown and creates the tree. It never
invents a story: every node comes from an id the document defines.

Contract, severities and reasoning:
`$HOME/.claude/multi-agent-refs/features/analysis-jira.md`.

## Phase 1 - Plan, offline

```bash
node "$HOME/.claude/scripts/analysis-story-tree.mjs" "<analysis.md>" --json > /tmp/ma-plan.json
node "$HOME/.claude/scripts/analysis-story-tree.mjs" "<analysis.md>"
```

Exit 4 means the document still carries an open placeholder. Stop and report it:
the step is `/multi-agent:analysis-resolve`, and a tree built from an open
question publishes the gap as work somebody is now assigned.

Exit 2 means nothing could be derived. Say so; do not improvise a tree.

## Phase 2 - Preview, in full

Show the human-readable output verbatim, in `outputLanguage`. It already carries
what makes a preview meaningful:

- every node, its source ids and its identity label
- the coverage verdict **on its own line**
- every field beside the pref key it came from, so a wrong setting shows here
  rather than in Jira afterwards
- the write count

Then the dry run, which is what proves the writer agrees with the plan:

```bash
bash "$HOME/.claude/lib/analysis-jira-write.sh" \
  --plan /tmp/ma-plan.json --project "<KEY>" --dry-run
```

## Phase 3 - Approve

One `AskUserQuestion`. When the verdict is `ok` or `incomplete`:

- **Create the tree** - proceed
- **Show a node in full** - print one node's body, ask again
- **Cancel** - stop, write nothing

When the verdict is `unverifiable`, the approve option is **replaced**, never
reworded:

- **Create it, unverified** - the tree will be written and recorded as unchecked
- **Show a node in full**
- **Cancel**

A run that could not be checked is allowed. One that looks checked when it was
not is the defect, so the approval has to name it and a plain "Approve" must not
be reachable.

`incomplete` prints its uncovered and invented ids before the question. An
invented id means the plan cites something the document does not define - treat
that as a defect in the plan, not a warning to click past.

## Phase 4 - Write

```bash
bash "$HOME/.claude/lib/analysis-jira-write.sh" \
  --plan /tmp/ma-plan.json --project "<KEY>"
```

It searches by label first and skips what exists. Re-running is safe and is the
intended recovery from any failure: the ledger makes a half-written tree
findable rather than duplicable.

**Never pass `--force`-like flags, and never update an existing node.** Jira has
no backup path for fields other than description.

## Phase 5 - Report

Keys created, keys skipped, the coverage verdict, and the ledger path. If the
verdict was `unverifiable`, say that in the report too - not only at approval
time, because the report is what gets pasted elsewhere.

**Stop. No worktree, no branch, no dev chain.**
