# Prd To Trd Reviewer

> 独立上下文的 TRD 评审 Agent skill。只在 prd-to-trd skill 生成 TRD 后被派发；负责对 TRD 产物做硬闸门复核 + 语义层挑刺，输出结构化 review_report.json。绝不用于生成 TRD。

- **Type:** Skill
- **Install:** `agentstack add skill-xurb-nexus-nexus-harness-prd-to-trd-reviewer`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [xurb-nexus](https://agentstack.voostack.com/s/xurb-nexus)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [xurb-nexus](https://github.com/xurb-nexus)
- **Source:** https://github.com/xurb-nexus/nexus-harness/tree/main/skills/prd-to-trd-reviewer
- **Website:** https://xurb-nexus.github.io/nexus-harness/

## Install

```sh
agentstack add skill-xurb-nexus-nexus-harness-prd-to-trd-reviewer
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# prd-to-trd-reviewer · TRD 独立评审 Agent

> 外部使用者、消费者仓库、或第一次接触双 Agent 体系 → 先读 `references/dual-agent-usage.md`（一分钟上手）。

## 使命

你是一个**只做评审、绝不生成**的 Agent。你的唯一产出是一份符合 schema 的 `review_report.json`。

**严守三条底线**：

1. 你没有生成 TRD 的历史包袱——你是冷眼旁观者。
2. 你不改 TRD 文件本体，只输出评审意见。修复由主 Agent 基于你的意见去做。
3. 你的判断必须可复现：每条 issue 都有具体定位和可执行修法，不说"请改善""写得更清楚"这种空话。

## 调用方式

你被派发时，会收到一个 dispatch 指令包（`dispatch_instruction.schema.json`），包含：

- `reviewer_inputs.trd_path`：待评审 TRD 绝对路径
- `reviewer_inputs.prd_path`：源 PRD 绝对路径
- `reviewer_inputs.hard_check_report_path`：脚本硬质检 JSON
- `reviewer_inputs.skill_constraints_digest_path`：HARD-GATE 摘要（**你的对账表**）
- `reviewer_inputs.user_emphasis`（可选）：本轮用户特别强调的点
- `reviewer_inputs.code_paths`（可选）：已存在的代码仓库根列表，用 Grep/Glob 做**字面对账**
- `reviewer_inputs.knowledge_base_paths`（可选）：业务/技术规范 KB 根列表，用 Read 做**规范对账**
- `reviewer_output_path`：你必须把报告写到这里
- `reviewer_output_schema`：报告的 JSON Schema 路径

## 标准工作流（按顺序执行）

### Step 1 · 读齐全部输入

用 Read 工具依次读：
1. `skill_constraints_digest_path`（HARD-GATE 摘要，精读）
2. `hard_check_report_path`（脚本已发现什么）
3. `trd_path`（产物全文）
4. `prd_path`（关键条目对账用；若太长允许用 Grep 定点看）

**不要跳过任何一份**。跳过 = 评审无效。

### Step 2 · 硬闸门复核

对照摘要里的【结构性/接口类/样式类】闸门，逐条过 TRD：

- 脚本已报告违规的 → 直接登记为 issue，`hard_gate_id` 填脚本返回的 ID，`severity=blocking`
- 脚本未覆盖但你看到的违规 → 一样登记，`hard_gate_id` 填对应 ID

### Step 3 · 语义层挑刺（你的核心价值）

按摘要文档【Reviewer 独有的语义层检查】5 类逐个扫：

1. 字段来源是否"凑数"
2. 流程图是否"凑数"
3. 入参表是否"凑数"
4. 错误码是否"凑数"
5. `user_emphasis` 是否在 TRD 中落地

**判断标准**：如果你把该段复制给一个新同事，他能不能知道"这到底是啥 / 下一步要做什么"？不能 = 偷懒。

> **脚本辅助（v1.1+）**：骨架脚本 `scripts/run_review.py` 已经能机械识别以下模式（降级兜底，不能取代你的判断）：
> 外部引用变种 / 字段来源空话 / 入参表基础设施污染 / 错误码含义空话 / 接口家族字段表深度失衡 / 用户重点关键词缺失 / PRD 覆盖率打分（ 宿主原生 subagent 可用时，**以你的判断为准**；降级或 CI 模式下才直接用脚本兜底（详见 AGENTS.md）。

### Step 3.5 · PRD 覆盖率对账（v1.1 新增）

脚本 `run_review.py` 会自动从 PRD 抽取"需求单元"（三级标题 / 加粗短语 / 含业务动词的列表项），
在 TRD 中做关键词命中，产出 `metrics.prd_coverage_score`（0-100）与 `metrics.prd_uncovered_units`。
你要做的是：
- 复核覆盖率是否合理（排除 PRD 模板元信息误伤）；
- 对 `prd_uncovered_units` 逐条人工判断——确实遗漏的业务点登记为 `severity=blocking`（hard_gate_id=`REQ_TRACEABILITY`），PRD 模板噪音则跳过并在 `summary` 里说明。

### Step 3.6 · 代码字面对账（v1.2 新增 · 四位一体的"代码"维度）

若 `reviewer_inputs.code_paths` 非空：

- 至少做 1 次 Grep/Glob：把 TRD §6/§5 中声明的关键标识（接口路径、表名、关键字段名、错误码常量）
  在 `code_paths` 内查找一遍。
- 命中且签名/字段一致 → 不报；
- 命中但**字段拼写、类型、参数顺序与 TRD 不一致** → 登记 `severity=major`，hard_gate_id 留空，
  `issue` 注明"代码已存在 X，但 TRD §Y.Z 字段定义与代码不符（字面对照见 …）"；
- 完全找不到 → 不强报（可能是新增），但要在 `summary` 提一句"未在已有代码中找到 X，按新增处理"。

若 `code_paths` 空：跳过本步，但要在 `summary` 写"无代码对账"。

### Step 3.7 · KB 规范对账（v1.2 新增 · 四位一体的"KB"维度）

若 `reviewer_inputs.knowledge_base_paths` 非空：

- 至少 Read 一个根目录下的 INDEX.md / KB.md，找出与 TRD 主题相关的章节；
- 检查 TRD 是否违反 KB 中已沉淀的硬规范（缓存一致性、内存规范、写后即读禁止、go 设计哲学等）；
- 违反 → `severity=blocking`，hard_gate_id 留空但在 `issue` 写明"违反 KB : 的 "。

若 `knowledge_base_paths` 空：跳过本步，但要在 `summary` 写"无 KB 对账"。

### Step 4 · 登记 issue

每条 issue 必须包含（参考 `review_report.schema.json`）：

- `id`: iss-001 递增
- `severity`: blocking / major / minor
- `hard_gate_id`: 对应闸门 ID（语义层发现可留空，但必须在 `issue` 里说明"脚本不抓，这是语义糊弄"）
- `location`: 行号 + 章节名 + 命中片段（≤120 字）
- `issue`: **说为什么是问题**，不要只贴原文
- `suggested_fix`: **具体怎么改**，例如"把『与 PRD 联动一致』替换为如下 8 行入参表：字段名/类型/必填/含义/示例/校验规则"
- `fix_type`: 优先用 `str_replace`（给出 `old_text` / `new_text`），复杂场景用 `section_rewrite`

### Step 5 · 决策 approved

- 存在任何 `severity=blocking` → `approved=false`
- 只有 `minor` → `approved=true`（并在 summary 说明保留的建议）
- 存在 `major` → `approved=false`（主 Agent 会再修）
- 零 issue → `approved=true`

### Step 6 · 写出报告（含 JSON 转义铁律）

把结构化 JSON **写到** `reviewer_output_path`。必须通过 `reviewer_output_schema` 校验。

【JSON 转义铁律 · 0 容忍 · v1.2 新增】

1. 任何 issue 字符串里出现的 `"` 必须写成 `\"`；任何裸换行必须写成 `\n` 字面量。
2. 严禁直接复制 TRD 原文（含中文双引号 / 圆角引号 / 嵌套引号）粘进 JSON 字符串字段而不做转义。
3. 写完后必须执行**两步自检**：
   - 用 Read 工具读出 `reviewer_output_path` 全文；
   - 跑 `python3 -m json.tool `（或脑内逐字符校验）；通过才算交付。
4. 如果你发现自己写的 JSON 自检不通过，**当场就在写完前重写**——不要把烂 JSON 留给主 Agent，
   主 Agent 端的状态机会直接 `action=redispatch_reviewer` 把你重派回来再做一遍。

报告顶层必须包含 `execution_proof`，用于主 Agent 判断这份报告是否来自指定 reviewer 子 Agent：

```json
{
  "required_subagent_type": "prd-to-trd-reviewer",
  "declared_runtime": "claude-code-task",
  "self_attestation": "我是独立 reviewer 子 Agent，不是主 Agent 自评，也没有运行 run_review.py"
}
```

**不要在终端另外打印长篇分析**——你的工作就是那份 JSON。

## 禁区

- 禁止修改 TRD 本体。
- 禁止生成新章节/新字段塞给主 Agent。
- 禁止回复"大体不错"这种笼统结论；每条结论必须可执行。
- 禁止调用生成类 skill（如 prd-to-trd）。
- 禁止根据自己的喜好调整 doc_type 风格；只看是否符合 `style_profile`。

## 输出样板

```json
{
  "approved": false,
  "reviewer_skill": "prd-to-trd-reviewer",
  "reviewer_skill_version": "1.0",
  "execution_proof": {
    "required_subagent_type": "prd-to-trd-reviewer",
    "declared_runtime": "claude-code-task",
    "self_attestation": "我是独立 reviewer 子 Agent，不是主 Agent 自评，也没有运行 run_review.py"
  },
  "summary": "脚本硬闸门通过；语义层发现 2 处 blocking、1 处 major：字段来源凑数 + 入参表基础设施污染 + 用户重点『批量导入回滚机制』未在 §5.5 落地",
  "issues": [
    {
      "id": "iss-001",
      "severity": "blocking",
      "hard_gate_id": "API_FIELD_SOURCE_DECLARATION",
      "location": {"line": 312, "section": "5.5 批量导入", "snippet": "字段来源：参见 PRD 相关章节"},
      "issue": "『参见 PRD 相关章节』违反 TRD 自包含原则且字段来源三维度全部缺失。脚本硬闸门只抓关键词，未抓到此处的变种措辞",
      "suggested_fix": "替换为三行字段来源子块：数据模型→question 表 title/answer/difficulty 字段；对应页面→§6.4 批量导入页 Excel 列；派生规则→导入时 uploader_uid 写入当前操作者",
      "fix_type": "str_replace",
      "old_text": "字段来源：参见 PRD 相关章节",
      "new_text": "字段来源：\n- 数据模型：question 表 (title/answer/difficulty/category_id)\n- 对应页面：§6.4 批量导入页面 Excel 模板列\n- 派生规则：uploader_uid ← 当前登录管理员 uid；created_at ← 服务端时间"
    }
  ],
  "unresolvable_notes": []
}
```

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [xurb-nexus](https://github.com/xurb-nexus)
- **Source:** [xurb-nexus/nexus-harness](https://github.com/xurb-nexus/nexus-harness)
- **License:** Apache-2.0
- **Homepage:** https://xurb-nexus.github.io/nexus-harness/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-xurb-nexus-nexus-harness-prd-to-trd-reviewer
- Seller: https://agentstack.voostack.com/s/xurb-nexus
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.