<!-- ✅ CORRECT: Table layout -->
| Before | After |
|--------|-------|
| ![Before](./images/before.png) | ![After](./images/after.png) |

| Video | Flow | Description |
|-------|------|-------------|
| ![Demo](./videos/demo.webm) | Step1 → Step2 → Step3 | Demo |

<!-- ❌ WRONG: Vertical stacking -->
![Step1](./images/step1.png)
![Step2](./images/step2.png)

When user says: "ボタンの色が仕様と違う"
Record exactly: "ボタンの色が仕様と違う" ✅
NOT: "Button color issue" ❌ (summarized)

# <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 |
|--------|-------|
| ![Before](./images/YYYYMMDD-feature-before.png) | ![After](./images/YYYYMMDD-feature-after.png) |

### Videos (image syntax for thumbnails, with flow column)
Use image syntax `![](video.mp4)` 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 |
|-------|------|-------------|
| ![Login](./videos/YYYYMMDD-login.webm) | Top → Email → Password → Submit → Dashboard | Login flow demo |
| ![Settings](./videos/YYYYMMDD-settings.webm) | 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)

# Build output here

# Test output here

# Steps to reproduce the evidence above
pnpm install
pnpm dev
# Then navigate to http://localhost:3000/feature

## 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

# 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

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 &

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"

# Get current commit hash
COMMIT_HASH=$(git rev-parse HEAD)
# Or short form
COMMIT_HASH=$(git rev-parse --short HEAD)

![alt](https://github.com/<org>/<repo>/blob/<commit-hash>/.artifacts/<feature=branch_name>/images/screenshot.png?raw=true)

![alt](https://github.com/<org>/<repo>/blob/<branch-name>/.artifacts/<feature=branch_name>/images/screenshot.png?raw=true)

<!-- 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)"

# 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"

[View demo video](./.artifacts/feature/videos/demo.webm)

# webm → gif conversion (using ffmpeg)
ffmpeg -i demo.webm -vf "fps=10,scale=600:-1" demo.gif

<details>
<summary>Click to expand: Detailed logs</summary>

Long logs or detailed information here.
Code blocks can be included.

</details>

| Video | Flow | Description |
|-------|------|-------------|
| ![Demo](./videos/demo.webm) | Home → Click → Modal → Submit → Success | Feature demo |

[Play video](./videos/demo.webm): Home → Click → Modal → Submit → Success

| Before | After |
|--------|-------|
| ![Before](./images/before.png) | ![After](./images/after.png) |

<!-- 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 `![](video.mp4)` 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.