review

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:

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