# Issue → Jira → Wiki Triad

> **TLDR**  -  When a GitHub issue triggers the pipeline and has no Jira ID, the `autoJiraFromGithubIssue` policy decides whether to auto-create a Jira task (and patch the GitHub issue body with the new Jira link). Phase 7 then posts a humanizer'd wiki-content summary back as a Jira comment, closing the loop. Autopilot treats `ask` as `always`.

This doc is referenced from `$HOME/.claude/multi-agent-refs/phases/phase-0-init.md` Step 1 (GitHub issue input) and `$HOME/.claude/multi-agent-refs/phases/phase-7-report.md` Step 2 (component wiki). Keeps the phase docs tight and gives the triad contract a stable home.

## The triad at a glance

```
GitHub issue (no Jira link)
     │
     ▼  Phase 0 Step 1   -  auto-create policy
Jira issue (new, linked both ways)
     │
     ▼  Phase 3  -  component implementation
wiki markdown in pipeline/skills/...
     │
     ▼  Phase 7 Report Step 2  -  wiki capture + Jira comment post
Jira comment (humanizer'd component summary)
```

## Phase 0 auto-create policy

Inputs:

- `state.inputType === "github-issue-url"` or `"github-issue-number"`  -  not `jira-*`, not `free-text`.
- `state.jiraId` is null (no `{JIRA_KEY}-XXXXX` found in the issue body).
- `prefs.global.autoJiraFromGithubIssue`  -  enum `ask` | `always` | `never`.
- `state.mode`  -  `autopilot` overrides `ask` to `always` (no interactive fallback when user isn't watching).

Decision table:

| preference | interactive | autopilot |
|---|---|---|
| `ask`    | native `AskUserQuestion` picker (`question` "Create a Jira issue for this?" in `outputLanguage`, `header` "Jira", `options` `{ label: "Create", description: "Create + link a Jira issue for this GitHub issue" }`, `{ label: "Skip", description: "Continue without a Jira issue" }`); **Create** → Create path, **Skip** → skip + log | treat as `always` |
| `always` | silently create + log | silently create + log |
| `never`  | skip + log | skip + log |

**Create path:**

1. Emit progress line `→ creating Jira issue for GH{issueNo}`.
2. Resolve Jira token via `keychainMapping.jira`. Token missing → run Token Save Flow from `setup.md` inline (clipboard-based; user can add now or skip). Skip → treat as `never` for this run.
3. Derive Jira fields from the GitHub issue:
   - `summary` ← GitHub issue title (truncate to 255 chars).
   - `description` ← GitHub issue body run through the markdown → Jira wiki conversion table (`channels/jira.md`)  -  the body is GitHub Markdown (`###`, `- [ ]`, backticks) and Jira's description field renders wiki markup, so an unconverted body arrives as literal text under a correctly-rendered prefix. Prefix the converted body with the two lines `h3. From GitHub` and `[GH{issueNo}|{url}]`, then a blank line (real newlines in the payload file, never literal `\n`).
   - `issueType`  -  infer from labels: `bug` → Bug, `enhancement` → Story, default Task.
   - `project`  -  `figmaConfig.jira.projectKey`, or `prefs.global.defaultJiraKey`, or prompt (cached after first use).
   - `priority`  -  derive from labels if present (`priority:high` → High, etc.); else leave unset (Jira default).
4. `POST {jira.baseUrl}/rest/api/2/issue` with the derived payload.
5. On success: store new Jira key in `state.jiraId`. Emit `→ created Jira {newKey}`.
6. Patch the GitHub issue body: append a line `Jira: [{newKey}]({jira.baseUrl}/browse/{newKey})` so the bidirectional link is visible on GitHub without refetching the pipeline state.

**Skip path** (`never` or user declined): Branch falls back to `feature/GH{issueNo}-{kebab}`; Phase 7 later emits `→ no Jira linked (policy: {preference})`.

**Failure isolation:** Jira API 5xx or network error → log the error, warn the user, and **continue with no Jira link** (do not halt Phase 0). Rationale: a transient Jira outage should not block code work; user can link manually post-hoc.

## Phase 7 wiki → Jira comment

Runs after Phase 7 Report Step 2 (wiki capture) has produced markdown and only when:

- `state.jiraId` is non-null (from Phase 0 scan or auto-create).
- `prefs.global.wikiToJiraComment !== false` (default true).
- Step 2 actually wrote files (skipped taskTypes don't trigger this).

Flow:

1. Emit `→ posting wiki summary to Jira {jiraId}`.
2. Read the first N lines of the primary wiki markdown file (the component's overview page  -  one of `writtenPaths[0]`).
3. Render as Jira comment: title line (`h3. Component docs  -  {componentName}`) + an overview paragraph + a link to the full page (wiki URL, if the adapter returned `pushedRemote`). The overview lines come from a Markdown file  -  convert them via the `channels/jira.md` table before POST, exactly like the title line already is, then run the whole body through `node "$HOME/.claude/scripts/jira-wiki-escape.mjs"` per that file's *Emoticon escaping* section.
4. **Run through the humanizer skill**  -  same policy as Step 4 Confluence: user-facing content must read naturally.
5. `POST {jira.baseUrl}/rest/api/2/issue/{jiraId}/comment`.
6. Log: `Phase 7: wiki summary posted to Jira {jiraId}`.

On failure: log + continue. Wiki is already written; the Jira comment is an augmentation. Don't regress Phase 7 over a Jira 5xx.

## Autopilot behaviour

Autopilot forces:

- `autoJiraFromGithubIssue: ask` → `always` (no user to prompt).
- `wikiToJiraComment` obeys its preference (default `true`)  -  no prompting either way.

Rationale: autopilot is explicit consent for side-effect creation; muting Jira activity would defeat the purpose.

## Preferences involved

| key | type | default | controls |
|---|---|---|---|
| `prefs.global.autoJiraFromGithubIssue` | enum ask/always/never | `ask` | Phase 0 auto-create decision |
| `prefs.global.wikiToJiraComment` | bool | `true` | Phase 7 wiki → Jira comment post |
| `figmaConfig.jira.projectKey` | string |  -  | Target project for new issues (falls back to `prefs.global.defaultJiraKey`) |
| `prefs.global.keychainMapping.jira` | string |  -  | Jira token keychain lookup |

## Cross-CLI parity

Both Claude Code and Copilot CLI implementations MUST:

- Resolve the `autoJiraFromGithubIssue` enum the same way.
- Derive Jira fields from GitHub issue metadata identically (title → summary, body → description via the markdown → wiki conversion + `h3. From GitHub` prefix, label → issueType mapping).
- Patch the GitHub issue body with the `Jira: [KEY](url)` line after create.
- Treat failures as non-blocking with the same log shape.
- Run the humanizer skill on the wiki-summary Jira comment.

`smoke-issue-jira-triad.sh` asserts every contract item.