Help us improve
Share bugs, ideas, or general feedback.
From reviw-plugin
Accumulates screenshots, videos, logs in .artifacts/<feature=branch>/ for visual regression, E2E results, and PR documentation. Generates structured reports with proof before declaring tasks complete.
npx claudepluginhub kazuph/reviw --plugin reviw-pluginHow this skill is triggered — by the user, by Claude, or both
Slash command
/reviw-plugin:artifact-proofThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
An operational workflow for preserving development evidence (screenshots, videos, logs) in `.artifacts/<feature=branch_name>/` and reusing it for PR descriptions.
Verifies task completion with checklist: collects evidence like screenshots/videos in REPORT.md, asks report level via user question, initiates reviews (code-security, e2e, ui-ux). Use post-implementation.
Records browser interactions into MP4 feature demo video, uploads to GitHub, and embeds in PR description for reviewer walkthroughs.
Inspects PostHog Visual Review runs that gate PR merges with screenshot regression checks. Useful for triaging visual diffs, deciding if changes are real or flaky, and unblocking PRs.
Share bugs, ideas, or general feedback.
An operational workflow for preserving development evidence (screenshots, videos, logs) in .artifacts/<feature=branch_name>/ and reusing it for PR descriptions.
Assumes human-in-the-loop visual regression, requiring screenshots to be retaken and verified before commits and PR pushes.
Every report MUST follow these rules. Violations will result in rejection.
![]() syntax for both images AND videos (image syntax, NOT link []())<!-- ✅ CORRECT: Table layout -->
| Before | After |
|--------|-------|
|  |  |
| Video | Flow | Description |
|-------|------|-------------|
|  | Step1 → Step2 → Step3 | Demo |
<!-- ❌ WRONG: Vertical stacking -->


<details> tagsWhen user says: "ボタンの色が仕様と違う"
Record exactly: "ボタンの色が仕様と違う" ✅
NOT: "Button color issue" ❌ (summarized)
.artifacts/<feature=branch_name>/ for evidence (screenshots, videos, REPORT.md) to avoid polluting the repository.tests/e2e/ (permanent project assets), NOT in .artifacts/ (temporary evidence only).apply_patch only. Operations that break others' changes (like git reset) are prohibited..artifacts/<feature=branch_name>/REPORT.md.artifacts/<feature=branch_name>/images/.artifacts/<feature=branch_name>/videos/20251130-login-before.png, 20251130-login-after.png, 20251130-login-run.webm# <feature=branch_name> / <ticket>
Created: YYYY-MM-DD
Branch: <branch-name>
Status: Awaiting Review
## 📌 Attention Required (今回の確認項目)
**Please review these specific points:**
| # | Item | Question/Note |
|---|------|---------------|
| 1 | [Specific area to review] | [What you want feedback on] |
| 2 | [Design decision] | [Options considered, why this choice] |
| 3 | [Edge case handling] | [How it's handled, is this acceptable?] |
---
## 🔄 User Request ⇄ Response (修正依頼と対処)
**修正依頼がある場合は必ずこのセクションを含める(依頼→対処の交互表示)**
| # | User Request (原文) | Response (対処内容) | 検証方法 |
|---|---------------------|---------------------|----------|
| 1 | 「[ユーザーの依頼をほぼ原文で]」 | [具体的な変更内容: ファイル名、コード変更] | E2E: [どうアサートしているか] |
| 2 | 「[ユーザーの依頼をほぼ原文で]」 | [具体的な変更内容] | E2E: [アサーション内容] |
<!--
CRITICAL: このセクションがないと以下の問題が発生する:
- ユーザーは依頼がどう対処されたか分からない
- E2Eを回しても「何も変わっていない」
- スクショ・動画を見ても変化が不明
検証方法は必須。E2Eでアサートしていない修正は「対処した」とは言えない。
-->
---
## 📋 Previous Feedback Response (累積フィードバック履歴)
<details open>
<summary><strong>Latest: YYYY-MM-DD</strong></summary>
| Feedback | Status | How Addressed |
|----------|--------|---------------|
| "Fix the button alignment" | ✅ Done | Changed flexbox justify-content to center |
| "Add error handling" | ✅ Done | Added try-catch with user-friendly message |
</details>
<details>
<summary>YYYY-MM-DD (Previous)</summary>
| Feedback | Status | How Addressed |
|----------|--------|---------------|
| "Improve loading state" | ✅ Done | Added skeleton loader |
</details>
<!--
ACCUMULATION RULE:
- When receiving new feedback, move the current "Latest" to a new collapsed <details> block
- Add new feedback response as the new "Latest" (with <details open>)
- Never delete previous feedback - keep accumulating
- Oldest feedback goes to the bottom
-->
---
## Context
- Background and requirements
- Out of scope
- Acceptance criteria
## Plan
- [ ] Task 1
- [ ] Task 2
- [ ] Task 3
## Evidence
### Screenshots (table layout recommended)
| Before | After |
|--------|-------|
|  |  |
### Videos (image syntax for thumbnails, with flow column)
Use image syntax `` to display video with thumbnail and controls.
**Include a Flow column with arrow notation** to show what the video demonstrates at a glance.
| Video | Flow | Description |
|-------|------|-------------|
|  | Top → Email → Password → Submit → Dashboard | Login flow demo |
|  | Menu → Settings → Toggle → Save → Toast | Settings update demo |
Link-only format (no thumbnail):
- [Login demo](./videos/YYYYMMDD-login.webm): Top → Email → Password → Submit → Dashboard
### Test Results
```bash
# Command executed
npx playwright test tests/e2e/feature.spec.ts --reporter=line
# Result
✓ 5 passed (10s)
npm run build passed# Build output here
# Test output here
# Steps to reproduce the evidence above
pnpm install
pnpm dev
# Then navigate to http://localhost:3000/feature
| File | Line | Code | Status |
|---|
| File | Line | Code | Issue |
|---|
## Example of Capturing Evidence with Playwright (Screenshots + Videos)
**Note**: E2E test code should be in `tests/e2e/`, not here. Use this for quick evidence capture only.
```bash
FEATURE=${FEATURE:-feature}
mkdir -p .artifacts/$FEATURE/{images,videos}
# Run existing E2E test with evidence collection
npx playwright test tests/e2e/your-feature.spec.ts \
--headed \
--output=.artifacts/$FEATURE \
--trace=retain-on-failure
# Or quick one-liner for ad-hoc screenshot (TypeScript via tsx)
npx tsx -e "
import { chromium } from 'playwright';
const feature = process.env.FEATURE || 'feature';
const browser = await chromium.launch({ headless: false });
const context = await browser.newContext({
viewport: { width: 1440, height: 900 },
recordVideo: { dir: \\\`.artifacts/\\\${feature}/videos\\\` }
});
const page = await context.newPage();
await page.goto(process.env.BASE_URL || 'http://localhost:3000', { waitUntil: 'networkidle' });
const stamp = new Date().toISOString().slice(0,10).replace(/-/g,'');
await page.screenshot({ path: \\\`.artifacts/\\\${feature}/images/\\\${stamp}-step.png\\\`, fullPage: true });
await browser.close();
"
FEATURE=${FEATURE:-feature}
BASE_URL=http://localhost:3000 \
npx playwright test tests/e2e/<spec>.spec.ts \
--headed \
--output=.artifacts/$FEATURE/images \
--trace=retain-on-failure \
--reporter=line
After execution, if videos or trace outputs are scattered in different directories, organize them by moving to .artifacts/$FEATURE/videos/.
.artifacts/<feature=branch_name>/images/ (videos to videos/).reviw is a CLI tool that reviews CSV/TSV/Markdown/Diff/text files in a browser and outputs comments in YAML format.
# Open a report (must run in foreground)
npx reviw .artifacts/<feature=branch_name>/REPORT.md
# If there's a video, open it first
open .artifacts/<feature=branch_name>/videos/demo.webm
npx reviw .artifacts/<feature=branch_name>/REPORT.md
# Review git diff
git diff HEAD | npx reviw
# Open multiple files simultaneously
npx reviw file1.md file2.csv data.tsv
| Option | Description |
|---|---|
--port <number> | Specify port number (default: 4989) |
--encoding <enc> | Specify character encoding (shift_jis, euc-jp, etc.) |
--no-open | Disable automatic browser launch |
npx reviw .artifacts/<feature=branch_name>/REPORT.md # Launch in foreground
↓
Browser opens
↓
User reviews content and adds comments
↓
Click "Submit & Exit"
↓
Feedback is output in YAML format
↓
Register feedback in TodoWrite (detailed, no summarizing)
↓
Fix → Review again with reviw → Repeat until approved
# Correct (can receive feedback)
npx reviw report.md
# Wrong (cannot receive feedback)
npx reviw report.md &
Launching in the background prevents receiving user comments, so always launch in foreground.
Note for Claude Code users: Claude Code can detect when background processes exit and capture their output, so you may use
run_in_background: truewith the Bash tool. The foreground requirement applies to other AI environments that cannot monitor background process completion.
file: report.md
mode: markdown
comments:
- line: 15
content: "Please add an explanation for this part"
- line: 23
content: "Error handling is needed"
summary: "Overall good, but please fix the above points"
PR branches are often deleted after merging. Branch-name-based URLs become 404 after deletion, so always use blob URLs with commit hashes.
# Get current commit hash
COMMIT_HASH=$(git rev-parse HEAD)
# Or short form
COMMIT_HASH=$(git rev-parse --short HEAD)
Correct URL format (using commit hash):

Wrong URL format (using branch name - 404 after deletion):

Vertically stacked screenshots are hard to read. Use HTML tables to arrange them horizontally as well:
<!-- 2-column layout -->
<table>
<tr>
<td><img src="https://github.com/.../blob/<hash>/.artifacts/feature/images/before.png?raw=true" width="400"/></td>
<td><img src="https://github.com/.../blob/<hash>/.artifacts/feature/images/after.png?raw=true" width="400"/></td>
</tr>
<tr>
<td align="center">Before</td>
<td align="center">After</td>
</tr>
</table>
<!-- 3-column layout (comparing multiple screens) -->
<table>
<tr>
<td><img src=".../step1.png?raw=true" width="280"/></td>
<td><img src=".../step2.png?raw=true" width="280"/></td>
<td><img src=".../step3.png?raw=true" width="280"/></td>
</tr>
<tr>
<td align="center">1. Login Screen</td>
<td align="center">2. After Input</td>
<td align="center">3. Completion Screen</td>
</tr>
</table>
FEATURE=${FEATURE:-feature}
ORG=$(gh repo view --json owner -q .owner.login)
REPO=$(gh repo view --json name -q .name)
COMMIT=$(git rev-parse HEAD)
# Generate Markdown table from image list
echo "<table><tr>"
count=0
for img in .artifacts/$FEATURE/images/*.png; do
filename=$(basename "$img")
echo "<td><img src=\"https://github.com/$ORG/$REPO/blob/$COMMIT/$img?raw=true\" width=\"400\"/></td>"
count=$((count + 1))
# New row every 2 columns
if [ $((count % 2)) -eq 0 ]; then
echo "</tr><tr>"
fi
done
echo "</tr></table>"
gh api --method PATCH repos/<org>/<repo>/pulls/<num> -f body="$(cat /tmp/new-body.md)"
Video files are large, so they must be managed with Git LFS.
# If LFS is not installed
brew install git-lfs # macOS
git lfs install
# Add video files to LFS tracking
git lfs track "*.webm"
git lfs track "*.mp4"
git lfs track "*.mov"
git lfs track ".artifacts/**/*.webm"
git lfs track ".artifacts/**/*.mp4"
# Commit .gitattributes
git add .gitattributes
git commit -m "chore: add video files to Git LFS"
# 1. Place the video
mv recording.webm .artifacts/$FEATURE/videos/
# 2. Verify LFS tracking
git lfs status
# 3. Add/commit normally
git add .artifacts/$FEATURE/videos/
git commit -m "docs: add demo video for $FEATURE"
Videos cannot be played directly on GitHub, so provide them as links:
[View demo video](./.artifacts/feature/videos/demo.webm)
Or convert to GIF for embedding:
# webm → gif conversion (using ffmpeg)
ffmpeg -i demo.webm -vf "fps=10,scale=600:-1" demo.gif
Use collapsible sections for long logs or detailed information:
<details>
<summary>Click to expand: Detailed logs</summary>
Long logs or detailed information here.
Code blocks can be included.
</details>
Recommended: Use image syntax for thumbnail display with flow column
| Video | Flow | Description |
|-------|------|-------------|
|  | Home → Click → Modal → Submit → Success | Feature demo |
The Flow column uses arrow notation (→) to show what steps the video demonstrates at a glance. Since Mermaid cannot be used inside tables, this is the recommended alternative.
Link syntax (no thumbnail):
[Play video](./videos/demo.webm): Home → Click → Modal → Submit → Success
Images can be placed inside table cells:
| Before | After |
|--------|-------|
|  |  |
Putting code fences (```) inside table cells breaks the parser:
<!-- This does NOT work -->
| Code | Diagram |
|------|---------|
| sample | ```mermaid
flowchart TD
``` |
<!-- Place Mermaid outside tables instead -->
| Code | Diagram |
|------|---------|
| sample | See below |
```mermaid
flowchart TD
A --> B
### Mermaid Diagrams
reviw auto-renders Mermaid diagrams:
```markdown
```mermaid
flowchart LR
A[Start] --> B[Process] --> C[End]
Note: Place Mermaid blocks outside tables, not inside table cells.
## Best Practices
- Include screen or state-descriptive words in screenshot/video filenames (e.g., `login-success.png`).
- Use both full-page and element-level captures for better diff accuracy.
- Preserve screenshots even for test failures to aid in debugging.
- When creating PRs, paste Artifact content directly; update Artifacts based on review feedback.
- **Don't stack screenshots vertically; use 2-3 column table layouts for horizontal utilization**.
- **Always use commit hashes in image URLs so they display even after branch deletion**.
- **Always manage videos with Git LFS to avoid repository bloat**.
- **Use `` syntax for video thumbnails in reviw**.
- **Include a Flow column with arrow notation** to describe video content at a glance.
- **Use `<details>` for collapsible sections to keep reports clean**.
- **Never put code fences inside table cells - it breaks the parser**.
## Expected Outputs
- `.artifacts/<feature=branch_name>/` contains task-specific READMEs with linked evidence (screenshots, videos, logs).
- Screenshots are updated to the latest before commits and PR pushes, with visual diffs verified by human eyes.
- Artifacts can be directly reused as PR descriptions.
- PR images use commit hash-based blob URLs that remain visible after branch deletion post-merge.
- Video files are managed with Git LFS, reducing clone overhead.