--- name: session-review-notes description: "Upsert a single PR comment that serves as an AI session ledger (human steering, deltas, tests) across Codex + Claude Code. Not a PR description." tools: [Bash, Read, Write, Grep, Glob] allowed-tools: Bash Read Write Grep Glob --- # Session Review Notes Skill ## When to Use This Skill Use this skill at the end of an AI-assisted coding session (Codex or Claude Code) when you want to: - Give reviewers the **intent and rationale** that a diff\/PR alone can’t capture. - Make “prompt requests” practical by summarizing **how the human steered** the work. - Highlight **what to review** (risks, tricky areas, assumptions, tradeoffs). - Post a **single, auto-updating PR comment** (create-or-update) that stays scannable. This is **not** a replacement for a PR description: - Use `pr-description-writer` for the PR body (narrative, diagrams, full test plan). - Use `session-review-notes` for a single upserted comment that tracks **human steering across sessions** and avoids the “latest minor session” trap. ## Inputs \/ Assumptions - You are in an active chat that includes the session’s conversation history. - If the work involves a git repo, you can access it via `Bash`. - You have GitHub CLI (`gh`) installed and authenticated for the target repo. - If you can’t reliably infer the PR, base branch, or commit range, ask the user. ## Architecture (Hybrid: LLM + Deterministic Script) This skill is intentionally **hybrid**: - **LLM responsibility (high-level narrative only):** produce a small JSON payload capturing intent, human steering, decisions, tests, and reviewer hotspots. - **Script responsibility (invariants, no exceptions):** create-or-update the single PR comment, preserve\/merge the session log, compute PR facts + delta, apply redaction, and talk to GitHub via `gh api`. Use the deterministic script: - `scripts\/upsert-pr-comment.py` ## Payload JSON (LLM-Owned) The script consumes a **small JSON payload** containing only human narrative (it will compute PR facts + delta itself). Minimum recommended shape: ```json { "intent": "1–2 sentences: what we were trying to do and why", "risk": "Low\/Medium\/High + 1-liner justification", "tests_summary": "Short, evidence-based summary (or 'None recorded')", "pr_scope_bullets": ["PR-wide changes, not just this chat"], "hotspots": ["Where reviewers should focus \/ risks"], "prompts": "Optional. Minimal prompts-to-reproduce (redacted).", "session_label": "Short label for this session entry", "human_steering": ["Constraints, clarifications, reversals, corrections"], "decisions": ["Tradeoffs chosen + why"], "delta_narrative": "Short: what changed since prior update", "tests_markdown": "- [ ] pytest ...\\n- [x] ruff ... (pass)", "notes": "Anything reviewers should know (uncertainties, follow-ups)" } ``` Rules: - Keep `pr_scope_bullets` and `hotspots` scannable (short bullets, no diffs). - `tests_markdown` must be **GitHub task list** markdown. The script treats `[x]` as **self-reported**, not verified, and will render it explicitly as such. - Redact secrets\/tokens, customer PII, and internal URLs (the script also redacts as a safety net). ## Comment Identity (Distinct + Idempotent) This skill must ensure **only one** such comment exists per PR by using a hidden marker that you can search for and update: ```text ``` Rules: - The marker must appear **once near the top** of the comment body. - Before posting, search existing PR comments for the marker: - If found, **update** that comment (do not add another). - If multiple are found, update the **most recently updated** one and call out the duplication as a follow-up. ## Multi-Session Support (Codex + Claude Code) This skill assumes a PR may be produced across **multiple agent sessions**, possibly in **different tools** (Codex and Claude Code). Principle: the PR comment is a **living ledger** with two layers: - **PR scope (always regenerated):** derived from the full PR diff so it never “forgets” earlier work. - **Session log (cumulative):** each run adds (or updates) a session entry capturing **human steering** and the **delta since the prior update**. ## Session Selection (Human-Readable) Sometimes you need to backfill earlier work (e.g., several Codex + Claude Code sessions happened but only the final session is open right now). If you can’t confidently identify which sessions matter: 1. Generate a short, human-readable list of recent sessions for this project (tool, session ID, timestamp, branch, first-prompt snippet). - Prefer the helper described in `references\/transcripts.md`. 2. Ask the user to pick the relevant session IDs (and optionally give each a 1-line label). 3. Only then, selectively open\/scan those transcript files to extract **human steering** + **tests run** (never paste transcripts verbatim; redact secrets). If transcript access is not available (sandbox \/ remote environment), fall back to asking the user to run: - `codex resume` \/ `codex resume --all` - `claude --resume` and share the chosen session IDs. ## Avoiding the “Latest Minor Session” Trap Never let a tiny follow-up session overwrite the narrative: - The visible “What changed” section must reflect the **entire PR diff**, not just the current chat. - The most recent session should be logged as a **delta** plus a new (or updated) session entry. ## Workflow 1. **Resolve the target PR** - Prefer `--pr auto` (PR for current branch) or accept a PR URL\/number. - If there is no PR, ask the user for the PR number or URL (stop until you have it). 2. **If multi-session\/backfill is needed, enumerate sessions** - Use the helper described in `references\/transcripts.md` to show a short table. - Ask the user which session IDs to include (Codex + Claude Code may both be involved). 3. **Write the payload JSON (LLM-owned content only)** - Keep it short and structured (no walls of text). - Do not claim tests ran unless you have evidence. - Redact secrets\/tokens\/PII\/internal URLs. 4. **Run the deterministic upsert script** - It finds\/updates the single comment (by marker), merges session entries, computes delta via GitHub compare, redacts, and posts. - Use `--dry-run` to preview without posting. 5. **Return** - Output only the comment URL (and do not re-print the entire comment body unless asked). ## Output Format (Markdown) The script renders a single GitHub-flavored Markdown comment body in this shape (keep it scannable and keep the markers intact): ````markdown

## SESSION REVIEW NOTES _{Single upserted PR comment • cumulative across Codex + Claude Code sessions<\/sub>

<\/div>

> [!IMPORTANT]
> This comment is **updated**, not duplicated. Re-run `\/session-review-notes:generate` to update it. Please do not create a second “SESSION REVIEW NOTES” comment.

### Summary

| Field | Value |
| --- | --- |
| **Intent** | <1–2 sentences> |
| **PR coverage** | `...` |
| **PR size** | |
| **Sessions** | ` (Codex×, Claude×)` |
| **Latest delta** | |
| **Risk** | Low \/ Medium \/ High |
| **Tests** | |

What changed (full PR diff)<\/strong><\/summary>

-
-

<\/details>

Hotspot map (deterministic)<\/strong><\/summary>

| Area | Files | + | - |
| --- | ---: | ---: | ---: |
| `src\/` | 7 | 220 | 45 |

<\/details>

Review hotspots \/ risks<\/strong><\/summary>

-

<\/details>

Latest delta (since prior update)<\/strong><\/summary>

-

<\/details>

Provenance \/ integrity<\/strong><\/summary>

- PR scope: GitHub diff `...`
- Delta: compare `...`
- Generator: `session-review-notes` schema=2 rev=

<\/details>

Session log (cumulative)<\/strong> _{(newest first)<\/sub><\/summary>

<\/strong> • • <\/summary>

**Human steering**
-

**Delta**
-

**Key decisions**
-

**Tests (this session)**
- [ ] (not run)
- [x] (pass)

**Notes**
-

<\/details>

<\/details>

Prompts (optional, redacted)<\/strong><\/summary>

```text

```

<\/details>

---

_{Last updated: • No secrets\/tokens\/credentials in this comment<\/sub>
````

## Posting \/ Updating the Comment (Deterministic Script)

Use the bundled script `scripts\/upsert-pr-comment.py`. It:
- finds the existing comment by marker (or creates it),
- merges the session log safely,
- computes PR facts + delta via GitHub compare,
- redacts secrets\/PII\/URLs,
- updates the comment with merge\/verify retries to avoid lost updates.

### Usage

From a **Codex Skill install** (inside the skill directory):

```bash
python3 scripts\/upsert-pr-comment.py --tool codex --session-id auto --pr auto --payload payload.json
```

From **Claude Code** (plugin install):

```bash
python3 "${CLAUDE_PLUGIN_ROOT}\/skills\/session-review-notes\/scripts\/upsert-pr-comment.py" --tool claude --session-id auto --pr auto --payload payload.json
```

Preview only (no GitHub write):

```bash
python3 scripts\/upsert-pr-comment.py --dry-run --tool codex --session-id auto --pr auto --payload payload.json
```

Payload from stdin:

```bash
python3 scripts\/upsert-pr-comment.py --tool codex --session-id auto --pr auto --payload - < payload.json
```

### Style Rules

- **Never** paste raw secrets\/tokens\/credentials (including `Authorization:` headers, API keys, cookies, JWTs, or `gh` auth tokens).
- Do not include customer PII. Redact aggressively.
- Prefer **specificity over verbosity**:
- Mention modules, directories, and concepts.
- Avoid listing every file unless the change is tiny.
- If you didn’t run tests, say so plainly (don’t imply).
- If you are uncertain about a claim, mark it as **(uncertain)** and explain why.}}}