grill-with-docs

Grill with Docs

Conduct an in-depth review of an issue or PRD, combined with the project's design documents, to uncover oversights, ambiguities, and boundary problems. Your role isdevil's advocate—friendly but relentless.

The design philosophy of this skill is:The best code review happens before writing any code. Fixing a design on paper is far cheaper than fixing a design in code.

Which documents do you need

The specific documents depend on the type of ticket you are working on. Your task is to determine which documents are needed and go read them.

Reference documents:

ADR-FORMAT.md — How to read and understand ADRs
CONTEXT-FORMAT.md — How to read the project context and domain glossary

The core documents are:

PRD(created by /to-prd or drafted manually) — describes what the feature should do
The most recent related ADR — the most recent architectural decisions made in the related domain, including the alternatives listed in the ADR and the rationale for the trade-offs
Global context — obtained from CONTEXT.md / CONTEXT-MAP.md the domain glossary and high-level architecture diagram

But you should not assume which documents are relevant. List the documents you think might be relevant, go read them, and if you find more clues, keep digging deeper.

Process

1. Read the content to be reviewed

Read the issue you need to review — its body, comments, existing labels, and all PRD references.

2. Identify relevant documents

List the documents you plan to review, then go read them. For the format, refer to ADR-FORMAT.md and CONTEXT-FORMAT.md。

3. Review

Raise a series ofspecific questions(rather than general criticism). Each question must cite the document you reviewed (PRD, ADR, or context).

Do not write the review as a checklist. Each of your questions should come withan explanationexplaining why this might be a problem. A good review focuses on reasoning, not ticking boxes.

Your goal is to identify:

Design-level deviations — Does the feature conflict with the most recent ADR? Does it repeat an approach that was previously explicitly rejected?
Edge cases — What happens when the input is empty? What if the operation fails midway? What about under concurrency?
Missed alternatives — Are there other (possibly better) implementation paths that have not been considered?
Breaks in the user journey — From the user's perspective, is the interaction flow reasonable?

4. Summarize

Point out patterns — are you repeatedly hitting the same problem? If so, it may be an architectural issue rather than a problem with the feature itself.

5. Present

Present the review results as a list. Write the problems you found into a comment updated on the corresponding issue.

Review examples

1. **当协作会话有 0 个参与者时会发生什么？**
   PRD 说"协作会话允许多个用户连接"，但并没有描述当用户加入或离开时会发生什么。在最后一个参与者断开后，会话是否应该自动关闭？如果应该，由谁来负责清理？

2. **这与 ADR-003（基于 push 的同步）有冲突**
   该 PRD 描述了一个轮询模型（每 5 秒拉取一次），但 ADR-003 已经确定我们采用的是基于 push 的同步方案，并否决了轮询模型，理由是"对数据库的压力不可持续"。为什么这里回到了之前的方案？

3. **`Session.close()` 的幂等性没有定义**
   如果 `close()` 被调用了两次，会发生什么？第二次调用是静默成功、抛出异常，还是产生未定义的行为？有了这种行为定义，我们才能——
   - 决定是否允许它
   - 确定是否需要修改接口

4. **错误恢复流程没有描述**
   当协作会话中某个参与者丢失 WebSocket 连接时，PRD 并没有说明会发生什么。他们是自动重连，还是被移出会话？如果是后者，其他参与者会收到通知吗？