---

name: review description: Review specification and developer documents for compliance with project guidelines. Use when checking docs-spec/ and docs-site/docs/ for ambiguous expressions or missing required sections. allowed-tools: Read, Glob, Grep

Specification Document Reviewer

Instructions

1. Determine the review target:

   • If argument is provided: Review that specific file
   • If no argument: Find all files in docs-spec/ and docs-site/docs/ directories using Glob (exclude node_modules)

2. Read each target file

3. Apply the checks below based on file type

4. Output results in this format:

   ## [filename]
   
   ### Issues Found
   - [Line X] Issue description
     - Current: "problematic text"
     - Suggested: "improved text"
   
   ### OK (if no issues)
   No issues found.
   

---

Check Rules

Common Checks (All Files)

Prohibited Ambiguous Words

Detect these vague expressions and suggest numeric alternatives:

| Prohibited | Suggestion | |------------|------------| | 高速 | Specify: "< X ms" or "X ops/sec" | | 高品質 | Specify: "MOS > X" or "bitrate X kbps" | | 低遅延 | Specify: "RTT < X ms" or "latency < X ms" | | シンプル | Specify concrete constraints | | 柔軟 | Specify supported options explicitly | | 高い/低い (performance) | Use numeric thresholds | | 最適化 | Specify before/after metrics |

Judgment Reason Check

Flag statements that lack "why" explanation:

• Decisions without Context/Reason
• Technology choices without justification

---

architecture.md Specific

Required sections (flag if missing):

• [ ] 対応 OS (macOS / Windows / Linux)
• [ ] 使用言語 (e.g., C++20, Rust stable)
• [ ] 音声 I/O (CoreAudio / WASAPI / ALSA / PipeWire)
• [ ] ネットワーク方式 (e.g., WebRTC Native)
• [ ] codec (e.g., Opus 48kHz / 20ms)
• [ ] スレッドモデル
• [ ] リアルタイム制約 (with numeric targets)

---

ADR Files (docs-spec/adr/*.md)

Required sections:

• [ ] ## Context - Why was this decision needed?
• [ ] ## Decision - What was decided?
• [ ] ## Consequences - Trade-offs and implications

Flag if:

• Any section is missing
• Context lacks problem statement
• Decision lacks clear choice
• Consequences lacks pros/cons

---

BDD Files (docs-spec/behavior/*.feature)

Required structure:

• [ ] Feature: declaration
• [ ] At least one Scenario:
• [ ] Each scenario has Given, When, Then

Flag if:

• Then clause uses unmeasurable terms (suggest defining in architecture.md)
• Missing Given conditions for environment setup

---

API Spec Files (docs-spec/api/*.md)

Required for each API:

• [ ] API name
• [ ] 入力 (Input parameters)
• [ ] 出力 (Return value)
• [ ] スレッド制約 (Thread requirements)
• [ ] 呼び出しタイミング (When to call)

Flag if:

• Thread constraints are missing (critical for real-time audio)
• Input/output types are unspecified

---

docs-site Files (docs-site/docs/**/*.md)

Checks for developer documentation:

Ambiguous Expression Check

Apply same prohibited words as Common Checks.

Note Banner Check

Required at top of each file:

• [ ] Contains :::note banner pointing to docs-spec as source of truth

Flag if:

• Note banner is missing
• Note banner doesn't reference docs-spec

Internal Link Check

Flag if:

• Links to /docs/... paths that don't correspond to existing files
• Broken relative links

Consistency Check (intro.md only)

If file contains implementation status table:

• [ ] Phase statuses should match docs-spec/README.md

---

Example Output

## docs-spec/architecture.md

### Issues Found
- [Line 15] Ambiguous expression detected
  - Current: "低遅延な音声通信を実現"
  - Suggested: "片方向遅延 < 150ms (RTT < 50ms環境)"

- [Missing] スレッドモデル section not found
  - Suggested: Add section describing thread architecture

### Summary
- 2 issues found
- 1 required section missing

## docs-site/docs/intro.md

### Issues Found
- [Line 14] Ambiguous expression detected
  - Current: "超低レイテンシ"
  - Suggested: Use specific value (e.g., "10ms以下" as already stated on line 22)

### OK
- Note banner present (line 7-10)
- Internal links valid