# Readiness Review (shared flow for review-jira + review-issue)

Assess whether a tracker item (Jira issue or GitHub issue) is READY to hand to the multi-agent pipeline, list the concrete gaps, and - after confirmation - post them back as a comment on the item so the reporter can fix it. Read-only on code: no worktree, no branch, no commits, no dev chaining. This is the inverse of `/multi-agent:create-jira` (which authors a well-formed item); here we grade an existing one.

Both `/multi-agent:review-jira` and `/multi-agent:review-issue` execute this flow; only the provider (fetch + comment endpoint + picker) differs.

## Language
Instruction prose here is English. The verdict shown in chat and the comment body follow `prefs.global.outputLanguage` (the comment is authored for the user's team, same exception as create-jira). AskUserQuestion `label`/`header` stay English; `question`/`description` follow `outputLanguage`.

## Step 1 - resolve the item
- With an argument: `review-jira KEY-123` / `https://<jira>/browse/KEY-123`; `review-issue #N` / `repo#N` / GitHub issue URL.
- With no argument: offer the picker - review-jira reuses the `jira` command's issue list (`jira/SKILL.md` JQL, assignee=currentUser, open); review-issue reuses the `issue` command's list (`gh issue list`). Single-select (one item reviewed per run; re-run for more).

## Step 2 - fetch + base maturity
Run `$HOME/.claude/lib/issue-fetcher.sh` (the same fetcher Phase 0 uses). It returns a descriptor with `title`, `type`, `status`, `description`, and `maturity = { score (0..100), blockers[], warnings[], summary }`. Reuse that maturity verbatim as the baseline; never re-fetch through MCP.

## Step 3 - readiness rubric (extends maturity)
Maturity is generic; add these pipeline-readiness dimensions by reading the fetched `title` + `description` (no invention - only judge what is written). Each is `pass` / `gap`:

| Dimension | Ready when | Gap signal |
|---|---|---|
| Scope is testable | the change is bounded + verifiable (what "done" means is stated) | vague ("improve X"), no measurable outcome |
| Acceptance criteria / DoD | AC or DoD present (Task/Story/Feature) | none (aligns with maturity `no_acceptance_criteria`) |
| Reproduction | Bugs have steps + expected/actual | none (aligns with maturity `no_repro_steps`) |
| Design reference | UI work links a Figma frame or attaches a screenshot | UI implied but no design source |
| API contract | backend/integration work names endpoints or a Swagger/OpenAPI ref | data/contract implied, none given |
| Platform / stack signal | the target stack is inferable (iOS / Android / frontend / backend) | ambiguous - Phase 1 could not route |
| Dependencies | blocking deps/links are called out when they exist | hidden dependency likely |

Only emit a dimension as a gap when its trigger applies (do not demand an API contract on a copy-change task). Merge: `gaps = maturity.blockers + maturity.warnings + rubric gaps`.

**Known upstream (optional).** When `ai-analyst-toolkit` is enabled and the item names a library, framework or SDK, ask `evidence-github` whether the reported behaviour is already an open issue there. A hit does not change the score - it changes the comment, which then says "this looks like `GitHub:<owner>/<repo>#<n>`, upstream" instead of asking the reporter for more detail about a bug that is not theirs. Not enabled, or nothing found, is a silent no-op.

## Step 4 - verdict (chat, always)
Print a compact verdict; reuse the maturity blocker-vs-warning severity contract (same as the Phase 0 maturity check):

```
Readiness: KEY-123  -  score 60/100  -  NEEDS WORK
BLOCK  Description is empty
WARN   No acceptance criteria detected
GAP    UI work but no design reference
GAP    Target stack ambiguous
```
Verdict rule: any blocker -> NOT READY (blocking); else any warning/gap -> NEEDS WORK; else READY. Mirrors `jira/SKILL.md` maturity handling: blockers would halt a real run, warnings would prompt.

## Step 5 - post the comment (confirmed)
Posting to a tracker is outward-facing - confirm first (autopilot auto-posts):

```
question (outputLanguage): "Eksiklikleri {KEY|#N} üzerine yorum olarak ekleyeyim mi?"
header   (English):        "Post readiness comment"
options:
  - label "Post comment", description (outputLanguage): "Eksiklik listesini item'a yorum olarak yaz"
  - label "Chat only",    description (outputLanguage): "Sadece sohbet özeti, item'a dokunma"
default: option 1
```

Comment body: a short "Multi-agent readiness review" heading, the score + verdict, then the gap list grouped Blockers / Warnings / Gaps, each with a one-line fix suggestion. Tone rules (same as `channels/issue-comment.md`): no AI/Claude/Copilot attribution, no "generated by", no em-dash/section-sign, plain ASCII; if referencing another item use `Ref: #N` never `Closes/Fixes`. READY items get a short "ready to pick up" confirmation instead of a gap list.

Provider dispatch:
- **Jira** (`review-jira`): post via `$HOME/.claude/multi-agent-refs/channels/jira.md` comment path - `POST /rest/api/2/issue/{id}/comment`, Bearer token from `keychainMapping.jira` via `credential-store.sh`, UTF-8 verbatim (`jq --rawfile` + `curl --data-binary @payload.json`), markdown->wiki conversion, then `node "$HOME/.claude/scripts/jira-wiki-escape.mjs"` on the converted body before POST.
- **GitHub** (`review-issue`): `gh issue comment "$N" --repo "$org/$repo" --body-file <file>` per `channels/issue-comment.md` (auth via the Phase 0 `gh` account).

On post failure, surface the failing endpoint on stderr; the chat verdict remains the source of truth.

## Not in scope
No status transitions, no assignment changes, no issue creation, no code review (that is `/multi-agent:review`). This command only reads the item and comments its readiness.