Review ticket

/review-ticket — Ticket-Grounded Code Review

Runs a full code review with the ticket as the ground truth for intent. The reviewer sees not just the diff but the ticket's stated problem, scope, and acceptance criteria — so it can flag both code-quality issues and drift from what was actually asked for.

On invocation, announce: "I'll resolve your tracker, fetch the ticket, run the scope-drift check against acceptance criteria, then call /ccmagic:review with the ticket context attached. The final report includes a Ticket-scope drift section."

This skill is read-only against the codebase. It reports and verdicts; it never edits source, and never runs git add, git commit, git push, gh pr create, or gh pr merge — the frontmatter grants only read-only git/gh subcommands plus the two comment-posting ones it needs. /ccmagic:review runs here without --fix, even when the findings look mechanically fixable. Applying fixes is the caller's job: interactively that's you, and under /ccmagic:auto-ticket it's the orchestrator's bounded fix loop, which applies the findings, pushes via /ccmagic:push, and re-invokes this skill for a delta pass. Fixing your own findings and then verifying them yourself is self-certification — the separation is what makes the re-review worth anything.

When to use this vs /ccmagic:review

• Use /ccmagic:review when you want a code-quality review against generic best practices.
• Use /ccmagic:review-ticket when there's a tracker ticket driving the work and you want the review to also catch scope creep, missing acceptance criteria, or work that doesn't match what was requested.

---

Step 0: Load project settings & resolve tracker

Same cascade as /ccmagic:work-ticket:

1. Read .claude/ccmagic.local.md (if present) for tracker:, ticket_url_base:, ticket_id_regex:, github_repo: — and fall back to the user-level ~/.claude/ccmagic.local.md for any key the project file omits (project overrides user).
2. If tracker: is auto or unset, run the detection cascade:
   • Arg shape: integer-only ticket ID → GitHub; [A-Z][A-Z0-9]+-[0-9]+ → Linear or JIRA.
   • MCP probe: Linear MCP — a server available to the session (case-insensitive mcp__*[Ll]inear*__get_issue, incl. Cyrus's mcp__linear__ and a still-connecting server; see contract §7); Atlassian/JIRA MCP (mcp__*atlassian*__* or mcp__*Atlassian*__*).
   • CLI probe: command -v gh && gh repo view --json nameWithOwner 2>/dev/null.
   • Branch hint: match against ticket_url_base if ambiguous.
   • Prompt-relay fallback: if the contract §7 detection rule matches (skills/auto-ticket/autonomous-contract.md §7), resolve tracker: linear with transport: prompt-relay instead of stopping.
3. If none found, stop: tell the user to install a tracker integration or set tracker:.

Transport resolution depends on how this skill was invoked. When invoked with a grounding block that carries a transport: value (orchestrated/autonomous runs — contract §2), trust that value and do not re-detect — the orchestrator resolved transport once for the whole run, so every sub-step stays consistent. Only when running standalone (no grounding block) do you resolve transport yourself: whenever the tracker is linear — pinned in config or detected via the cascade — apply the contract §7 detection rule (skills/auto-ticket/autonomous-contract.md §7, including its server-availability rule and load-with-retry) to set transport: mcp | prompt-relay. A pinned tracker: skips the cascade above, never standalone transport resolution.

---

Step 1: Detect the ticket

1. If $1 looks like a ticket ID (matches ticket_id_regex or is a pure integer), use it.
2. Otherwise parse the current branch (git branch --show-current) for a ticket ID. Strip prefixes like feature/, bugfix/, hotfix/, chore/.
3. If neither yields a ticket ID, ask:

   "I couldn't detect a ticket from the branch ({branch}) or arguments. What ticket should I use?"

---

Step 2: Fetch the ticket

Linear

Use mcp__*Linear*__get_issue. Extract title, description, state.name, labels, priority, comments. The description may contain acceptance criteria as bullet lists, checkboxes, or "Acceptance Criteria" headers — parse them out.

Under prompt-relay (contract §7): skip the MCP call — take title and description from the grounding block's ticket_content: section (contract §2). Parse acceptance criteria out of that text exactly as for an MCP fetch (bullets, checkboxes, "Acceptance Criteria" headers). Ticket comments are not available under prompt-relay — the AC sources are title + description only. If the ticket_content: section is absent, stop with the setup-error message per contract §7 fetch_ticket — never guess. The "If not found" stop text below applies only to the MCP path.

GitHub

gh issue view {N} --repo {github_repo or auto-detected} --json title,body,state,labels,url,comments

Treat body as the description. AC may appear as - [ ] checkboxes or "Acceptance Criteria" sections.

JIRA

Use the Atlassian MCP tool to fetch the issue. Extract summary, description, status, issuetype, comments. AC may be in a dedicated field, a checklist, or buried in the description.

If not found

Stop. Tell the user the ticket ID failed and which tracker you tried.

---

Step 3: Extract acceptance criteria

From the ticket title, description, and recent comments, extract:

• Goal — one-sentence summary of what the ticket is asking for.
• Acceptance criteria — bulleted list. If the ticket has explicit AC, use it verbatim. If not, infer 2-4 criteria from the description and present them to the user with a brief confirmation prompt:

  "The ticket has no explicit acceptance criteria. I inferred these from the description — does this look right? {list}"

• Out-of-scope notes — anything explicitly called out as "not in scope" or "future work".

If the user disagrees with the inferred AC, ask them to clarify before continuing.

---

Step 4: Run ticket-scope drift analysis

Compute the diff against the base branch:

# Determine base branch (same logic as /ccmagic:pr)
BASE=$(gh repo view --json defaultBranchRef -q .defaultBranchRef.name 2>/dev/null || \
       (git show-ref --verify --quiet refs/heads/develop && echo develop) || \
       echo main)

git diff --name-only $BASE...HEAD
git diff --stat $BASE...HEAD
git diff $BASE...HEAD

Cross-reference the diff against the AC and out-of-scope notes:

• In-scope — changes that map to an AC item. List each AC item and which files/changes address it.
• Out-of-scope — files or hunks that don't tie to any AC. Flag for justification.
• Missing-from-ticket — AC items with no evidence in the diff. List each unfulfilled AC.

Hold this analysis — it will be merged into the final report after /ccmagic:review runs.

Systemic findings. When any finding — drift or code-quality — is an instance of a repeatable pattern, enumerate all instances across every reference mechanism that could carry the pattern (template attributes, raw attributes, ES-module imports, CSS @import/url(), manifests, service workers, config), not just the syntax of the first hit, and tag the finding systemic: per the review finding schema. Any "no other instances" claim must state its search scope and the mechanisms covered, or be downgraded to "no other {mechanism} instances found".

---

Step 5: Invoke /ccmagic:review with ticket context

Invoke /ccmagic:review via the Skill tool with a grounding block prepended to the arguments. The grounding block looks like:

TICKET CONTEXT:
ID: {TICKET-ID}
Title: {title}
URL: {ticket_url}

Goal: {one-sentence goal}

Acceptance Criteria:
- {AC item 1}
- {AC item 2}
- ...

Out-of-scope: {anything explicitly excluded}

(The above is the source of truth for intent. The review's Step 2.5 Scope Drift Detection should treat this ticket as the primary intent source, ahead of plan files, PR description, or commit messages.)

Pass through any --threshold N argument the user provided.

/ccmagic:review will run its full pipeline (4 core agents + conditional specialists + Codex CLI if available + MCP fallback + triage). Wait for its report.

---

Step 6: Produce the combined report

Prepend a dedicated Ticket-scope drift section to the review report:

# Ticket-Grounded Review: {TICKET-ID}

## Ticket
- **{TICKET-ID}** — "{title}" ([link]({ticket_url}))
- **State:** {state}
- **Goal:** {one-sentence}

## Acceptance Criteria
- [ ] {AC 1} — {Addressed | Partially addressed | Missing}
- [ ] {AC 2} — {Addressed | Partially addressed | Missing}
- ...

## Ticket-Scope Drift

### In-scope (matches AC)
| File | Lines | AC item |
|------|-------|---------|
| ... | ... | ... |

### Out-of-scope (no AC match — needs justification)
| File | Lines | Concern |
|------|-------|---------|
| ... | ... | ... |

If empty: "No out-of-scope changes detected."

### Missing from ticket (AC items not covered by diff)
- {AC item N} — no evidence in the diff. Recommendation: address before merging, or update the ticket to clarify deferral.

If empty: "All AC items have corresponding changes."

---

{Full code review report from /ccmagic:review here, including its own Scope Check, Critical/High/Medium findings, etc.}

The drift section is informational — it does not block. But it gives the user a clear pre-merge signal for whether the work matches the ticket.

---

Step 7: Handle drift findings

After presenting the report, if there are out-of-scope changes or missing AC items, ask the user:

"Found {N} out-of-scope changes and {M} missing AC items. A) Continue addressing missing AC items now B) Revert out-of-scope changes C) Update the ticket to reflect actual scope D) Acknowledge and proceed (note in PR description)"

Use AskUserQuestion. Take the appropriate follow-up action based on the choice. For (C), help the user draft a ticket comment explaining the scope change.

---

Autonomous mode

/ccmagic:review-ticket runs interactively by default. Autonomous mode is opt-in and additive — it changes behavior only at the human-gates below (AC confirmation and drift handling) and adds a machine-readable verdict; the review pipeline itself is unchanged. This skill still only reports and verdicts — it does not mutate code; the caller (or /ccmagic:auto-ticket) applies fixes.

When autonomous mode is active

Autonomous mode is ON when the first present signal (in priority order) resolves truthy:

1. --autonomous in the skill arguments.
2. An autonomous: true line in the grounding/context block a parent skill prepends when invoking this skill.
3. autonomous: true in ccmagic.local.md frontmatter — the project file .claude/ccmagic.local.md first, then the user file ~/.claude/ccmagic.local.md.

Absent all three, run the interactive path exactly as documented above. Also read needs_human_state: / needs_human_label: from config. Orchestrated vs. standalone works exactly as in /ccmagic:work-ticket → Autonomous mode: a parent's grounding block (#2) means the parent parks on needs-human; --autonomous/config (#1/#3) means this skill parks (route-and-stop) itself.

Behavior at each human-gate

• Step 3 (Confirm inferred AC): do not pause. Use the inferred acceptance criteria and write them into the report verbatim, marked (inferred).
• Step 5 (Invoke /ccmagic:review): prepend the same autonomous grounding block so the review runs without pausing.
• Step 7 (Drift handling): apply rules instead of asking:
  • Out-of-scope changes stay, but flag each one — leave the out-of-scope table populated and post a PR comment listing them — unless this pass's report is being posted as a PR comment (the Report posting rule below): a full report carries the out-of-scope table itself, and a delta report carries net-new out-of-scope items plus the reference to the prior report's table; either way, don't post both. Do not revert.
  • Missing AC → treat as not-done: fixable-findings if the caller can close it in-scope; needs-human if it can't.
  • CRITICAL findings from /ccmagic:review must be fixed before proceeding → return them under fixable-findings (the caller fixes and re-reviews). A CRITICAL finding that needs human judgment → needs-human.
• Report posting: if a PR exists for the branch, post the Step 6 combined report (or the delta report on re-review passes) as a PR comment (gh pr comment); with no PR (e.g. a standalone pre-PR review), skip — the report in your output is the artifact. If the gh pr comment post itself fails, say so in your output and continue — a later delta pass then leans on the grounding block's previous_findings: alone (the prior-comment reference is a convenience, not a dependency).
• Re-review passes (review_pass: ≥ 2 in the grounding block): post a delta report instead of a full fresh one — each entry in the grounding block's previous_findings: list verified and reported fixed / not-fixed as one-liners, net-new findings in full (schema unchanged), and a reference to the previous pass's report comment on the PR (fetch via gh pr view --json comments if needed) instead of repeating unchanged sections. Verdict and handshake semantics are unchanged, and the systemic-enumeration and scoped-all-clear rules apply in full on every pass.

Verdict → handshake mapping

Emit the verdict as the last thing in the report:

status: clean | fixable-findings | needs-human
reason: <one line, when not clean>
follow_ups: [<any tickets or deferrals noted>]

• clean — no CRITICAL findings and no missing AC (out-of-scope items, if any, are flagged only).
• fixable-findings — one or more CRITICAL findings and/or missing-AC items that are mechanically fixable in-scope. List them in the report so the caller can address them.
• needs-human — a finding or missing AC needs human judgment or can't be closed in-scope; reason names it. If top-level, route-and-stop (park to needs_human_state, or needs_human_label if that state doesn't exist — on GitHub create the label first if missing; comment on the PR + ticket) before emitting the handshake. Under prompt-relay (contract §7), that top-level park applies contract §4's Under the prompt-relay transport adjustments — no state move or label, parked note to the PR only, emitted (with Requested state: {needs_human_state}) wrapped in the §7 final-message delimiters as your final output.

---

Error handling

Situation	Action
No tracker available — unless the prompt-relay detection rule matched (contract §7)	Stop. Tell user to install one or set tracker: in .claude/ccmagic.local.md.
Ticket not found	Stop. Tell user clearly which tracker was tried.
No diff (on base branch with no changes)	Stop. Tell user there's nothing to review.
No AC and user can't confirm inferred AC	Ask user to provide AC explicitly, or proceed without AC checking (drift section will skip AC matrix). (Autonomous: use the inferred AC, mark them (inferred).)
/ccmagic:review fails	Surface the error. Do not silently retry.
User disputes drift classification	Mark the drift item as "user-acknowledged" in the report. Do not silently drop.
Autonomous: CRITICAL findings or fixable missing AC	Emit fixable-findings with the list — the caller addresses and re-reviews.
Autonomous: finding/AC needs human judgment or can't be closed in-scope	Emit needs-human; route-and-stop if top-level, else hand the verdict to the parent.