refine the code-review-report skill

Author: florinc

.github/skills/code-review-report/SKILL.md

@@ -1,38 +1,40 @@
-````skill
 ---
 name: code-review-report
 description: "Generate structured code review reports in Markdown format suitable for import into GitHub PRs or Azure DevOps pull requests. Produces per-file inline remarks and a summary that renders natively in PR comment threads."
-version: 1.0.0
-output_format: Markdown
+version: 2.0.0
+output_format: Markdown + JSON
 platforms: GitHub, Azure DevOps
 ---
 
 # Code Review Report Skill
 
 ## Purpose
 
-Generates a structured, portable code review report in Markdown that:
-1. Renders correctly when pasted as a **GitHub PR comment** or **Azure DevOps PR comment**
-2. Can be saved as a persistent artifact in `docs/code-reviews/`
-3. Contains per-file remarks with line references that reviewers can act on
-4. Provides a machine-parseable remarks table for downstream automation
+Generates a structured, portable code review report consisting of **two artifacts**:
+
+1. **Markdown report** — human-readable, renders correctly as a GitHub or Azure DevOps PR comment; can be pasted directly or posted via `gh pr comment`
+2. **JSON payload** — machine-ready structured data for programmatic import via `gh api` (GitHub) or `curl` (Azure DevOps REST API)
+
+Both artifacts are saved to `docs/code-reviews/` and referenced in the chat summary.
 
 ## When to Use
 
 - After completing a code review with the `code-reviewer` agent
 - When the review output must be shared in a pull request on GitHub or Azure DevOps
 - When a persistent review artifact is needed for traceability
 
-## Output Locations
+## Output Files
 
-| Output | Path |
-|--------|------|
-| Report file | `docs/code-reviews/{issueId}-review_{timestamp}.md` |
-| Chat summary | Displayed inline in the agent conversation |
+| File | Path | Purpose |
+|------|------|---------|
+| Markdown report | `docs/code-reviews/{issueId}-review_{timestamp}.md` | Human-readable, paste into PR comment |
+| JSON payload | `docs/code-reviews/{issueId}-review_{timestamp}.json` | Programmatic PR import (GitHub + Azure DevOps) |
 
 **Timestamp format:** `yyyyMMdd-HHmm` (e.g., `20260225-1430`)
 
-## Report Template
+> Generate the JSON payload **only** when at least one remark has a resolvable file path. If all remarks are general (no file/line), produce only the Markdown report.
+
+## Artifact 1 — Markdown Report Template
 
 Use the following template **exactly** as the structure for the report file. Replace all `{placeholders}` with actual values. Omit sections that have no content (e.g., if no blockers, omit the blockers subsection) but always keep the top-level sections.
 
@@ -45,7 +47,7 @@ Use the following template **exactly** as the structure for the report file. Rep
 |-------|-------|
 | **Issue** | #{issueId} — {issueTitle} |
 | **Date** | {date} |
-| **Reviewer** | AI Code Reviewer (GitHub Copilot) |
+| **Reviewer** | AI Code Reviewer - {Model} |
 | **Build** | {✅ Pass \| ❌ Fail} |
 | **Tests** | {✅ Pass \| ❌ Fail \| ⚠️ Partial} |
 
@@ -160,6 +162,115 @@ Use the following template **exactly** as the structure for the report file. Rep
 
 ---
 
+## Artifact 2 — JSON Payload Template
+
+The JSON payload serves a dual purpose: it is the body for the **GitHub PR Review API** and contains all data needed to reconstruct **Azure DevOps PR threads**. The agent fills this structure from the collected remarks.
+
+```json
+{
+  "_meta": {
+    "issueId": "{issueId}",
+    "issueTitle": "{issueTitle}",
+    "date": "{date}",
+    "timestamp": "{timestamp}",
+    "markdownReport": "docs/code-reviews/{issueId}-review_{timestamp}.md"
+  },
+  "verdict": "{APPROVE|REQUEST_CHANGES|COMMENT}",
+  "summary": "{2-4 sentence overview}",
+  "body": "{full markdown summary block — same as the Markdown report's Summary + Metrics + Verdict sections}",
+  "event": "{APPROVE|REQUEST_CHANGES|COMMENT}",
+  "metrics": {
+    "blockers": 0,
+    "warnings": 0,
+    "suggestions": 0,
+    "notes": 0
+  },
+  "remarks": [
+    {
+      "id": "R1",
+      "severity": "blocker",
+      "dimension": "Architecture Compliance",
+      "file": "Modules/Sales/Sales.Services/OrderingService.cs",
+      "line": 42,
+      "lineEnd": 42,
+      "title": "{short title}",
+      "description": "{full description}",
+      "suggestedFix": "{direction — no full code}"
+    }
+  ]
+}
+```
+
+### JSON Field Rules
+
+| Field | Values | Notes |
+|-------|--------|-------|
+| `verdict` / `event` | `APPROVE`, `REQUEST_CHANGES`, `COMMENT` | `APPROVE WITH SUGGESTIONS` → use `COMMENT` |
+| `severity` | `blocker`, `warning`, `suggestion`, `note` | Lowercase |
+| `file` | Repo-root relative, forward slashes | e.g. `Modules/Sales/Sales.Services/Foo.cs` |
+| `line` / `lineEnd` | Integer (1-based), or `null` if unknown | Set both to same value for single-line remarks |
+| `suggestedFix` | Omit the field if remark is a `note` | |
+| `body` | GFM Markdown string | Used as the top-level PR review body |
+
+---
+
+## CLI Import Commands
+
+After the agent saves both files, output a **ready-to-run commands block** in the chat so the user can import the review into their PR immediately.
+
+### GitHub — `gh` CLI
+
+```bash
+# Option A: Post the full Markdown report as a single PR comment
+gh pr comment {PR_NUMBER} --body-file docs/code-reviews/{issueId}-review_{timestamp}.md
+
+# Option B: Post as a formal PR review with inline file comments (uses GitHub Review API)
+# Requires: GH_TOKEN with repo scope, jq installed
+gh api repos/{OWNER}/{REPO}/pulls/{PR_NUMBER}/reviews \
+  --method POST \
+  --input docs/code-reviews/{issueId}-review_{timestamp}.json
+```
+
+> **Note for Option B:** The JSON payload's top-level structure matches the GitHub PR Review API.
+> GitHub inline comments (`remarks[]`) require `path` (= `file`), `line`, and `body`.
+> The `gh api --input` flag reads JSON directly from the file — no shell escaping needed.
+
+### Azure DevOps — REST API via `curl`
+
+```bash
+# Post the full Markdown report as a PR thread (top-level comment)
+curl -s -X POST \
+  "https://dev.azure.com/{ORG}/{PROJECT}/_apis/git/repositories/{REPO}/pullRequests/{PR_ID}/threads?api-version=7.1" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $AZURE_DEVOPS_TOKEN" \
+  --data-binary @- <<EOF
+{
+  "comments": [{"content": $(jq -Rs . < docs/code-reviews/{issueId}-review_{timestamp}.md), "commentType": 1}],
+  "status": 1
+}
+EOF
+
+# Post individual inline remarks from the JSON payload
+# (run once per remark that has a non-null 'file' and 'line')
+curl -s -X POST \
+  "https://dev.azure.com/{ORG}/{PROJECT}/_apis/git/repositories/{REPO}/pullRequests/{PR_ID}/threads?api-version=7.1" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $AZURE_DEVOPS_TOKEN" \
+  -d '{
+    "comments": [{"content": "{R1 body}", "commentType": 1}],
+    "threadContext": {
+      "filePath": "/{file}",
+      "rightFileStart": {"line": {line}, "offset": 1},
+      "rightFileEnd": {"line": {lineEnd}, "offset": 1}
+    },
+    "status": 1
+  }'
+```
+
+> The agent outputs **placeholder-filled** commands (with actual values substituted) so the user only needs to set environment variables (`OWNER`, `REPO`, `PR_NUMBER`, `AZURE_DEVOPS_TOKEN`) and run.
+
+---
+
 ## Formatting Rules
 
 ### General
@@ -195,34 +306,6 @@ The report is designed to render correctly when pasted as a GitHub PR comment:
 - Same Markdown renders correctly in both platforms
 - Avoid Mermaid diagrams in the report (not supported in Azure DevOps PR comments)
 
-## Chat Summary Format
-
-In addition to saving the report file, output a **condensed summary** in the chat conversation. This is what the agent displays inline:
-
-```
-# Code Review: Issue #{id} — {title}
-
-**Design Documents:**
-- High-Level: docs/workitems/{id}-design.md — {found|MISSING}
-- Detailed: docs/workitems/{id}-detailed-design.md — {found|MISSING}
-
-**Build:** {✅|❌} | **Tests:** {✅|❌}
-**Blockers:** {count} | **Warnings:** {count} | **Suggestions:** {count} | **Notes:** {count}
-
-## Verdict
-{APPROVE | REQUEST CHANGES | APPROVE WITH SUGGESTIONS}
-
-## Summary
-{2-4 sentence overview}
-
-## Top Remarks
-{List only 🔴 blockers and 🟡 warnings here, as bullet points:}
-- **R1** 🔴 `path/File.cs` — {title}
-- **R2** 🟡 `path/File.cs` — {title}
-
-📄 Full report saved to: `docs/code-reviews/{issueId}-review_{timestamp}.md`
-```
-
 ## Edge Cases
 
 ### No Remarks Found
@@ -247,4 +330,3 @@ If the agent was asked to review only specific dimensions (e.g., "Review only ar
 ### Large File Lists (>20 files)
 - Group the Files Reviewed table by module/folder
 - Add a sub-header per module for readability
-````