---
name: review-document
description: Review a document's contents using a structured 3-tier severity checklist (問題, 要確認, 提案).
argument-hint: "Relative path of the document to review"
---

Read and review the contents of a target document in the workspace using a structured checklist with three severity levels (問題, 要確認, 提案).

## Review Checklist

### 1. 問題 (Issue/Problem - High Severity)

Critical errors, logic flaws, or gaps that must be corrected.

-   **矛盾・論理の破綻 (Contradictions & Logic Flaws)**: Internal contradictions, conflicting instructions, or logical inconsistency.
-   **致命的な記述漏れ・不明瞭さ (Critical Missing Info / Ambiguity)**: Essential details, prerequisites, or parameters that are missing or so ambiguous that they prevent understanding.
-   **参照・リンク切れ (Broken Links & References)**: References to files, directories, code symbols, or URLs that do not exist or are incorrect.
-   **事実誤認 (Factual Errors)**: Plainly incorrect technical assumptions, wrong version numbers, or inaccurate claims.

### 2. 要確認 (Needs Confirmation/Clarification - Medium Severity)

Items that require clarification or validation from the user/stakeholders.

-   **前提条件の妥当性 (Unstated / Ambiguous Assumptions)**: Implicit dependencies, target environments, or prerequisites that should be explicitly confirmed (e.g., assumptions about OS, versions, API access).
-   **用語の不整合・定義不足 (Inconsistent / Undefined Terminology)**: Terminology inconsistency (用語の揺れ) or domain-specific jargon used without clear definition.
-   **技術的実現性・リスク (Feasibility & Risks)**: Requirements or implementation details that seem excessively complex, high-risk, or potentially incompatible.
-   **構造・構成の乱れ (Structural / Formatting Inconsistency)**: Inconsistent layout, numbering, heading levels, or stylistic approaches that obscure readability.

### 3. 提案 (Suggestion/Recommendation - Low Severity)

Constructive ideas to improve clarity, aesthetics, or user experience.

-   **可読性・明瞭性の向上 (Readability & Clarity)**: Simplifying complex sentences, converting blocks of text into bullet points/tables, or adding diagrams (e.g., Mermaid).
-   **体裁・構成の改善 (Visual & Formatting Enhancements)**: Cosmetic adjustments, such as leveraging appropriate Markdown syntax (like code blocks, alert blocks, clean links).
-   **ベストプラクティスの適用 (Best Practices)**: Alignment with industry standard terminology, standard formatting guidelines, or repository-specific style conventions.

---

## Execution Flow

1.  **Locate Target File**:
    -   If a file path is provided as an argument, use it as the target.
    -   If no argument is provided, prompt the user to specify the file path.
2.  **Read Content**:
    -   Read the file content.
3.  **Conduct Review**:
    -   Analyze the document line-by-line or section-by-section against the checklist.
4.  **Save Report to File**:
    -   Save the formatted review report to `.review/[relative-path-to-target-document]` relative to the project root (e.g., if target is `docs/AGENTS.md`, save the report to `.review/docs/AGENTS.md`, and if target is `GEMINI-jp.md`, save to `.review/GEMINI-jp.md`).
    -   Ensure the directories inside `.review/` are created automatically if they do not exist.
    -   If the report file already exists, overwrite it with the new review content.
5.  **Output Report**:
    the saved file.

---

## Output Report Format

Output the review report using the following structure:

```markdown
# Document Review Report: [file basename]

Review of: `[relative/path/to/file]`

## Executive Summary

| Severity | Count | Key Focus |
| --- | --- | --- |
| 🔴 問題 (High) | 0 | Critical issues requiring immediate correction |
| 🟡 要確認 (Medium) | 0 | Items requiring user confirmation or alignment |
| 🟢 提案 (Low) | 0 | Suggestions for readability and quality |

---

## Detailed Findings

### 🔴 問題 (High Severity)
*List critical issues.*

- **[Short Summary of Issue]**
  - **Location**: Line X-Y / Section name
  - **Original Text**: `[original text]`
  - **Description**: [Why it is a problem]
  - **Recommended Action**: [Specific, actionable fix]

### 🟡 要確認 (Medium Severity)
*List items needing confirmation.*

- **[Short Summary]**
  - **Location**: Line X-Y / Section name
  - **Original Text**: `[original text]`
  - **Description**: [What needs confirmation and why]
  - **Recommended Action**: [Specific clarification questions or options]

### 🟢 提案 (Low Severity)
*List suggestions.*

- **[Short Summary]**
  - **Location**: Line X-Y / Section name
  - **Original Text**: `[original text]`
  - **Description**: [How it could be improved]
  - **Recommended Action**: [Concrete suggested text or structure]
```
