@groupby/ai-dev 0.5.15 → 0.5.17

package/teams/firstspirit-caas/skills/retrospect/extract_prompts.py

@@ -0,0 +1,392 @@
+#!/usr/bin/env python3
+"""Deterministic session-transcript extractor + HTML renderer for the retrospect skill.
+
+Two modes:
+
+  extract  Parse a Claude Code session transcript (.jsonl) and emit a data JSON
+           holding EVERY user prompt (numbered 1..N) with a compact trace of what
+           followed each one. Prints a small JSON summary on stdout.
+
+  render   Combine the extract data JSON with a Claude-authored analysis JSON into
+           the final HTML report. The script owns rendering of all N prompts, so a
+           prompt can never be silently dropped; a prompt missing analysis is
+           rendered with a visible "analysis missing" marker.
+
+Completeness is mechanical: the prompt list comes from the transcript, not from a
+model's memory.
+"""
+
+import argparse
+import glob
+import html
+import json
+import os
+import re
+import sys
+from datetime import datetime
+
+WRAPPER_TAGS = ("system-reminder", "command-message", "command-name",
+                "command-args", "local-command-stdout", "local-command-stderr")
+
+CMD_NAME_RE = re.compile(r"<command-name>(.*?)</command-name>", re.DOTALL)
+
+
+def find_transcript(explicit):
+    if explicit:
+        if not os.path.isfile(explicit):
+            sys.exit(f"transcript not found: {explicit}")
+        return explicit
+    cwd = os.getcwd()
+    slug = re.sub(r"[/.]", "-", cwd)
+    proj_dir = os.path.expanduser(f"~/.claude/projects/{slug}")
+    if not os.path.isdir(proj_dir):
+        sys.exit(f"no project transcript dir for cwd (looked in {proj_dir}); "
+                 f"pass --transcript explicitly")
+    files = glob.glob(os.path.join(proj_dir, "*.jsonl"))
+    if not files:
+        sys.exit(f"no .jsonl transcripts in {proj_dir}")
+    return max(files, key=os.path.getmtime)
+
+
+def strip_wrappers(text):
+    for tag in WRAPPER_TAGS:
+        text = re.sub(rf"<{tag}>.*?</{tag}>", "", text, flags=re.DOTALL)
+    return text.strip()
+
+
+def text_blocks(content):
+    """Return list of (text) blocks. Skip tool_result-bearing messages entirely."""
+    if isinstance(content, str):
+        return [content]
+    if not isinstance(content, list):
+        return []
+    if any(isinstance(b, dict) and b.get("type") == "tool_result" for b in content):
+        return []  # this user message is a tool result, not a human prompt
+    out = []
+    for b in content:
+        if isinstance(b, dict) and b.get("type") == "text":
+            out.append(b.get("text", ""))
+    return out
+
+
+def summarize_assistant(content, limit=240):
+    texts, tools = [], []
+    if isinstance(content, str):
+        texts.append(content)
+    elif isinstance(content, list):
+        for b in content:
+            if not isinstance(b, dict):
+                continue
+            if b.get("type") == "text":
+                texts.append(b.get("text", ""))
+            elif b.get("type") == "tool_use":
+                tools.append(b.get("name", "?"))
+    text = " ".join(t.strip() for t in texts if t.strip())
+    text = re.sub(r"\s+", " ", text)
+    if len(text) > limit:
+        text = text[:limit].rstrip() + "…"
+    return text, tools
+
+
+def parse(transcript):
+    """Return ordered list of prompt dicts: {n, text, trace}."""
+    records = []
+    with open(transcript, encoding="utf-8") as fh:
+        for line in fh:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                records.append(json.loads(line))
+            except json.JSONDecodeError:
+                continue
+
+    prompts = []
+    n = 0
+    i = 0
+    while i < len(records):
+        rec = records[i]
+        if rec.get("type") == "user" and not rec.get("isMeta"):
+            msg = rec.get("message") or {}
+            blocks = text_blocks(msg.get("content"))
+            raw = "\n\n".join(blocks) if blocks else ""
+            cleaned = strip_wrappers(raw)
+            if not cleaned:
+                cmd = CMD_NAME_RE.search(raw)
+                if cmd and cmd.group(1).strip():
+                    cleaned = cmd.group(1).strip()  # slash-command invocation
+            if cleaned:
+                n += 1
+                trace = collect_trace(records, i + 1)
+                prompts.append({"n": n, "text": cleaned, "trace": trace})
+        i += 1
+    return prompts
+
+
+def collect_trace(records, start):
+    """Compact trace from `start` until the next genuine user prompt."""
+    assistant_texts, tool_names = [], []
+    j = start
+    while j < len(records):
+        rec = records[j]
+        rtype = rec.get("type")
+        if rtype == "user" and not rec.get("isMeta"):
+            msg = rec.get("message") or {}
+            if text_blocks(msg.get("content")):  # next real prompt
+                break
+        if rtype == "assistant":
+            msg = rec.get("message") or {}
+            text, tools = summarize_assistant(msg.get("content"))
+            if text:
+                assistant_texts.append(text)
+            tool_names.extend(tools)
+        j += 1
+    summary = " ".join(assistant_texts)
+    summary = re.sub(r"\s+", " ", summary)
+    if len(summary) > 400:
+        summary = summary[:400].rstrip() + "…"
+    return {"assistant_summary": summary, "tools": tool_names}
+
+
+def cmd_extract(args):
+    transcript = find_transcript(args.transcript)
+    prompts = parse(transcript)
+    outdir = args.outdir
+    os.makedirs(outdir, exist_ok=True)
+    stamp = datetime.now().strftime("%Y-%m-%d-%H%M")
+    base = os.path.join(outdir, stamp)
+    data_file = f"{base}-data.json"
+    payload = {
+        "transcript": transcript,
+        "stamp": stamp,
+        "count": len(prompts),
+        "prompts": prompts,
+    }
+    with open(data_file, "w", encoding="utf-8") as fh:
+        json.dump(payload, fh, indent=2)
+    print(json.dumps({
+        "data_file": data_file,
+        "analysis_file": f"{base}-analysis.json",
+        "html_file": f"{base}-retrospect.html",
+        "count": len(prompts),
+        "transcript": transcript,
+    }, indent=2))
+
+
+def render_block(p, analysis):
+    a = analysis.get(str(p["n"])) or analysis.get(p["n"])
+    missing = a is None
+    problem = bool(a and a.get("problem"))
+    cls = "prompt problem" if problem else "prompt"
+    if missing:
+        cls = "prompt missing"
+    parts = [f'<section class="{cls}" id="p{p["n"]}">']
+    parts.append(f'<h2><span class="num">#{p["n"]}</span> '
+                 f'<span class="badge">{ "PROBLEM" if problem else ("MISSING ANALYSIS" if missing else "OK") }</span></h2>')
+    parts.append('<div class="field"><span class="label">Prompt</span>'
+                 f'<pre class="userprompt">{html.escape(p["text"])}</pre></div>')
+    tr = p.get("trace") or {}
+    if tr.get("assistant_summary"):
+        parts.append('<div class="field"><span class="label">Result</span>'
+                     f'<p>{html.escape(tr["assistant_summary"])}</p></div>')
+    if tr.get("tools"):
+        parts.append('<div class="field"><span class="label">Tools</span>'
+                     f'<p class="tools">{html.escape(", ".join(tr["tools"]))}</p></div>')
+    if missing:
+        parts.append('<div class="field warn">⚠ analysis missing — fill this prompt '
+                     'in the analysis JSON and re-render.</div>')
+    elif problem:
+        parts.append('<div class="field"><span class="label">What went wrong</span>'
+                     f'<p>{html.escape(a.get("problem",""))}</p></div>')
+        loc = html.escape(a.get("location", ""))
+        parts.append('<div class="field"><span class="label">Improvement</span>'
+                     f'<p>{html.escape(a.get("suggestion",""))}</p>'
+                     f'{ f"<p class=loc>Target: {loc}</p>" if loc else "" }</div>')
+    else:
+        note = a.get("note") or "No issue."
+        parts.append(f'<div class="field"><span class="label">Note</span>'
+                     f'<p>{html.escape(note)}</p></div>')
+    parts.append('</section>')
+    return "\n".join(parts)
+
+
+CSS = """
+*{box-sizing:border-box}
+body{font:15px/1.5 -apple-system,Segoe UI,Roboto,sans-serif;margin:0;color:#1a1a1a;background:#fafafa;display:flex;align-items:flex-start}
+nav.toc{position:sticky;top:0;align-self:flex-start;width:260px;min-width:260px;height:100vh;overflow-y:auto;padding:1.25rem 1rem;background:#fff;border-right:1px solid #e0e0e0;font-size:13px}
+nav.toc h2{font-size:12px;text-transform:uppercase;letter-spacing:.06em;color:#999;margin:.2rem 0 .6rem}
+nav.toc ul{list-style:none;margin:0 0 1rem;padding:0}
+nav.toc ul ul{margin:.2rem 0 .4rem .8rem}
+nav.toc a{color:#333;text-decoration:none;display:block;padding:.12rem 0}
+nav.toc a:hover{color:#1565c0}
+nav.toc a.flag{color:#e53935}
+nav.toc .grp{font-weight:600;margin-top:.5rem}
+main{flex:1;max-width:900px;margin:0 auto;padding:2rem 1.5rem}
+header{border-bottom:2px solid #ddd;margin-bottom:1.5rem}
+h1{margin-bottom:.2rem}
+.meta{color:#666;font-size:13px;margin-bottom:1rem}
+.summary{background:#fff;border:1px solid #e0e0e0;border-radius:8px;padding:.75rem 1rem;margin-bottom:1rem;display:flex;align-items:center;gap:1rem;flex-wrap:wrap}
+.summary b{font-size:18px}
+button#toggleAll{margin-left:auto;font:13px inherit;padding:.35rem .8rem;border:1px solid #bbb;border-radius:6px;background:#f4f4f4;cursor:pointer}
+button#toggleAll:hover{background:#eaeaea}
+.suggestions{background:#fff;border:1px solid #e0e0e0;border-radius:8px;padding:1rem 1.25rem;margin-bottom:1.5rem}
+.suggestions h2{margin-top:0}
+.suggestions ol{margin:.4rem 0 0;padding-left:1.3rem}
+.suggestions li{margin:.5rem 0}
+.suggestions a{font-weight:700;color:#e53935;text-decoration:none}
+details.group{background:transparent;border:none;margin-bottom:1.25rem}
+details.group>summary{cursor:pointer;list-style:none;font-size:15px;font-weight:700;padding:.5rem .75rem;background:#eef1f4;border:1px solid #dde2e7;border-radius:8px;display:flex;align-items:center;gap:.5rem}
+details.group>summary::-webkit-details-marker{display:none}
+details.group>summary::before{content:"\\25B8";color:#888;font-size:12px}
+details.group[open]>summary::before{content:"\\25BE"}
+details.group>summary .gcount{color:#888;font-weight:500;font-size:13px}
+details.group>summary .gflag{margin-left:auto;font-size:11px;font-weight:700;color:#fff;background:#e53935;border-radius:4px;padding:.1rem .45rem}
+.group-body{padding:.75rem 0 0 .25rem}
+section.prompt{background:#fff;border:1px solid #e0e0e0;border-left:5px solid #4caf50;border-radius:8px;padding:1rem 1.25rem;margin-bottom:1rem;scroll-margin-top:1rem}
+section.problem{border-left-color:#e53935;background:#fff6f6}
+section.missing{border-left-color:#fb8c00;background:#fff8ef}
+section.prompt h2{font-size:16px;margin:0 0 .6rem;display:flex;align-items:center;gap:.6rem}
+.num{color:#888}
+.badge{font-size:11px;font-weight:700;letter-spacing:.05em;padding:.15rem .5rem;border-radius:4px;background:#4caf50;color:#fff}
+.problem .badge{background:#e53935}
+.missing .badge{background:#fb8c00}
+.field{margin:.5rem 0}
+.label{display:block;font-size:11px;text-transform:uppercase;letter-spacing:.05em;color:#999;margin-bottom:.15rem}
+pre.userprompt{white-space:pre-wrap;word-break:break-word;background:#f4f4f4;border-radius:6px;padding:.6rem .75rem;margin:0;font:13px/1.45 ui-monospace,Menlo,monospace}
+.tools{font:13px ui-monospace,Menlo,monospace;color:#555}
+.loc{font-size:13px;color:#1565c0;margin-top:.3rem}
+.warn{color:#e65100;font-weight:600}
+@media(max-width:720px){body{display:block}nav.toc{position:static;width:auto;height:auto;border-right:none;border-bottom:1px solid #e0e0e0}}
+"""
+
+JS = """
+const btn=document.getElementById('toggleAll');
+function refresh(){const ds=[...document.querySelectorAll('details.group')];
+  btn.textContent=ds.some(d=>!d.open)?'Expand all':'Collapse all';}
+btn.addEventListener('click',()=>{const ds=[...document.querySelectorAll('details.group')];
+  const open=ds.some(d=>!d.open);ds.forEach(d=>d.open=open);refresh();});
+// expand the group containing a targeted prompt when following an anchor
+function openTarget(){const h=location.hash;if(!h)return;
+  const el=document.querySelector(h);if(!el)return;
+  const d=el.closest('details.group');if(d){d.open=true;refresh();}el.scrollIntoView();}
+window.addEventListener('hashchange',openTarget);
+document.querySelectorAll('details.group').forEach(d=>d.addEventListener('toggle',refresh));
+refresh();openTarget();
+"""
+
+
+def get_analysis(analysis, n):
+    return analysis.get(str(n)) or analysis.get(n)
+
+
+def group_prompts(prompts, analysis):
+    """Group prompts by their analysis `topic`, in first-appearance order.
+
+    Returns list of (topic, [prompt,...]). Prompts with no topic fall into
+    a trailing 'Ungrouped' bucket.
+    """
+    order, groups = {}, []
+    for p in prompts:
+        a = get_analysis(analysis, p["n"]) or {}
+        topic = (a.get("topic") or "").strip() or "Ungrouped"
+        if topic not in order:
+            order[topic] = len(groups)
+            groups.append((topic, []))
+        groups[order[topic]][1].append(p)
+    return groups
+
+
+def cmd_render(args):
+    with open(args.data, encoding="utf-8") as fh:
+        data = json.load(fh)
+    analysis = {}
+    if args.analysis and os.path.isfile(args.analysis):
+        with open(args.analysis, encoding="utf-8") as fh:
+            analysis = json.load(fh)
+    prompts = data["prompts"]
+    flagged = sum(1 for p in prompts if (get_analysis(analysis, p["n"]) or {}).get("problem"))
+    missing = sum(1 for p in prompts if get_analysis(analysis, p["n"]) is None)
+    groups = group_prompts(prompts, analysis)
+
+    # suggestions list: rank flagged prompts by impact (desc), cap at top 10
+    flagged_pairs = [(p, get_analysis(analysis, p["n"]))
+                     for p in prompts if (get_analysis(analysis, p["n"]) or {}).get("problem")]
+    flagged_pairs.sort(key=lambda pa: (-(pa[1].get("impact") or 0), pa[0]["n"]))
+    top = flagged_pairs[:10]
+    sugg_items = []
+    for p, a in top:
+        loc = a.get("location", "")
+        sugg_items.append(
+            f'<li><a href="#p{p["n"]}">#{p["n"]}</a> {html.escape(a.get("suggestion") or a.get("problem",""))}'
+            + (f' <span class="loc">→ {html.escape(loc)}</span>' if loc else "") + '</li>')
+    if sugg_items:
+        more = (f'<p class="meta">Showing top 10 of {len(flagged_pairs)} by impact.</p>'
+                if len(flagged_pairs) > 10 else '')
+        sugg_html = f'<ol>{"".join(sugg_items)}</ol>{more}'
+    else:
+        sugg_html = '<p class="warn" style="color:#2e7d32">No issues flagged — clean session.</p>'
+    shown = len(sugg_items)
+
+    # table of contents + grouped body
+    toc_groups, body_groups = [], []
+    for gi, (topic, gprompts) in enumerate(groups):
+        gflag = sum(1 for p in gprompts if (get_analysis(analysis, p["n"]) or {}).get("problem"))
+        sub = "".join(
+            f'<li><a class="{ "flag" if (get_analysis(analysis,p["n"]) or {}).get("problem") else "" }" '
+            f'href="#p{p["n"]}">#{p["n"]} {html.escape(p["text"][:42])}</a></li>'
+            for p in gprompts)
+        toc_groups.append(
+            f'<li class="grp"><a href="#g{gi}">{html.escape(topic)}</a><ul>{sub}</ul></li>')
+        flag_badge = f'<span class="gflag">{gflag}</span>' if gflag else ''
+        blocks = "".join(render_block(p, analysis) for p in gprompts)
+        body_groups.append(
+            f'<details class="group" id="g{gi}"><summary>{html.escape(topic)}'
+            f'<span class="gcount">({len(gprompts)})</span>{flag_badge}</summary>'
+            f'<div class="group-body">{blocks}</div></details>')
+
+    html_file = args.out or args.data.replace("-data.json", "-retrospect.html")
+    doc = f"""<!doctype html><html lang="en"><head><meta charset="utf-8">
+<title>Session Retrospect {html.escape(data['stamp'])}</title>
+<style>{CSS}</style></head><body>
+<nav class="toc"><h2>Contents</h2>
+<ul><li><a href="#suggestions">Suggestions ({shown})</a></li></ul>
+<h2>Prompts</h2><ul>{''.join(toc_groups)}</ul></nav>
+<main>
+<header><h1>Session Retrospect</h1>
+<div class="meta">{html.escape(data['stamp'])} · transcript: {html.escape(os.path.basename(data['transcript']))}</div></header>
+<div class="summary"><span><b>{data['count']}</b> prompts</span><span><b>{flagged}</b> flagged</span><span><b>{missing}</b> missing analysis</span>
+<button id="toggleAll" type="button">Expand all</button></div>
+<section id="suggestions" class="suggestions"><h2>Suggestions</h2>{sugg_html}</section>
+{''.join(body_groups)}
+</main>
+<script>{JS}</script>
+</body></html>"""
+    with open(html_file, "w", encoding="utf-8") as fh:
+        fh.write(doc)
+    print(json.dumps({
+        "html_file": html_file,
+        "count": data["count"],
+        "flagged": flagged,
+        "missing_analysis": missing,
+        "groups": len(groups),
+    }, indent=2))
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__)
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    e = sub.add_parser("extract")
+    e.add_argument("--transcript", help="explicit .jsonl path; default = newest in cwd's project dir")
+    e.add_argument("--outdir", default=".claude/retrospects")
+    e.set_defaults(func=cmd_extract)
+    r = sub.add_parser("render")
+    r.add_argument("--data", required=True)
+    r.add_argument("--analysis")
+    r.add_argument("--out")
+    r.set_defaults(func=cmd_render)
+    args = ap.parse_args()
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

package/teams/firstspirit-caas/skills/review/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: review
+description: Use when the user asks to review a JIRA ticket — phrases like "review HP-1234", "start a review for this ticket", "let's review this issue". Triggers on requests to run a structured pre-merge review of all PRs linked to a ticket.
+---
+
+# Review
+
+## Overview
+
+Drives the automated phase of a JIRA ticket review: fetches the ticket and its linked PRs across all repositories, checks out branches, runs per-PR agent analysis (code, release notes, documentation), and surfaces findings in temporary markdown files with a summary table. Hands off to unstructured Claude conversation for the human review phase.
+
+**Core principle:** Gather evidence first, present clearly, never merge anything.
+
+## When to use
+
+- User asks to review / start a review for a JIRA ticket
+- User invokes with an explicit key ("review HP-1234") or from a branch where a key is parseable
+
+## When NOT to use
+
+- User wants to wrap up an already-reviewed ticket — use `review-finalize`
+- User wants to enrich the ticket description — use `specify`
+- User wants to post a work summary — use `summarise-for-jira-comment`
+
+## Workflow
+
+### 1. Identify the ticket key
+
+- Default: parse `[A-Z]+-\d+` from the current branch name
+- Override: explicit key in user message
+- Unresolvable or ambiguous: ask before proceeding
+
+### 2. Fetch ticket
+
+Call `mcp__plugin_planetexpress_jira-tools__get_jira_ticket`. Capture: summary, description, status, issuetype, any release-notes field.
+
+### 3. Spec check
+
+Compare the fetched description against the story/bug shape expected by `specify`. If the description is still vague or a one-liner, warn the user and suggest running `specify` first. Do not block the review — surface it as a finding.
+
+### 4. Dev info check
+
+Call `mcp__plugin_planetexpress_jira-tools__get_jira_dev_info`. Collect linked branches, commits, and PR references across all repositories.
+
+### 5. Discover PRs
+
+Call `mcp__plugin_planetexpress_jira-tools__search_bitbucket_prs` or use links from dev info to enumerate all PRs associated with this ticket. Collect: repository slug, PR id, PR title, PR link, branch name, target branch, PR status (open/merged/declined).
+
+### 6. Check out branches
+
+For each open PR, check out the corresponding branch locally:
+- Determine the local clone path from context (working directory, recent git operations, known repo locations)
+- If the local folder for a repository is not obvious, ask the user where it is cloned before proceeding
+- Run `git fetch` and `git checkout <branch>` in each repo
+
+### 7. CI/build status
+
+For each branch, call `mcp__plugin_planetexpress_jira-tools__get_bitbucket_commit_build_status` (or `get_bamboo_build` if a Bamboo plan key is resolvable). Record pass/fail/pending per repository.
+
+### 8. Linked tickets
+
+Call `mcp__plugin_planetexpress_jira-tools__get_jira_ticket` for each linked/blocking issue. Present the list and ask the user which (if any) are relevant to include in this review. Only carry forward those the user confirms.
+
+### 9. Triage per repo
+
+For each repository with a PR, present:
+
+| Repository | PR | Branch | CI | Changed files | Changed lines |
+|---|---|---|---|---|---|
+| `repo-name` | [PR-123](link) | `feature/HP-xxx` | ✅ pass | 14 | +320 / -80 |
+
+Always run a review agent. Ask the user per repository:
+
+> Run the review agent for `<repo>` as a **background subagent** or **in the main conversation**?
+> (Suggest background for larger/more complex PRs; inline for small/trivial ones.)
+
+### 10. Agent analysis
+
+For each PR, run the review agent (background or inline per step 9). The agent covers three areas:
+
+#### Code review
+General code quality analysis: correctness, consistency, potential issues, test coverage. (Further sharpening in future skill versions.)
+
+#### Release notes check
+1. Check the repository's `CLAUDE.md` and any referenced docs for guidance on where release notes live (PR changes vs. JIRA field).
+2. If PR changes: verify release notes are present in the diff and adequate.
+3. If JIRA field: check the field on the ticket fetched in step 2.
+4. If no guidance found: prompt the user for the expected location and suggest adding a `CLAUDE.md` entry for this repository.
+
+#### Documentation check
+1. Check the repository's `CLAUDE.md` and any referenced docs to locate customer-facing documentation.
+2. Assess whether the ticket scope or PR changes imply that documentation updates were needed or requested.
+3. If so, verify that adequate documentation changes are included in the PR.
+4. If no guidance on documentation location is found: prompt the user and suggest adding a `CLAUDE.md` entry for this repository.
+
+### 11. Present findings
+
+For each repository/PR:
+- Write findings to `/tmp/review-<REPO>-<PR_ID>.md` or - if that path does not exist - to `/c/tmp/review-<REPO>-<PR_ID>.md`(create or overwrite)
+- Structure the file with sections: Code Review, Release Notes, Documentation, Summary
+
+In the main conversation, present a summary table:
+
+| Repository | PR | Findings file | Findings |
+|---|---|---|---|
+| `repo-name` | [PR-123](link) | `/tmp/review-repo-name-123.md` | 7 |
+
+**Hand off:** Inform the user that the automated analysis is complete and they can now freely review the findings with Claude. When ready to wrap up, invoke `review-finalize`.
+
+## Edge cases
+
+| Situation | Behaviour |
+|---|---|
+| No ticket key resolvable | Ask the user; do not guess |
+| No PRs found | Inform the user; offer to continue with manual repo/branch input |
+| PR is already merged or declined | Include in the table but note status; skip branch checkout |
+| Local clone not found | Ask the user for the path before attempting checkout |
+| `CLAUDE.md` has no release notes guidance | Prompt user; suggest `CLAUDE.md` addition; record as a finding |
+| `CLAUDE.md` has no documentation guidance | Prompt user; suggest `CLAUDE.md` addition; record as a finding |
+| CI result unavailable | Note as unknown in the table; do not block |
+| `get_jira_dev_info` returns no linked branches | Warn the user; fall back to manual PR discovery via `search_bitbucket_prs` |
+
+## Red flags — STOP and reconsider
+
+| Thought | Reality |
+|---|---|
+| "I'll just pick the most likely clone path" | If not obvious, ask. A wrong path causes a checkout in the wrong repo. |
+| "Release notes look thin but I'll skip it" | Always check; surface it as a finding even if it's minor. |
+| "No CLAUDE.md entry for docs — I'll assume none needed" | Absence of guidance is itself a finding. Prompt the user. |
+| "I'll merge the branch since it looks ready" | Never. Present PR links only. Merges are the user's decision. |
+| "CI is pending — I'll wait before continuing" | Note the pending status and continue. Don't block the workflow on CI. |

package/teams/firstspirit-caas/skills/review-finalize/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: review-finalize
+description: Use when the human review phase of a JIRA ticket review is complete and the user wants to wrap up — phrases like "finalize the review", "wrap up the review", "close out the review for HP-1234", "let's finalize HP-1234". Triggers after the unstructured review conversation following the `review` skill.
+---
+
+# Review Finalize
+
+## Overview
+
+Wraps up a JIRA ticket review after the human review phase: runs the final functional-test gate, compiles all findings and interaction outcomes into a review summary, posts it as a JIRA comment, and presents PR links for the user to merge at their own discretion.
+
+**Core principle:** Summarize what happened, never merge anything.
+
+## When to use
+
+- The human review phase (free-form Claude conversation following `review`) is complete
+- User wants to wrap up, post findings, and get PR links
+- Use after `review` — this skill assumes findings files from that skill exist
+
+## When NOT to use
+
+- The automated review phase has not been run yet — use `review` first
+- User wants to post a general work summary unrelated to a review — use `summarise-for-jira-comment`
+
+## Workflow
+
+### 1. Identify context
+
+Resolve the ticket key from context (current branch, earlier conversation, or explicit user input). Locate the findings files written by `review` at `/tmp/review-<REPO>-<PR_ID>.md`. If files are missing or the ticket key is ambiguous, ask the user before continuing.
+
+### 2. Functional test gate
+
+Ask the user explicitly:
+
+> Has the feature been manually tested against the ticket spec?
+
+Do not proceed to posting until the user answers. Record the response (yes / no / partial / not applicable) and include it in the summary.
+
+### 3. Compile summary
+
+Aggregate findings from all `/tmp/review-<REPO>-<PR_ID>.md` files and from the interaction outcomes appended during the human review phase. Structure the JIRA comment as:
+
+```
+*Review summary for <KEY>*
+
+*Repositories reviewed:*
+- <repo-name>: [PR-123|link] — <N> findings (<brief disposition, e.g. "all addressed", "2 open">)
+
+*Release notes:* <adequate / missing / not applicable>
+*Documentation:* <adequate / missing / not applicable>
+*Functional test:* <yes / no / partial / not applicable>
+
+*Notes:*
+- <any non-obvious outcomes or unresolved items from the review conversation>
+```
+
+Keep bullets scannable. Do not enumerate code-level details — those live in the findings files. Do not include file paths, class names, or commit hashes unless they are the specific point of a note.
+
+### 4. Present for approval
+
+Show the exact comment text that will be posted to JIRA, verbatim. End with:
+
+> Reply 'post' to publish to \<KEY\>, or give edits.
+
+Strict gate:
+- Affirmative-and-explicit ("post", "yes, post", "ship it") → post
+- Edits → revise, re-present, wait again
+- Anything else → do not post; treat as edits or a question
+
+### 5. Post comment
+
+Call `mcp__plugin_planetexpress_jira-tools__add_jira_comment` with the approved text. Confirm in chat with the comment URL/ID returned.
+
+### 6. Present PR links
+
+Present all reviewed PRs as a list for the user to act on:
+
+> PRs ready for your review and merge decision:
+> - `repo-name`: [PR-123 — Feature/HP-xxx](link) — status: open
+> - `repo-name-2`: [PR-45 — Feature/HP-xxx](link) — status: open
+
+**Claude does not merge, approve, or close any PR.** The user follows the links and acts at their own discretion.
+
+## Edge cases
+
+| Situation | Behaviour |
+|---|---|
+| Findings files missing | Ask the user if `review` was run; if not, suggest running it first |
+| Ticket key ambiguous | Ask before proceeding |
+| Functional test answer is "no" | Record it honestly in the summary; do not block posting |
+| All PRs already merged | Note status in the PR list; still present for completeness |
+| `add_jira_comment` fails | Surface error verbatim; do not claim success |
+| User says "looks good" instead of "post" | Strict gate — wait for explicit "post" / "yes, post" / "ship it" |
+
+## Red flags — STOP and reconsider
+
+| Thought | Reality |
+|---|---|
+| "Functional test was implied by earlier conversation — I'll skip the gate" | Always ask explicitly. Record the answer. |
+| "I'll merge the PR since it looks approved" | Never. Present links only. Merges are the user's decision. |
+| "The findings files have enough detail — I'll copy them into the comment" | The comment is high-level. Details live in the files. |
+| "User said 'looks good' — that's approval to post" | Strict gate: needs explicit "post" / "yes, post" / "ship it". |
+| "I'll skip the PR list since they're already visible in JIRA" | Always present the list explicitly — the user needs to act on them. |