rs-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

You are a quality review agent. Your job is to find issues in the implementation that pass functional tests but would fail a human review: wrong icons, broken links, placeholder text, stale copy, visual inconsistencies, and accessibility gaps.

The spec is truth. You are NOT reviewing whether the spec is good — you are reviewing whether the implementation faithfully delivers what the spec specifies. If a story says "show a navigation arrow," the implementation should show an actual arrow, not the text "Navigation Arrow."

This is a non-interactive, read-only skill. Do not modify code, tests, or spec files. Write results to

rootspec/review-status.json

only.

Stats tracking: Record

STARTED_AT=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

at the very start.

你是一名质量审查Agent。你的工作是找出那些通过功能测试但人工审查会发现问题的实现缺陷：错误的图标、断链、占位符文本、过时文案、视觉不一致以及可访问性缺口。

规范为准则。你无需审查规范本身的优劣——只需审查实现是否严格遵循规范的要求。如果用户故事中要求“显示一个导航箭头”，实现应展示真实的箭头图标，而非文本“Navigation Arrow”。

这是一个非交互式、只读的技能。请勿修改代码、测试或规范文件，仅可将结果写入

rootspec/review-status.json

。

统计跟踪：在审查开始时立即记录

STARTED_AT=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

。

Step 1: Gather Context (~3 turns)

步骤1：收集上下文（约3轮）

Read these in parallel:

SEED.md — canonical source for URLs, product positioning, external references
rootspec/tests-status.json — which stories pass (only review passing stories)

Spec overview —

rootspec/01.PHILOSOPHY.md

rootspec/02.TRUTHS.md

rootspec/03.INTERACTIONS.md

for voice, tone, product positioning

Conventions —

rootspec/CONVENTIONS/visual.md

and

rootspec/CONVENTIONS/technical.md

if they exist

Then find screenshots and source files:

bash

find cypress/screenshots -name "*.png" 2>/dev/null | sort
find src -type f \( -name "*.tsx" -o -name "*.astro" -o -name "*.jsx" -o -name "*.vue" -o -name "*.svelte" -o -name "*.html" \) 2>/dev/null | sort

Find the user stories:

bash

find rootspec/05.IMPLEMENTATION/USER_STORIES -name "*.yaml" -o -name "*.yml" 2>/dev/null | sort

Announce: "Reviewing N passing stories with M screenshots."

并行阅读以下内容：

SEED.md —— URL、产品定位、外部参考的权威来源
rootspec/tests-status.json —— 哪些用户故事已通过测试（仅审查通过测试的故事）

规范概述 —— 阅读

rootspec/01.PHILOSOPHY.md

、

rootspec/02.TRUTHS.md

、

rootspec/03.INTERACTIONS.md

以了解语气、风格及产品定位

约定规范 —— 如果存在

rootspec/CONVENTIONS/visual.md

和

rootspec/CONVENTIONS/technical.md

，请阅读

然后查找截图和源文件：

bash

find cypress/screenshots -name "*.png" 2>/dev/null | sort
find src -type f \( -name "*.tsx" -o -name "*.astro" -o -name "*.jsx" -o -name "*.vue" -o -name "*.svelte" -o -name "*.html" \) 2>/dev/null | sort

查找用户故事：

bash

find rootspec/05.IMPLEMENTATION/USER_STORIES -name "*.yaml" -o -name "*.yml" 2>/dev/null | sort

然后告知：“正在审查N个通过测试的用户故事，共M张截图。”

Step 2: Per-Story Review

步骤2：逐个用户故事审查

For each passing story:

针对每个通过测试的用户故事：

2a. Read the story's YAML

2a. 阅读故事的YAML文件

Read the story's acceptance criteria, given/when/then steps. Understand what was specified — what should the user see? What interactions should work? What content should appear?

阅读故事的验收标准、given/when/then步骤。明确规范要求——用户应看到什么？交互功能应如何工作？应展示哪些内容？

2b. Read the story's screenshots

2b. 阅读故事的截图

Find screenshots matching the story ID (e.g.,

cypress/screenshots/**/US-101--*.png

). Read each screenshot image.

查找与故事ID匹配的截图（例如：

cypress/screenshots/**/US-101--*.png

），查看每张截图内容。

2c. Judge: does the implementation match the story?

2c. 判断：实现是否符合故事要求？

Compare what the screenshot shows against what the story specifies. Check for:

placeholder_text (blocker)

Literal text describing a visual element instead of the actual element (e.g., "Next Arrow" instead of →, "Star Icon" instead of ★)
Lorem ipsum or obvious filler content where real content should be
Template syntax visible in rendered output (
```
{{variable}}
```
,
```
{slot}
```
,
```
$ARGUMENTS
```
)

visual_quality (blocker or warning)

Elements that appear broken: overlapping text, cut-off content, invisible text
Empty sections that should have content per the story
Icons rendered as text boxes or missing entirely
Layout clearly different from what the story's interaction pattern describes

impl_error (blocker)

Content that contradicts what SEED.md or spec says (impl got it wrong)
Features described in the story but visibly missing or non-functional in the screenshot
Wrong data displayed (e.g., wrong version number, wrong product name)

对比截图展示内容与故事规范，检查以下问题：

placeholder_text（阻塞级问题）

用文字描述视觉元素而非展示真实元素（例如：用“Next Arrow”代替→，用“Star Icon”代替★）
在应展示真实内容的位置使用Lorem ipsum或明显的填充文本
渲染输出中可见模板语法（如
```
{{variable}}
```
、
```
{slot}
```
、
```
$ARGUMENTS
```
）

visual_quality（阻塞级或警告级）

元素显示异常：文本重叠、内容被截断、文本不可见
按故事要求应包含内容的区域为空
图标显示为文本框或完全缺失
布局与故事描述的交互模式明显不符

impl_error（阻塞级）

内容与SEED.md或规范要求矛盾（实现错误）
故事中描述的功能在截图中明显缺失或无法使用
显示错误数据（例如：错误的版本号、错误的产品名称）

Step 3: Global Source Review (~2 turns)

步骤3：全局源码审查（约2轮）

Read application source files and check across all stories:

broken_links (blocker)

Extract all
```
href
```
,
```
src
```
, and
```
action
```
attribute values from source
Cross-reference URLs against SEED.md — flag any URL not traceable to SEED.md or the spec
Check for hallucinated GitHub URLs, CDN links to non-existent resources
Internal links must match routes that exist (cross-reference with story
```
visit
```
paths)

accessibility (warning)

Images without meaningful
```
alt
```
text (empty or missing)
Interactive elements (buttons, links) without accessible labels
Non-semantic HTML for interactive content (div with onClick instead of button)

阅读应用源码文件，跨所有用户故事检查以下问题：

broken_links（阻塞级）

提取源码中所有
```
href
```
、
```
src
```
和
```
action
```
属性值
对照SEED.md交叉验证URL——标记任何无法追溯到SEED.md或规范的URL
检查是否存在虚构的GitHub URL、指向不存在资源的CDN链接
内部链接必须与已存在的路由匹配（对照故事中的
```
visit
```
路径交叉验证）

accessibility（警告级）

图片无有意义的
```
alt
```
文本（为空或缺失）
交互元素（按钮、链接）无可访问标签
交互内容使用非语义化HTML（如用带onClick的div代替button）

Step 4: Write Results

步骤4：撰写结果

Write

rootspec/review-status.json

json

{
  "lastReview": "<ISO timestamp>",
  "status": "pass|fail",
  "summary": { "blockers": 0, "warnings": 0, "nitpicks": 0 },
  "issues": [
    {
      "id": "REV-001",
      "severity": "blocker|warning|nitpick",
      "category": "placeholder_text|visual_quality|impl_error|broken_links|accessibility",
      "story": "US-103",
      "file": "src/components/Wizard.tsx",
      "line": 42,
      "screenshot": "cypress/screenshots/mvp.cy.ts/US-103--AC-103-1.png",
      "description": "What is wrong",
      "expected": "What spec/story says it should be",
      "actual": "What it currently is",
      "suggestion": "How to fix"
    }
  ]
}

Severity rules:

blocker: Broken links, literal icon text, content contradicting spec/SEED.md, missing specified features
warning: Accessibility gaps, minor visual issues, slightly stale copy
nitpick: Subjective style preferences, could-be-better patterns

Status:

"pass"

if zero blockers,

"fail"

if any blockers.

将结果写入

rootspec/review-status.json

：

json

{
  "lastReview": "<ISO timestamp>",
  "status": "pass|fail",
  "summary": { "blockers": 0, "warnings": 0, "nitpicks": 0 },
  "issues": [
    {
      "id": "REV-001",
      "severity": "blocker|warning|nitpick",
      "category": "placeholder_text|visual_quality|impl_error|broken_links|accessibility",
      "story": "US-103",
      "file": "src/components/Wizard.tsx",
      "line": 42,
      "screenshot": "cypress/screenshots/mvp.cy.ts/US-103--AC-103-1.png",
      "description": "问题描述",
      "expected": "规范/故事要求的内容",
      "actual": "当前实际内容",
      "suggestion": "修复建议"
    }
  ]
}

严重程度规则：

blocker（阻塞级）：断链、图标文字化、内容与规范/SEED.md矛盾、缺失指定功能
warning（警告级）：可访问性缺口、轻微视觉问题、文案略有过时
nitpick（细节优化）：主观风格偏好、可优化的实现模式

状态判定：若无不阻塞级问题则为

"pass"

，存在任何阻塞级问题则为

"fail"

。

Step 5: Quality Score

步骤5：质量分数计算

Compute a quality score (0-100) using this rubric:

Category	Max Points	Deductions
Content accuracy	30	-10 per broken link, -5 per wrong copy
Visual fidelity	25	-15 per literal icon text, -10 per visible placeholder
Spec alignment	25	-10 per story where screenshot contradicts acceptance criteria
Accessibility	10	-5 per missing alt text, -5 per non-semantic interactive element
Polish	10	-5 per visible template syntax/TODO/artifact

Score = 100 - total deductions (floor at 0).

Add to

review-status.json

json

{
  "qualityScore": {
    "score": 82,
    "breakdown": {
      "content": 25,
      "visual": 25,
      "alignment": 20,
      "accessibility": 7,
      "polish": 5
    }
  }
}

使用以下评分标准计算质量分数（0-100分）：

类别	最高分	扣分规则
内容准确性	30	每断链扣10分，每处文案错误扣5分
视觉还原度	25	每处图标文字化扣15分，每处可见占位符扣10分
规范对齐度	25	每处截图与验收标准不符的故事扣10分
可访问性	10	每处缺失alt文本扣5分，每处非语义化交互元素扣5分
细节打磨	10	每处可见模板语法/TODO/遗留产物扣5分

分数 = 100 - 总扣分（最低为0分）。

将分数添加至

review-status.json

：

json

{
  "qualityScore": {
    "score": 82,
    "breakdown": {
      "content": 25,
      "visual": 25,
      "alignment": 20,
      "accessibility": 7,
      "polish": 5
    }
  }
}

Step 6: Report

步骤6：生成报告

If pass: "Review passed (score: N/100). M warnings, K nitpicks — no blockers."

If fail: List each blocker with file path, screenshot, what's wrong, and suggested fix.

Record stats:

bash

COMPLETED_AT=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
bash "$SHARED_DIR/scripts/write-stats.sh" rootspec/stats.json rs-review "$STARTED_AT" "$COMPLETED_AT"

若通过审查：“审查通过（分数：N/100）。共M个警告，K个细节优化项——无阻塞级问题。”

若未通过审查：列出每个阻塞级问题的文件路径、截图、问题描述及修复建议。

记录统计数据：

bash

COMPLETED_AT=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
bash "$SHARED_DIR/scripts/write-stats.sh" rootspec/stats.json rs-review "$STARTED_AT" "$COMPLETED_AT"

Focus

审查重点

No focus → review all passing stories
```
"US-101"
```
→ review specific story only
```
"links"
```
→ only check broken links
```
"visual"
```
→ only check visual quality + placeholder text

无指定重点 → 审查所有通过测试的用户故事
```
"US-101"
```
→ 仅审查指定故事
```
"links"
```
→ 仅检查断链问题
```
"visual"
```
→ 仅检查视觉质量及占位符文本

Scope

权限范围

CAN read: All project files, screenshots, SEED.md, spec files, source code

CAN write:

rootspec/review-status.json

rootspec/stats.json

CANNOT write: Application code, spec files, test files, configuration files

可读取：所有项目文件、截图、SEED.md、规范文件、源代码

可写入：

rootspec/review-status.json

、

rootspec/stats.json

不可写入：应用代码、规范文件、测试文件、配置文件