Back to Details

review-docs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
Review a front-door doc (default 
README.md
; honor a path the user names) the way real readers would — not the way the author does. The author knows what every line means; a first-time reader does not. The job is to surface where a specific audience gets confused, under-served, or bounces, score it, and propose concrete fixes.
The method is fan-out: spawn one subagent PER PERSONA, all in parallel, each doing a cold read as that reader. Different readers catch different things; running them concurrently is faster and keeps each read uncontaminated by the others.
以真实读者而非作者的视角评审门户文档（默认是
README.md
；可遵循用户指定的路径）。作者清楚每一行的含义，但首次阅读的读者并不清楚。本次任务是找出特定受众感到困惑、需求未被满足或放弃阅读的地方，给出评分，并提出具体的修复方案。
采用分支并行方法：为每个角色生成一个子代理（subagent），所有子代理并行工作，每个子代理以对应读者的身份进行首次阅读。不同的读者会发现不同的问题；并行运行不仅更快，还能避免彼此的评审结果相互干扰。

How to run it

如何运行

1. Read the target doc yourself first

1. 先自行阅读目标文档

Read the doc in full and skim the docs it links to (so "promises depth the linked doc doesn't deliver" is checkable). You need this to judge the personas' findings and to apply fixes later.
完整阅读文档，并浏览其链接的其他文档（这样就能检查“文档承诺的深度在链接文档中未体现”这类问题）。你需要通过这一步来判断各角色的评审结果，并在后续应用修复方案。

2. Fan out one subagent per persona — in parallel

2. 为每个角色生成子代理——并行运行

Spawn the personas below as subagents in a single message (multiple Agent/Task calls at once) so they run concurrently. Use a fast, cheap model (Sonnet or Haiku) — this is a reading/judgment task, not heavy synthesis — and say so in one line when you launch them.
Give EACH subagent the same rubric, only the persona changes:
You are <PERSONA>. Read 
<path>
(ignore any HTML comment block at the top — that's internal authoring notes, not user-facing copy). Do a COLD read as this reader: adopt their goals, vocabulary, and patience. Be a harsh grader — most READMEs are a 3; 5/5 means you'd genuinely act on it and it's crisp end to end. Return ONLY:
  1. SCORE: x/5
  2. 30-second test: after the first screen only, in one sentence, what do you think this tool does — and is that right/wrong/fuzzy?
  3. Top 3 concrete problems — each quotes the exact line/phrase and gives a specific suggested rewrite (confusing jargon, sentences carrying too many ideas, anything that doesn't sell, formatting that hurts scanning, hype that costs trust).
  4. Jargon check: every word you had to stop on (harness, spec, eval, subagent, rings, recall/precision…) — is it defined in context or left guessing?
  5. What works — keep these, so revisions don't lose them.
  6. The one change that would move the score most. Quote exact text. Be useful, not polite.
在一条消息中生成以下角色作为子代理（同时进行多个Agent/Task调用），让它们并发运行。使用快速、低成本的模型（Sonnet或Haiku）——这是一项阅读/判断任务，不需要复杂的合成——在启动时用一句话说明这一点。
为每个子代理提供相同的评分标准，仅角色不同：
你是**<角色>。阅读
<路径>
（忽略顶部的HTML注释块——那是作者的内部笔记，不是面向用户的内容）。以该读者的身份进行首次阅读**：代入他们的目标、词汇量和耐心程度。严格评分——大多数README的得分是3分；5/5意味着你会真正按照文档操作，且文档从头到尾简洁清晰。 仅返回以下内容：
  1. 评分：x/5
  2. **30秒测试：**仅看完第一屏后，用一句话说明你认为这个工具是做什么的——这个判断是正确/错误/模糊的？
  3. 三大具体问题——每个问题都引用确切的行/短语，并给出具体的改写建议（比如令人困惑的行话、承载过多信息的句子、缺乏吸引力的内容、影响阅读的格式、降低信任度的夸大表述）。
  4. **行话检查：**所有你需要停下来理解的词汇（harness、spec、eval、subagent、rings、recall/precision……）——是否在上下文中定义过，还是需要读者自行猜测？
  5. 可取之处——保留这些内容，避免修订时丢失优点。
  6. 最能提升评分的一项修改 引用确切文本。给出有用的建议，不要敷衍。

3. The personas (the fan-out set)

3. 角色（并行评审集合）

Run all of these unless the user scopes to a subset. Edit the set freely for a given doc — these are the default readers of vigiles's front door.
  1. Claude Code newcomer — new to agentic tooling, bounces on undefined terms. Needs a clear "what do I do first," not theory. Catches jargon used before it's defined.
  2. Claude Code power user — lives in CC, skimming on a phone between tasks. Wants the WOW in the first screen and a copy-paste install in seconds; allergic to fluff.
  3. Plugin / skill author — mid-level dev, comfortable with TS but not a compiler/types nerd. Found this because it claims to test their skills. Cares about "does it work on MY repo without learning a new theory?"
  4. Skeptical senior / staff engineer — scans for substance in ~20s, mentally compares to promptfoo / ESLint / ast-grep. Anything hand-wavy or overclaimed costs trust; every load-bearing claim should link proof.
  5. Decision-maker (won't run a command) — deciding whether the team adopts. Cares about cost, risk, effort; needs the "free deterministic vs. metered per-token" story and the low-risk incremental on-ramp to be legible without running anything.
  6. Codex user (optional) — uses 
    AGENTS.md
    , not Claude Code. Skeptical this is "a Claude-only thing." Is Codex support visible early or buried/footnoted?
除非用户指定子集，否则运行所有这些角色。可根据特定文档自由调整角色集合——这些是vigiles门户文档的默认读者。
  1. Claude Code 新手——刚接触智能代理工具（agentic tooling），遇到未定义的术语就会放弃阅读。需要明确的“第一步该做什么”，而不是理论内容。能发现术语在定义前就被使用的问题。
  2. Claude Code 高级用户——日常使用Claude Code（CC），在工作间隙用手机快速浏览。希望在第一屏就能看到亮点，并且能在几秒内复制粘贴完成安装；讨厌冗余内容。
  3. 插件/skill 作者——中级开发者，熟悉TS，但不是编译器/类型专家。找到这份文档是因为它声称可以测试他们的skill。关心“无需学习新理论，就能在我的仓库中运行吗？”
  4. 持怀疑态度的资深/主管工程师——约20秒内快速浏览寻找实质内容，会在心里将其与promptfoo / ESLint / ast-grep进行比较。任何含糊其辞或夸大其词的表述都会降低信任度；每个重要的声明都应链接到证据。
  5. 决策者（不执行命令）——决定团队是否采用该工具。关心成本、风险、投入；需要清晰了解“免费确定性 vs. 按token计量付费”的区别，以及无需执行任何操作就能理解的低风险渐进式入门方案。
  6. Codex 用户（可选）——使用
    AGENTS.md
    ，而非Claude Code。怀疑这是“仅适用于Claude的工具”。Codex支持是否在显眼位置展示，还是被隐藏在脚注中？

4. Synthesize

4. 综合评审结果

Collect the scores and reports. Then:
  • Cross-cutting issues first. The 2–4 problems that hurt MULTIPLE personas are the highest-leverage fixes — lead with those.
  • Lowest score is the ceiling. The doc is only as good as its weakest reader's read; name what's blocking that persona.
  • Produce a ranked fix list — highest reader-impact first, each a one-line action quoting the line and the fix.
收集所有评分和报告。然后：
  • 优先处理跨角色问题。影响多个角色的2-4个问题是最具影响力的修复点——先处理这些。
  • 最低分是上限。文档的质量取决于最弱势读者的阅读体验；指出是什么阻碍了该角色的理解。
  • 生成排序后的修复列表——按对读者的影响从高到低排序，每个修复点是引用原文行的单行操作建议。

5. Iterate to a target (only when asked)

5. 迭代至目标分数（仅在被要求时执行）

If the user asks to "get it to N/5" (or "until 5/5"): apply the highest-leverage fixes yourself, then re-fan-out (resume the same subagents with the change list, or spawn fresh) and collect new scores. Repeat until every persona is at the target or scores stop moving. Bound it — if a round produces no improvement, or after ~3 rounds, stop and report what's blocking the last point rather than churning. By default this skill REPORTS; only enter the apply-and-iterate loop on an explicit "fix it / get it to N/5".
如果用户要求“将分数提升至N/5”（或“直到5/5”）：自行应用最具影响力的修复方案，然后重新并行评审（让相同的子代理查看修改列表，或生成新的子代理）并收集新的评分。重复此过程，直到所有角色都达到目标分数，或分数不再提升。设置边界——如果一轮修改后没有提升，或经过约3轮后，停止并报告阻碍最后一分提升的问题，而非继续无效迭代。默认情况下，该技能仅生成报告；只有在明确收到“修复它 / 将分数提升至N/5”的请求时，才进入应用修复并迭代的流程。

Output format

输出格式

undefined
undefined

Doc review — <file>

文档评审 — <文件名>

Scores

评分

<persona> — x/5 (one-line verdict each)
<角色> — x/5 （每个角色一句话结论）

Cross-cutting issues (highest leverage)

跨角色问题（最高影响力）

The 2–4 problems hitting multiple personas, each with the line + the fix.
影响多个角色的2-4个问题，每个问题包含原文行和修复建议。

Per-persona highlights

各角色重点发现

The sharpest single finding from each reader (don't dump the full reports).
每个读者最尖锐的单一发现（不要输出完整报告）。

Ranked fixes

排序后的修复列表

Ordered, highest reader-impact first — each a one-line action.

Keep the synthesis scannable and ACTIONABLE: every finding names a line and a fix. Hold
the doc to its own standards while reviewing — for the README that's the front-door
brevity bar (lead with benefits, one idea per sentence, define jargon at first use,
push depth into linked docs). Don't rewrite the doc in place unless the user asks for
the iterate loop — this skill REPORTS by default.
按对读者的影响从高到低排序——每个修复点是单行操作建议。

保持综合结果易于浏览且**可执行**：每个发现都要引用原文行并给出修复建议。评审时要让文档符合自身的标准——对于README来说，就是门户文档的简洁标准（以优势开头，一句话一个观点，首次使用行话时就定义，将详细内容放到链接文档中）。除非用户要求进入迭代流程，否则不要直接重写文档——该技能默认仅生成报告。