@groupby/ai-dev 0.5.14 → 0.5.16

package/teams/brain-studio/skills/jira-context/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: jira-context
+description: Provides standardized procedures for fetching Jira ticket data via the Atlassian MCP in agent workflows — resolving the ticket key (from caller input or branch name), fetching all relevant fields (summary, description, acceptance criteria, comments, issue type, priority, linked issues), and handling auth failures or missing tickets gracefully. Outputs a `<ticket-context>` object consumed by downstream review and planning workflow steps (whether skills or prompts). Auto-apply before any prompt that needs Jira ticket content to evaluate code, plan work, or write a PR description.
+---
+
+# Jira Context Guide
+
+## Relationship to other repository skills
+
+- **git-context** — must be read first when `<ticket-key>` is not provided by the caller; the key is extracted from `<branch-name>` produced there.
+
+This skill does not replace the git-context skill. It adds the Jira data layer on top of
+the git context.
+
+## Mandatory application (agents)
+
+Whenever a prompt requires Jira ticket content:
+
+1. **Confirm `<ticket-key>` is available.** If not, run the git-context skill first to
+   extract it from the branch name, or ask the user to provide it.
+2. **Read this skill file** before calling the Atlassian MCP.
+3. Follow the **Working method** steps in order.
+4. Store the result as `<ticket-context>` for use by the calling prompt.
+
+This skill is optional when the calling prompt explicitly says no Jira ticket is needed.
+
+## When to use
+
+- Before a code review that evaluates whether changes fulfil a ticket's acceptance criteria.
+- Before writing an implementation plan for a ticket.
+- Before writing a PR description that references a ticket.
+- Any time a prompt says "fetch the Jira ticket" or "check the acceptance criteria".
+
+## When not to use
+
+- The task has no associated Jira ticket and the caller confirms this — skip entirely.
+- The caller has already provided full ticket content inline — skip the MCP call.
+
+## Truthfulness and claims
+
+- Do not fabricate acceptance criteria — if the AC field is empty or absent, report that
+  explicitly; do not infer AC from the description.
+- Do not claim the ticket exists if the MCP returns an error — report the actual error.
+- Do not assume the ticket key format — use the value from `<ticket-key>` as-is.
+- Auth failures are expected in some environments — always note this clearly and continue
+  the workflow without ticket context rather than blocking.
+
+## Self-contained operating mode
+
+The Atlassian MCP server is configured for this project — treat it as always available. Do not skip the Jira fetch on the assumption that MCP is not set up; only skip it when the caller explicitly says no ticket is needed or when `401` / timeout errors occur (see §3 error table).
+
+Use the procedures in the **Embedded implementation standard** below as the sole
+authority for Jira ticket fetching. Do not substitute cached ticket content from a
+previous conversation turn — always make a fresh MCP call.
+
+---
+
+## Embedded implementation standard
+
+### 1) Resolve the ticket key
+
+- If the caller provided a key explicitly (e.g. as a command argument such as `S4R-10620`), use it.
+- If not, use `<ticket-key>` from the git-context skill output.
+- If neither source provides a key, ask the user before proceeding.
+
+### 2) Fetch the Jira issue
+
+Call the Atlassian MCP with the resolved ticket key. Collect all of:
+
+| Field | MCP field / location |
+|-------|---------------------|
+| Summary | `fields.summary` |
+| Description | `fields.description` (render as markdown) |
+| Acceptance criteria | `fields.customfield_10972` or embedded in description |
+| Comments | `fields.comment.comments` — focus on those that clarify scope or root cause |
+| Issue type | `fields.issuetype.name` (Bug / Story / Task / Spike) |
+| Priority | `fields.priority.name` |
+| Linked issues | `fields.issuelinks` — blocked-by / blocks / relates-to |
+| Status | `fields.status.name` |
+
+### 3) Handle errors
+
+| Error | Action |
+|-------|--------|
+| `Unauthorized` / `401` | Note "Atlassian auth unavailable"; continue workflow without ticket context; do not block. |
+| `Not Found` / `404` | Report "Ticket `<key>` not found"; stop and ask the user to verify the key. |
+| Network timeout | Retry once; if it fails again, treat as Unauthorized above. |
+
+### 4) Store ticket context
+
+Store all collected fields as `<ticket-context>`. At minimum, subsequent steps need:
+
+- `<ticket-summary>` — one-line description of what the ticket asks for.
+- `<ticket-ac>` — list of acceptance criteria items, or `none` if absent.
+- `<ticket-type>` — Bug / Story / Task / Spike; affects how the plan or review is framed.
+
+---
+
+## Working method (apply in this order)
+
+1. **Resolve** — Confirm or extract `<ticket-key>`; ask the user if both sources fail.
+2. **Fetch** — Call the Atlassian MCP; collect all fields listed in §2.
+3. **Handle errors** — Apply the error table in §3; never block on auth failures.
+4. **Store** — Set `<ticket-context>`, `<ticket-summary>`, `<ticket-ac>`, `<ticket-type>`.
+5. **Confirm** — Report to the caller: ticket key, summary, and whether AC was found.
+
+## Quality bar before final answer
+
+- `<ticket-key>` was resolved from caller input or branch name — not guessed.
+- The MCP was called with the actual key — not a paraphrased or reconstructed one.
+- Auth failures are reported as a note, not as a blocking error.
+- `<ticket-ac>` is either a concrete list or explicitly `none` — not fabricated.
+- `<ticket-context>` is set before the skill returns to the caller.

package/teams/brain-studio/skills/jira-spec/SKILL.md

@@ -0,0 +1,247 @@
+---
+name: jira-spec
+description: Fetch a Jira ticket and write a development spec to .ai/tasks/{KEY}/spec.md in the current repo. First step of the AI-assisted development workflow. Only run when the user explicitly invokes this command via /jira-spec — do NOT auto-trigger on Jira keys, ticket links, or the word "spec".
+---
+
+# Jira Spec
+
+## ⚠️ Prerequisite: Jira access
+
+This skill **cannot run without working Jira access**. The very first thing
+it does is fetch the ticket — if that fails, the skill stops. Most failures
+happen here. Before running, verify at least ONE of these works:
+
+- **Atlassian MCP** is configured (preferred): the Atlassian MCP is available
+  in the current session (fetch the accessible resources, then the issue).
+- **go-jira CLI** is installed and authenticated: `jira issue view <KEY>`
+  returns the ticket.
+- **`curl` + stored credentials**: `${JIRA_BASE_URL}` is set and a
+  credential (`JIRA_TOKEN` or `.netrc` entry) authorizes
+  `${JIRA_BASE_URL}/rest/api/3/issue/<KEY>`.
+
+If none of these is in place, the skill will refuse to proceed.
+**Never fabricate ticket content** — the value of the spec is the verbatim
+audit record from Jira.
+
+## Overview
+
+Given a Jira ticket reference (key like `S4R-1234` or a browse URL), fetch the
+ticket from Jira and produce a markdown spec at `.ai/tasks/{KEY}/spec.md`.
+The spec preserves the original ticket verbatim (for audit) and adds AI-gathered
+repo context so a future session can start implementation immediately.
+
+This is **Step 1** of the AI-assisted development workflow.
+
+## When to Use
+
+Trigger on inputs like:
+
+- A Jira key alone: `S4R-1234`, `SRE-7348`, `AIP-123`
+- A Jira URL: `https://*.atlassian.net/browse/S4R-1234`
+- Requests like "draft a spec for S4R-1234", "prep this ticket", "create
+  ticket doc for <link>"
+
+Do NOT use for: generic note-taking, non-Jira tickets (GitHub issues, Linear),
+or when the user already has a spec file and just wants to edit it.
+
+## Workflow
+
+### 1. Parse the input
+
+Extract the ticket key (uppercase letters, hyphen, digits — e.g. `S4R-1234`).
+Accept both bare keys and `…/browse/KEY` URLs.
+
+### 2. Fetch the ticket from Jira
+
+The most common failure point — see Prerequisite above. Try in this order:
+
+- **Atlassian MCP** (preferred when available): via the Atlassian MCP, fetch
+  the accessible resources, then fetch the issue for the resolved ticket key.
+  Also fetch comments if the description references them.
+- **CLI fallback**: `jira issue view KEY` (go-jira) or a `curl` against
+  `${JIRA_BASE_URL}/rest/api/3/issue/KEY` using stored credentials.
+- **If none of these works, STOP.** Print which mechanism was tried, the
+  error, and what the user needs to configure. Do NOT proceed to the repo
+  scan. Do NOT invent ticket content.
+
+### 3. Determine change types and load architecture docs
+
+Based on the ticket summary/description, classify the likely change types
+using the categories from the arch-context skill:
+
+- Component / hook (`.tsx`)
+- Styling (`.styles.ts`)
+- API / data fetching
+- State management
+- Test changes
+- Auth / permissions
+- Feature flags
+- i18n
+- Config / build
+
+Then load architecture context: if `.github/copilot-instructions.md` exists,
+use its Doc Routing Table to load the relevant `docs/architecture/` files for
+these change types; otherwise, if `docs/architecture/` exists, load the
+relevant docs directly. If `docs/architecture/12-code-conventions/README.md`
+exists, load it as baseline. If neither path exists, skip this step.
+
+This gives the repo scan (next step) much better direction.
+
+### 4. Investigate the repo (medium depth)
+
+Based on the ticket summary/description AND any loaded architecture docs:
+
+- Identify the most relevant files/modules (use Grep/Glob, check the
+  module structure from loaded docs).
+- Read the key files end-to-end where useful; skim larger ones.
+- Note conventions, patterns, and any nearby code the change will touch.
+- If `.ai/patterns.md` exists, check it for relevant past solutions.
+- Keep this targeted — don't tour the whole codebase.
+
+### 5. Determine the output path
+
+- Directory: `.ai/tasks/{KEY}/` (create if missing).
+- Filename: `spec.md` (always this name within the task folder).
+- If the file already exists, ask the user before overwriting.
+
+### 6. Generate slug for future branch naming
+
+Derive a slug from the ticket summary. This slug will be used by subsequent
+workflow steps (branch creation, plan file, etc.). Include it in the spec
+metadata.
+
+**Slug rules:** 3–6 words, ≤ 50 characters, kebab-case.
+
+- Lowercase. Replace any run of non-`[a-z0-9]` with a single `-`. Trim
+  leading/trailing `-`.
+- Strip a leading `KEY:` if the summary repeats the key.
+- Drop filler: `implement-the-`, `add-support-for-`, `feature-from-`,
+  `the-`, `a-`, `for-`, `from-`, `in-`, `of-`, etc.
+- Keep the **distinctive core**: the noun/verb that names the change.
+
+Examples:
+- "Implement the does not affect feature from Mongo for Facet Exclusion" → `does-not-affect`
+- "Add MongoDB command listener logging" → `mongodb-command-listener-logging`
+- "Fix: NPE in /search when filters empty" → `npe-search-empty-filters`
+
+### 7. Write the spec
+
+Use the template below.
+
+### 8. Report and stop
+
+Report the path of the file and a one-line summary. Remind the user of the
+next workflow step:
+
+> "Spec saved at `.ai/tasks/{KEY}/spec.md` (local-only — the `.ai/` folder is
+> gitignored; it reaches the team later via the PR). Next step: create a branch
+> and run `/draft-plan` when ready."
+
+Do not start implementation unless the user explicitly asks.
+
+## Spec Template
+
+```markdown
+# {KEY}: {Summary}
+
+- **Jira:** {browse URL}
+- **Status:** {status} · **Type:** {issuetype} · **Priority:** {priority}
+- **Assignee:** {assignee} · **Reporter:** {reporter}
+- **Labels:** {labels} · **Components:** {components}
+- **Parent / Epic:** {parent or epic link, if any}
+- **Fetched:** {YYYY-MM-DD}
+- **Slug:** {slug} (for branch: `<type>/{KEY}-{slug}`)
+
+## Original Description (verbatim, for audit)
+
+> {Jira description, rendered to markdown. Preserve formatting, bullet lists,
+> code blocks, and links. Do not edit or paraphrase.}
+
+### Acceptance Criteria (verbatim)
+
+> {If present as a separate field or section, include verbatim. Omit the heading
+> if there is none — do not invent acceptance criteria.}
+
+### Relevant Comments (verbatim, optional)
+
+> {Include only comments that add load-bearing context — decisions, scope
+> changes, clarifications from the reporter. Skip chatter. Quote verbatim with
+> author and date. Omit the section entirely if nothing qualifies.}
+
+## Implementation Notes (AI-gathered)
+
+> ⚠️ The items below are AI guesses from a medium-depth repo scan. Verify
+> against the current code before relying on any specific file path, line
+> range, or claim — they may be stale, incomplete, or wrong.
+
+### Architecture docs loaded
+- {List which docs/architecture/* files were consulted and why, or "none — no
+  architecture doc source was present"}
+
+### Touch points in this repo
+- `path/to/file` — what lives here and why it matters for this ticket
+- `path/to/other:120-180` — specific region of interest
+
+### Patterns and conventions to follow
+- {From docs/architecture/* (if loaded) and .ai/patterns.md (if present)}
+- {e.g. "Forms in linguistic-controls use Formik + Yup; validation in
+  src/search-for-retail/validation/"}
+
+### Suggested approach (sketch, not a plan)
+- {2–5 bullets outlining the most plausible shape of the change. Keep loose —
+  the actual plan belongs in a separate planning step.}
+
+### Test surface
+- {Which test files in test/unit/ and test/integration/ will need updates}
+- {Use custom render() from test-utils.tsx for component tests}
+
+## Open Questions
+
+> Include this section **only** when at least one truly blocking question
+> exists — i.e. its answer would change the implementation and cannot be
+> resolved by reading the repo or the ticket. If there are no such questions,
+> omit this entire section (heading included). Don't print a placeholder.
+
+- [ ] {question, with the reason it blocks progress}
+```
+
+## Rules
+
+- **Verbatim means verbatim.** Do not summarize, "clean up", or translate the
+  Jira description. Quote it as-is in a blockquote so an auditor can compare
+  to Jira.
+- **One spec file per ticket.** Don't append to a different ticket's file.
+- **No invented metadata.** If a field is missing in Jira, omit it from the
+  spec rather than guessing.
+- **Minimize open questions.** Prefer to resolve uncertainty by reading the
+  code. Only escalate questions that are genuinely blocking.
+- **Don't start coding.** This skill produces the spec only. Implementation
+  comes later.
+- **Local-only artifact.** `.ai/` is gitignored — the spec is never committed.
+  It reaches the team only when `/draft-pr` embeds it in the PR body. Do not
+  try to `git add` or commit it.
+- **Load architecture docs if available.** If `.github/copilot-instructions.md`
+  exists, use its Doc Routing Table; otherwise, if `docs/architecture/` exists,
+  load the relevant docs directly — this produces better implementation notes.
+- **Check patterns.** Read `.ai/patterns.md` if it exists — past solutions
+  may be directly relevant.
+
+## Common Mistakes
+
+- Writing the spec without fetching Jira (hallucinating description).
+  **Never do this** — if Jira is unreachable, stop and report.
+- Saving to wrong location. Output is always `.ai/tasks/{KEY}/spec.md`.
+- Paraphrasing the description. The "Original Description" section must be
+  verbatim.
+- Padding "Open Questions" with nice-to-knows. Omit the section unless a
+  question is truly blocking.
+- Skipping the architecture-doc-loading step when a source is available (the
+  Doc Routing Table in `.github/copilot-instructions.md`, or `docs/architecture/`
+  directly). Architecture docs give the repo scan direction — without them
+  the implementation notes will be shallow.
+- Presenting AI-gathered touch points as ground truth. They are guesses —
+  keep the verify-before-relying banner above that section.
+- Doing deep design work here. This is a spec, not a plan — medium-depth
+  repo investigation only. The actual approach belongs in `/draft-plan`.
+- Forgetting to include the slug. Subsequent workflow steps (branch creation,
+  plan) depend on it.

package/teams/brain-studio/skills/pr-review/SKILL.md

@@ -0,0 +1,310 @@
+---
+name: pr-review
+description: >-
+  Use when the user invokes `/pr-review` (or asks to "review this branch", "review before PR",
+  "PR review", "standalone review"). Performs a self-contained review of the current branch's
+  changes against the live Jira ticket, architecture docs, code conventions, and accessibility —
+  works on ANY branch without requiring the `.ai/tasks/{KEY}/` workflow artifacts (uses them only
+  if present, otherwise fetches the ticket live via the Atlassian MCP). Produces a verdict
+  (PASS / PASS WITH NOTES / FAIL) and writes a report to `.ai/tasks/{KEY}/review.md`. Read-only by
+  default; offers to fix on FAIL. Checks plan compliance when `.ai/tasks/{KEY}/plan.md`
+  is present; skips the axis gracefully when the plan is absent. Only runs when
+  explicitly invoked — do NOT auto-trigger on the word "review".
+---
+
+# pr-review
+
+Standalone, ticket-driven review of the current branch's changes — runnable at any
+point, on any branch, **without** the `/jira-spec` → `/draft-plan` → `/tdd-implement`
+workflow having produced `spec.md`/`plan.md`.
+
+## Relationship to other repository skills
+
+This skill is the **primary review skill** for this repository. It handles both
+scenarios — the full AI workflow (with spec/plan) and standalone reviews (no artifacts):
+
+| Situation | This skill's behaviour |
+|---|---|
+| Full workflow — `spec.md` + `plan.md` present | All 6 axes run, including Plan compliance |
+| Standalone — no artifacts (hotfix, handwritten, another dev's branch) | Axes 1 and 2 degrade gracefully; all others run |
+
+`pr-review` **composes** the foundational context skills instead of re-implementing them:
+
+- `git-context` — sync, branch name, `<ticket-key>`, diff, `<change-types>`
+- `jira-context` — live `<ticket-context>` (acceptance criteria) via the Atlassian MCP
+- `arch-context` — `<loaded-docs>` + `<arch-constraints>` via the Doc Routing Table
+
+Read those three first; this skill assumes their outputs are available.
+
+## Mandatory application (agents)
+
+When the user invokes `/pr-review`:
+
+1. **Read this skill file** before doing anything else.
+2. Run the **Working method** steps in order, delegating context gathering to the three
+   skills above (do not re-derive their logic here).
+3. Review is **read-only** until the user explicitly chooses `[fix]` or `[fix-and-ask]`.
+
+## When to use
+
+- Reviewing a branch before opening a PR when there is **no** `spec.md`/`plan.md`.
+- Reviewing a hotfix, a hand-written change, or another developer's branch.
+- Any standalone review of the current branch, focused on the live ticket and accessibility.
+
+## When not to use
+
+- The user did not explicitly invoke it. Do **not** auto-trigger on the word "review".
+
+## Invocation
+
+```
+/pr-review [S4R-XXXX] [full|quick]
+```
+
+- **Ticket key** — optional. If omitted, it's extracted from the branch name by
+  `git-context` (regex `[A-Z]+-[0-9]+`, e.g. `S4R-10559` from `feat/S4R-10559-slug`).
+  If the branch has no key, the key is not in the branch (common here — keys often live
+  only in commits/PR), so: scan commit subjects on the branch for `[A-Z]+-[0-9]+`, then
+  ask the user. Never invent a key.
+- **Mode** — `full` (default) or `quick`.
+
+## Modes
+
+| Mode | Trigger | Scope |
+|------|---------|-------|
+| **Full** (default) | `/pr-review` or `/pr-review full` | All 6 axes below |
+| **Quick** | `/pr-review quick` | Axes 3–5 only (Architecture + Code quality + Accessibility) |
+
+## Review axes
+
+### Axis 1: Ticket compliance
+
+- Obtain acceptance criteria. Order of preference:
+  1. `.ai/tasks/{KEY}/spec.md` if it exists (richest, already distilled).
+  2. Otherwise `<ticket-context>` from `jira-context` (live AC from Jira).
+- For each AC, verify it is addressed in the diff. Flag: not covered, partially covered,
+  or contradicted.
+- If no ticket key resolves and no spec exists, state that AC could not be verified and
+  continue with the remaining axes (do not block).
+- Skip if mode = quick.
+
+### Axis 2: Plan compliance
+
+If `.ai/tasks/{KEY}/plan.md` exists, load it and verify the implementation matches
+the approved plan. Skip this axis entirely if the plan file is absent — note
+"Plan not found — Axis 2 skipped" in the report header.
+
+- **Affected areas** — files changed in the diff should correspond to the areas
+  listed in the plan. Flag significant additions or deletions not reflected there.
+- **Out of scope** — nothing listed in the plan’s “Out of scope” section should
+  appear in the diff. Flag any such additions.
+- **Approach** — the implementation should follow the plan’s stated direction.
+  Flag architectural choices that contradict the approved approach.
+- **Revisions** — if the plan has a `## Revision` section, treat it as the
+  updated source of truth for the sections it overrides.
+- Skip if mode = quick.
+
+### Axis 3: Architecture compliance
+
+Use `<loaded-docs>` and `<arch-constraints>` from `arch-context` (it applies the Doc
+Routing Table to `<change-types>`). Check the diff for:
+
+- Pattern violations (wrong file location, wrong abstraction level).
+- Import path violations (`@/` aliases required).
+- State management violations (direct store access instead of `useAppSelector`/`useAppDispatch`).
+- i18n violations (raw strings in JSX instead of FormatJS `useLocalization`/`useIntl`).
+- Currency violations (ad-hoc formatting instead of `useCurrencyFormatter`).
+- If the code contradicts a loaded doc, the **doc is the target state** — flag the
+  discrepancy; do not normalise the legacy pattern.
+
+### Axis 4: Code quality
+
+Load the code-generation skills relevant to the changed file types, in order:
+
+- `javascript` skill → `typescript` skill
+- `react` skill (if `.tsx`)
+- `styled-components` skill (if `.styles.ts`/`.styles.tsx`)
+
+Check for:
+
+- TypeScript: strict types, no `any`, proper narrowing, explicit return types.
+- React: function declarations with explicit `JSX.Element`, no `React.FC`, correct hook usage.
+- Styling: PascalCase named exports (no `Styled` prefix), `baseColors`, `theme.spacing()`,
+  `$` transient props, no `!important`.
+- JavaScript: Airbnb style, semicolons, braces on all control bodies, proper destructuring.
+- Security: OWASP-relevant concerns (XSS via `dangerouslySetInnerHTML`, injection, unsafe
+  URL handling, secrets in code).
+- Performance: unnecessary re-renders, missing/over-eager memoization, missing effect
+  cleanups, over-importing.
+
+### Axis 5: Accessibility
+
+For any changed `.tsx`/markup, check:
+
+- **Semantics** — real elements for their role (`button` for actions, `a` for navigation);
+  no `div`/`span` used as interactive controls.
+- **Labelling** — every interactive control has an accessible name (visible `<label>`,
+  `aria-label`, or `aria-labelledby`); icons-only buttons are labelled; placeholder is
+  never the only label.
+- **Keyboard** — all interactive elements are reachable and operable by keyboard; no
+  positive `tabindex`; custom widgets handle Enter/Space/Escape as expected.
+- **Focus management** — focus is moved into newly opened dialogs/menus and restored on
+  close; no focus traps outside modals; visible focus indicator preserved.
+- **ARIA** — used only when native semantics are insufficient; roles/states valid and not
+  contradicting the element; live regions for async status updates.
+- **Images/media** — meaningful `alt`; decorative images `alt=""`.
+- **Color/contrast** — meaning is not conveyed by color alone; obvious contrast regressions
+  flagged (note: exact ratios may need manual/tool verification — say so).
+
+If `docs/architecture/` defines accessibility conventions, those take precedence over the
+generic checklist above.
+
+### Axis 6: Test quality
+
+- Tests exist for new behaviour (not just the happy path).
+- Tests are in the correct location (`test/unit/` or `test/integration/`).
+- Custom `render()` from `test-utils.tsx` is used for component tests.
+- Assertions are meaningful (not "renders without crashing").
+- Edge cases from the AC are covered.
+- No snapshot tests without justification.
+- Skip if mode = quick.
+
+## Working method
+
+### 1. Gather context (delegate, don't re-implement)
+
+1. Run **`git-context`**: sync with `origin/main`, get `<branch-name>`, `<ticket-key>`,
+   the committed diff `git diff $(git merge-base HEAD origin/main)..HEAD`, the
+   `--name-only` file list, and `<change-types>`.
+2. Run **`jira-context`** with `<ticket-key>` to get `<ticket-context>`. If auth fails
+   (`401`/timeout) or there is no key, note it and continue without ticket context.
+3. Run **`arch-context`** with `<change-types>` to get `<loaded-docs>` + `<arch-constraints>`.
+4. Load the code-generation skills for the changed file types (Axis 4).
+5. If `.ai/tasks/{KEY}/plan.md` exists, read it for Axis 2 (Plan compliance).
+   If absent, note "Plan not found — Axis 2 skipped" in the report header.
+
+### 2. Run review
+
+For each in-scope axis, analyse the diff against the loaded standards and classify each
+finding's severity:
+
+- **Critical** — must fix before merge (breaks an AC, security issue, architecture
+  violation that forces later refactor, a11y barrier that blocks a user).
+- **Warning** — should fix, not a blocker (style/convention mismatch, missing edge-case
+  test, minor a11y nit).
+- **Note** — informational (suggestion, future watch-item).
+
+### 3. Produce verdict
+
+| Verdict | Criteria |
+|---------|----------|
+| **PASS** | Zero findings, or only Notes |
+| **PASS WITH NOTES** | Warnings only, no Criticals |
+| **FAIL** | One or more Critical findings |
+
+### 4. Present results in chat
+
+```markdown
+## PR Review — {KEY or branch}
+
+**Verdict: {PASS / PASS WITH NOTES / FAIL}**  ·  Mode: {full/quick}
+Ticket AC source: {spec.md / live Jira / none}
+Plan: {plan.md found / not found — Axis 2 skipped}
+
+### Critical ({count})
+1. **[Axis N: title]** — what's wrong
+   - File: `path/to/file.tsx` (line ~XX)
+   - Fix: what needs to change
+
+### Warnings ({count})
+1. **[Axis N: title]** — description
+   - File: `path/to/file.tsx`
+   - Suggestion: what to improve
+
+### Notes ({count})
+1. **[Axis N: title]** — observation
+```
+
+Do **not** print your reasoning steps or to-do list.
+
+### 5. On FAIL — offer resolution
+
+> *"Review found {N} critical issues. Options:*
+> - *`[fix]` — I'll fix all critical issues, run verification, and re-review*
+> - *`[fix-and-ask]` — I'll propose each fix and wait for your approval*
+> - *`[skip]` — proceed anyway (not recommended)"*
+
+On `[fix]`: apply fixes following the same code-gen skills → run
+`yarn lint && yarn typecheck && yarn test` → re-review (quick mode on the fixed areas)
+→ show updated verdict.
+
+On `[fix-and-ask]`: propose each critical fix in chat, wait for approval before applying,
+then run verification.
+
+On `[skip]`: record in the report that criticals were acknowledged but not fixed.
+
+### 6. Write review report
+
+Write to a **single** location: `.ai/tasks/{KEY}/review.md`. If no ticket key resolves,
+fall back to `.ai/tasks/{branch-slug}/review.md` (slugified branch name) so everything
+still lives under `.ai/tasks/`. Create the folder if missing.
+
+```markdown
+# PR Review — {KEY or branch}
+
+**Date:** {date}
+**Branch:** {branch}
+**Verdict:** {final verdict}
+**Mode:** {full/quick}
+**Ticket AC source:** {spec.md / live Jira / none}
+
+## Summary
+{1–2 sentences on what was reviewed}
+
+## Findings
+### Critical
+{list or "None"}
+### Warnings
+{list or "None"}
+### Notes
+{list or "None"}
+
+## Verification
+`yarn lint && yarn typecheck && yarn test` — {PASS/FAIL + summary, or "not run (read-only)"}
+
+## Context loaded
+- Ticket: {key + AC source, or "none / auth failed"}
+- Plan: {plan.md found / not found}
+- Architecture docs: {list from arch-context, or "none"}
+- Code-gen skills: {list}
+```
+
+### 7. Report next step
+
+> *"Review saved at `.ai/tasks/{…}/review.md`. Next: address criticals, or run
+> `/draft-pr` to open a draft pull request."*
+
+## Hard rules
+
+- **Read-only by default.** Do not modify source until the user picks `[fix]` or `[fix-and-ask]`.
+- **Do not invent acceptance criteria.** Check only against `spec.md` or the live ticket;
+  if AC is absent, say so — do not infer it from the description.
+- **Architecture docs win over general advice.** Flag only when the code violates a loaded doc.
+- **Skills override internet advice.** The loaded code-gen skills are the standard.
+- **Auth failure is not a blocker.** If the Atlassian MCP fails, note it and review the
+  remaining axes; never silently claim AC passed.
+- **Verification must actually run.** Never claim tests pass without
+  `yarn lint && yarn typecheck && yarn test` output.
+- **Never push or create a PR.** That's `/draft-pr`.
+- **Never modify `spec.md` or `plan.md`.**
+
+## Common mistakes
+
+- Re-implementing git/Jira/arch context inline instead of delegating to the three context skills.
+- Reviewing without resolving the ticket key, then silently skipping Axis 1.
+- Treating an MCP auth failure as "no AC issues".
+- Checking generic TypeScript best practices instead of the loaded code-gen skills.
+- Missing i18n/currency violations (raw strings and ad-hoc formatting are easy to overlook).
+- Skipping the accessibility axis on `.tsx` changes.
+- Claiming contrast/keyboard pass without noting what needs manual verification.
+- Applying fixes on FAIL without explicit user consent.