---
name: project-review
description: Whole-project or single-feature code review (not diff-based) using graph-wide analysis and objective scoring
---

# Project Review

Review the entire codebase or a single feature/module, independent of the git diff.  Two scopes, driven by the user's instruction:

- **whole-project**: "对项目代码进行全面审查", "全面审查", "整个项目" → review every source file in the graph.
- **feature**: "审查 <功能/模块> 的代码" (e.g. payment, auth) → review only the code related to the target.

**This skill is READ-ONLY.** Every finding is presented to the user for a manual fix decision. Never apply code changes, commit, or push.

## Token Efficiency Rules
- ALWAYS start with `get_minimal_context(task="project review")`. Use `detail_level="minimal"` on all calls; escalate to `"standard"` only when a metric or finding needs evidence.

## Step 0 - Parse the scope

Read the user's instruction and set scope: whole-project (contains 全面/整个项目/所有/all) or feature + target (extract the feature/module keyword).  Declare both in the report header.

## Step 1 - Graph ready

1. Call `build_or_update_graph_tool()` to ensure the graph is current.
2. Call `get_minimal_context_tool(task="project review")` for stats and community overview.

## Step 2 - Architecture map

Call `get_architecture_overview_tool(detail_level="minimal")` and `list_communities_tool(detail_level="minimal")` to map the module structure.

## Step 3 - High-risk scan (whole-project)

Call `get_knowledge_gaps_tool()`, `get_hub_nodes_tool()`, `get_bridge_nodes_tool()`, `find_large_functions_tool()` and `get_surprising_connections_tool()` to locate hotspots, chokepoints, untested areas and odd coupling.

## Step 4 - Objective scoring

- whole-project: `score_review_tool(all_files=True)` scores every source file in the graph.
- feature: locate the target files with `semantic_search_nodes_tool(query=<target>)` and `query_graph_tool(pattern="children_of", target=<target>)`, then `score_review_tool(changed_files=<files>)` and `get_impact_radius_tool(changed_files=<files>)` for the blast radius.

## Step 5 - Chain decomposition

Inspect the scored code across eight categories (interface, business, data, utility, error handling, security, performance, observability) and apply the gstack CRITICAL sub-pass (SQL & Data Safety, Race Conditions, LLM Output Trust Boundary, Shell Injection, Enum Completeness).  Mark each ✅ / ⚠️ / —.

## Step 6 - Manual adjudication (READ-ONLY)

Present every finding with severity (🔴 blocker / 🟡 major / 🔵 minor), confidence (1-10), file:line and a proposed fix.  Group by severity and ask the user per batch: fix / skip / self-fix.  🔴 blockers cannot be batch-skipped.  **Do not modify code.**

## Step 7 - Acceptance gate

Any 🔴 blocker → verdict `❌ FAIL`.  Classify each finding as Ready / Needs Fix / Unusable.

## Step 7.5 - 覆盖度自检（必须执行，防"审完了"由感觉决定）

报告前完成三件事（机制未生效时禁止用 CLI 兜底继续审查）：

1. **G1 深读名单完整性**：确认名单外文件是"被评估过"而非"被忽略"；未被任何信号点名的文件记入 **"未深读文件清单"**，在报告中显式列出。
2. **G2 静默抽检**：调用 `coverage_tool` 取返回的 `silent_files`（未被任何信号点名的文件），随机抽 **15%** 深读；发现 ≥1 major → 该文件升级全量深读，并同社区/同类追加抽检一轮。抽检记录附入报告（抽了几份 / 几个 major / 有无升级）。
3. **G3 覆盖度计算**：调用 `coverage_tool(deep_read_files=<本轮实际深读文件>, gate="both+line")`，引擎自动计算**三重口径**（文件数口径 + 三件套质量口径）：
   - **全库覆盖** = `coverage_pct`（已深读文件数 / 全部源文件数）
   - **高风险覆盖** = `high_risk_coverage_pct`（已深读 / 信号点名文件，文件数口径）
   - **行/单元覆盖** = `line_coverage_pct` / `unit_coverage_pct`（gate="both+line" 时的三件套质量口径）
   - **feature（单功能）审查**：改用 `gate="line+unit"`——**只做行覆盖 ≥95% + 单元完整性无缺口**，不做全库/高风险文件数覆盖检查（`coverage_pct`/`high_risk_coverage_pct` 为 `null`，报告只渲染行/单元覆盖，不渲染全库/高风险行）。`target_reached=false` → 报告顶部标 🔴 覆盖不足。

将覆盖度结果**完整透传**到 `review_data.coverage`（直接把 `coverage_tool` 返回值全部字段传入：coverage_pct/high_risk_coverage_pct/grade/deep_read_count/total_files/high_risk_total_files/high_risk_deep_count/deep_read_weight/total_weight/target_reached/target/uncovered_files/silent_files/note），不要手挑子集，否则计数字段渲染为 0/0 或 N/A。报告会自动渲染 `## 覆盖度` 区块。

**前置健康检查**：调用 `community_health_tool`，若 `needs_postprocess=true`（nodes.community_id 归属率 <90%），先 `code-review-graph postprocess` 重建社区归属再计算，否则覆盖度失真。

## Step 8 - Report

Call `generate_report_tool(review_data=<verdict, scope, metrics, findings>)` to write `code-review-report.html` and `code-review-report.md` (default `format="both"`).  Pass `reviewed_files: [path, ...]` (the deep-read file array) — the report header renders it as a collapsible `<details>` list (falls back to the flat `files` string when absent).

**Archive naming (REQUIRED):** always pass `output_path="docs/reviews/{name}-review-{YYYY-MM-DD-HHMMSS}"` (e.g. `docs/reviews/evm-feature-review-2026-08-06-151522`). Omitting `output_path` writes to `<repo_root>/code-review-report.*` which is a naming violation.

## Step 8.6 - Report naming self-check (REQUIRED)

After generating, run the naming verifier (standalone script, independent of the CRG CLI):

```powershell
powershell -File "C:\Users\Administrator\.config\opencode\skills\project-review\verify-report.ps1" -Repo <repo_root>
```

- Exit 0 → pass: all reports under `docs/reviews/` carry a `-YYYY-MM-DD-HHMMSS` suffix.
- Exit 1 → stray root `code-review-report.*` detected. Fix by re-calling `generate_report_tool` with the correct `output_path`, or run with `-Fix` to auto-archive, then re-verify.
- Historic non-conforming names in `docs/reviews/` are warnings only — do not rename them.

## Output Format

`Project Review: N issues (X blocker, Y major, Z minor) — verdict: ✅ PASS / ❌ FAIL`.  List each issue with severity, confidence, file:line, problem, and proposed fix.

## Token Efficiency Rules
- ALWAYS start with `get_minimal_context(task="project review")` before any other graph tool.
- Use `detail_level="minimal"` on all calls. Only escalate to `"standard"` when minimal is insufficient.
- Target: complete a project review in ≤12 tool calls and ≤1800 total output tokens.