design-doc-reviewer（设计文档审阅者）

Design Doc Reviewer

Produce structured, actionable review feedback on a design document. Reviews should be specific — not generic praise or criticism — and directly tied to content in the doc.

The Job

1. Identify which document to review (from the user's message, or ask)
2. Read the design doc in full
3. Read the vision doc (docs/vision/vision.md) for product alignment context
4. Evaluate the doc against the quality rubric below
5. Output the review in the structured format below

Step 1: Locate the Document

If the user didn't specify a path, check docs/design/ for recent files. Ask if ambiguous. Read the doc fully before evaluating.

Also read (if they exist):

• docs/vision/vision.md or equivalent product vision doc — to check product alignment
• Any directly related existing designs or architecture docs if referenced

Step 2: Evaluate Against the Rubric

Score each element as: ✅ Present & Strong / ⚠️ Partial or Unclear / ❌ Missing

Required Elements

Quality Signals (score holistically)

• Principle-driven consistency: Do implementation choices trace back to stated principles? Or do choices feel arbitrary?
• State ownership clarity: For every piece of mutable state, is it clear who creates/reads/modifies it?
• Decision rationale: For significant architectural choices, does the doc answer "why not the alternative"?
• Concrete over abstract: Does the doc use real examples (JSON, file paths, code, CLI output) or only prose?
• Failure path coverage: Does the doc only describe the happy path, or does it address what happens when things go wrong?
• Product alignment: Does the Vision Alignment section make a substantive argument, or is it hand-waving? Does it name specific vision goals?
• Scope discipline: Is the design appropriately scoped, or is it trying to solve everything at once?

User Story Quality (evaluate each story)

Apply the Agent-Ready Test to every user story: could an AI agent implement this story without asking for more information? If "No" or "Maybe," the story needs more detail.

• Self-contained: Does each story include enough context (file paths, data contracts, relevant interfaces) that an agent doesn't need to read the full design doc?
• Acceptance criteria are binary: Every criterion must be verifiable — "works correctly" fails, "returns 404 when user ID doesn't exist" passes.
• Testing requirements present: Every story must have explicit testing AC (unit tests for logic, browser verification for UI). No exceptions.
• Documentation requirements present: Stories that add user-facing functionality, CLI flags, API endpoints, or architectural changes must include AC to update the specific doc file. "Update docs if applicable" is not acceptable — the file must be named.
• Granularity: Stories should be minimized in count but each small enough for an agent to complete in one focused session. Not over-fragmented, not combining unrelated tasks.
• Grounded in design: Do stories reference exact file paths, function names, and data contracts from the design sections? Or are they disconnected from the technical work above?

Step 3: Output the Review

Use this exact structure:

Design Doc Review: [Document Title]

File: docs/design/[filename].md Reviewed: [today's date] Overall Assessment: [1–2 sentences. What's the doc's current state? Is it ready to implement, needs revision, or needs substantial work?]

Scorecard

Score: X/21 elements present and strong

Strengths

List 2–4 specific strengths. Reference actual content from the doc (quote sections, describe specific design decisions). Don't be generic.

• [Strength title]: [specific observation with reference to doc content]

Critical Gaps (must fix before implementation)

Issues that could cause implementation problems, ambiguity, or rework. Be specific about what's missing and what the impact is.

• [Gap title]: [what's missing, why it matters, and a concrete suggestion for how to address it]

Minor Issues (should fix, but not blocking)

• [Issue title]: [what's unclear or incomplete, and how to improve it]

Additional Open Questions

Questions the doc hasn't answered that an implementer would need to resolve — beyond any already listed in the doc itself:

1. [Question]
2. [Question]

Recommended Next Steps

Prioritized list of what the author should do before this doc is ready to implement:

1. [Highest priority action]
2. [Next action]
3. ...

Output

Save the review as docs/design/review-[original-filename].md (e.g., reviewing docs/design/auth-redesign.md → save to docs/design/review-auth-redesign.md). Then tell the user the file was saved and summarize the score and top 2–3 critical gaps in a short message.

Review Principles

• Be specific, not generic. "The testing strategy is weak" is not useful. "The testing strategy lists unit tests but doesn't name a single test case or edge case" is useful.
• Quote the doc. Reference actual sections, headings, or excerpts. This proves you read it and helps the author find exactly what to fix.
• Separate blockers from polish. Critical gaps block implementation. Minor issues are improvements. Don't conflate them.
• Acknowledge what's strong. A good review isn't only criticism. Noting what works well is as important as noting what doesn't — it tells the author what not to change.
• Propose, don't just critique. For every gap, suggest what's needed. "Add an edge cases table covering: DB lock failure, OS permission denial, and partial write crash" is more useful than "edge cases are missing."
• Respect scope. Don't ask the doc to solve everything. If something is intentionally deferred, acknowledge it — don't flag it as a gap.