---
name: screenshot-review
description: Capture production screenshots safely and build the per-sprint HTML review doc. Invoke for any sprint that ships user-facing portal UI changes, OR when a context-busting wide image risks killing the session.
user-invocable: true
title: screenshot-review
canonical_url: https://skilld.dev/gh/colaberryintern/colaberryenterprise_ai_leadershipaccelerator/screenshot-review
last_updated: 2026-10-08T09:39:34.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> If the user asked to install this Skill, run `npx skilld install colaberryintern/colaberryenterprise_ai_leadershipaccelerator/screenshot-review`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/screenshot-review`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/colaberryintern/colaberryenterprise_ai_leadershipaccelerator/screenshot-review) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/screenshot-review`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/screenshot-review --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/screenshot-review --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Screenshot Review — Capture + Review Doc Protocol

## When this skill applies

### Required for any sprint that:
- Changes a route, page, or component visible at `enterprise.colaberry.ai/portal/*`
- Adds a new surface (Cory Home, ExecutionLane, SystemView, Critique, Setup, etc.)
- Modifies UnifiedProjectState or other state surfaced on Cory Home
- Touches navigation, layout, or a verdict-bearing surface

### Not required for:
- Backend-only changes that don't surface to the user
- Internal scripts in `backend/src/scripts/` or `scripts/`

## Part 1 — Safe capture protocol

A prior session died because a single screenshot at 2128×266 pushed the cumulative many-image context past Claude Code's 2000px ceiling, and every reply after that hit the dimension-limit error. The verification workflow is now hardened.

### Hard rules (enforced)
- **Max safe width is 1800px.** Every PNG Claude will be asked to `Read` must be ≤1800px wide. Wider gets downscaled before it lands on disk.
- **Default capture viewport is `SAFE_VIEWPORT` (1440×900 at `deviceScaleFactor=1`).** DSF 2 (retina) is permitted only when the PNG will exclusively be embedded into a review-doc HTML for human inspection — never when Claude will `Read` it.
- **All capture scripts must route through `scripts/captureHelpers.js`.** Direct `page.screenshot(...)` calls in capture scripts are a violation. The helper provides `safeScreenshot`, `safeCrop`, `boundedFullPage`, and `maxWidthGuard`, each of which downscales in place if the captured PNG exceeds the safe width.
- **Three-image read budget per conversation turn.** Claude reads at most three PNGs in any single turn during verification. Subsequent images go through a focused crop, not a re-`Read` of the same surface.
- **`_summary.json` is mandatory.** Every capture batch writes `_summary.json` next to the PNGs via `writeCaptureSummary(...)`. Each entry must include `originalWidth`, `finalWidth`, `downscaled`. Any `finalWidth > 1800` is a process violation.

### The helper API
`scripts/captureHelpers.js` is the single sanctioned capture path:

| Export | Use |
|---|---|
| `MAX_SAFE_WIDTH` (=1800) | Hard cap referenced throughout |
| `SAFE_VIEWPORT` | Default: 1440×900, DSF 1 |
| `RETINA_REVIEW_VIEWPORT` | 1440×900, DSF 2 — review-doc embeds only |
| `createSafeContext(browser, { token, viewport, seededMemory, label })` | Playwright context with auth injected via `addInitScript`, viewport set per `label` |
| `safeScreenshot(page, outPath, { fullPage, clip, label })` | Wraps `page.screenshot`; downscales to ≤1800px after capture |
| `safeCrop(page, selector, outPath, { padding, label })` | Bounding-rect crop with width clamp |
| `boundedFullPage(page, outPath, { label })` | Full-page convenience that asserts DSF 1 |
| `maxWidthGuard(pngPath, { label })` | Standalone downscale check for non-Playwright captures |
| `writeCaptureSummary(outDir, entries)` | Writes `_summary.json` with `max_safe_width`, `safe_viewport`, the per-PNG `final_width` ledger |

Use `label: 'retina-review'` only for explicitly human-reviewed embeds; any other label routes through the safe-width clamp.

### Dependency
Depends on `sharp` (^0.33) at repo-root `devDependencies` for in-place PNG downscaling. Added 2026-05-16.

## Part 2 — Capture script invocation

The capture script lives at `scripts/captureProductionScreenshots.js`. It uses Playwright + a JWT token at `scripts/.ali_jwt.txt` (gitignored — never commit) to authenticate against `enterprise.colaberry.ai` and screenshot every primary surface.

```
node scripts/captureProductionScreenshots.js
```

Output lands in `docs/screenshots/<YYYY-MM-DD>-deploy/` as full-page PNGs. Override base URL with `CAPTURE_BASE` env, output dir with `CAPTURE_OUT`.

### Token refresh (when JWT expires)
1. F12 → Console (type `allow pasting` first to bypass Chrome's anti-XSS warning)
2. `copy(localStorage.getItem('participant_token'))`
3. Paste into `scripts/.ali_jwt.txt` (replace file contents)

## Part 3 — Review HTML structure

For each user-facing change shipped in the sprint:

1. **The live screenshot embedded inline** — wrapped in a dark frame card with URL caption + "open full size" link to the underlying PNG. Use the existing `.screenshot` CSS pattern in `docs/POST_DEPLOY_WALKTHROUGH.html`.
2. **Before/after pairs** when the change is a redesign.
3. **A clear caption** stating what the user is looking at.

### Per-stop pattern
- `① See it` — screenshot card + "Open in new tab" button to live URL
- `② What shipped here` — bullet list
- `③ Possible changes` — pre-flagged issues with checkboxes for operator investigation
- `④ Your verdict + notes` — 👍/⚠/✕ radio + free-form textarea

### Required interactions
- **Inline critique** — every section ends with a real `<textarea>` for operator notes without leaving the doc
- **Compile button** — at bottom, gathers all checkbox + radio + textarea state into a single Markdown prompt to paste back for the next sprint
- **Reset button** — clears state, fresh start

Reference implementation: `docs/POST_DEPLOY_WALKTHROUGH.html` (copy that pattern).

## Naming + location
- Walkthroughs: `docs/<SPRINT>_REVIEW.html` — one per sprint
- Screenshots: `docs/screenshots/<YYYY-MM-DD>-<context>/<NN>-<slug>.png`
- Token (gitignored): `scripts/.ali_jwt.txt`
- Capture script: `scripts/captureProductionScreenshots.js`

Screenshot folders may be committed if the operator decides. Token file may NOT.

## Why this protocol exists
1. **CSS mockups drift from reality.** Stakeholders sign off on wireframes, then prod looks different. Real screenshots eliminate that.
2. **Setup friction blocks review.** Without embedded screenshots, every reviewer needs the dev environment OR a production login. With them, the doc is self-contained.
