benedictking/benedictking-skills/codex-review

Codex Code Review Skill

Trigger Conditions

Triggered when user input contains:

• "代码审核", "代码审查", "审查代码", "审核代码"
• "review", "code review", "review code", "codex 审核"
• "帮我审核", "检查代码", "审一下", "看看代码"

Core Concept: Intention vs Implementation

Running codex review --uncommitted alone only shows AI "what was done (Implementation)". Recording intention first tells AI "what you wanted to do (Intention)".

"Code changes + intention description" as combined input is the most effective way to improve AI code review quality.

Skill Architecture

This skill operates in two phases:

1. Preparation Phase (current context): Check working directory, update CHANGELOG
2. Review Phase (isolated context): Invoke Task tool to execute Lint + codex review (using context: fork to reduce context waste)

Execution Steps

0. [First] Check Working Directory Status

git diff --name-only && git status --short

Decide review mode based on output:

• Has uncommitted changes → Continue with steps 1-4 (normal flow)
• Clean working directory → Assess HEAD with the same difficulty criteria, then invoke codex review --commit HEAD with the matching model configuration

1. [Mandatory] Check if CHANGELOG is Updated

Before any review, must check if CHANGELOG.md contains description of current changes.

# Check if CHANGELOG.md is in uncommitted changes
git diff --name-only | grep -E "(CHANGELOG|changelog)"

If CHANGELOG is not updated, you must automatically perform the following (don't ask user to do it manually):

1. Analyze changes: Run git diff --stat and git diff to get complete changes
2. Auto-generate CHANGELOG entry: Generate compliant entry based on code changes
3. Write to CHANGELOG.md: Use Edit tool to insert entry at top of [Unreleased] section
4. Continue review flow: Immediately proceed to next steps after CHANGELOG update

Auto-generated CHANGELOG entry format:

## [Unreleased]
 
### Added / Changed / Fixed
 
-Feature description: what problem was solved or what functionality was implemented
-Affected files: main modified files/modules

Example - Auto-generation Flow:

1. Detected CHANGELOG not updated
2. Run git diff --stat, found handlers/responses.go modified (+88 lines)
3. Run git diff to analyze details: added CompactHandler function
4. Auto-generate entry:
   ### Added
   - Added `/v1/responses/compact` endpoint for conversation context compression
   - Supports multi-channel failover and request body size limits
5. Use Edit tool to write to CHANGELOG.md
6. Continue with lint and codex review

2. [Critical] Stage All New Files

Before invoking codex review, must add all new files (untracked files) to git staging area, otherwise codex will report P1 error.

# Check for new files
git status --short | grep "^??"

If there are new files, automatically execute:

# Safely stage all new files (handles empty list and special filenames)
git ls-files --others --exclude-standard -z | while IFS= read -r -d '' f; do git add -- "$f"; done

Explanation:

• -z uses null character to separate filenames, correctly handles filenames with spaces/newlines
• while IFS= read -r -d '' reads filenames one by one
• git add -- "$f" uses -- separator, correctly handles filenames starting with -
• When no new files exist, loop body doesn't execute, safely skipped
• This won't stage modified files, only handles new files
• codex needs files to be tracked by git for proper review

3. Evaluate Task Difficulty and Invoke codex-runner

Count change scale:

# Get summary line for ALL changes (staged + unstaged)
# IMPORTANT: Must use 'HEAD' as base to include both staged and unstaged changes
git diff --stat HEAD | tail -1

For a clean working directory, assess the latest commit instead:

git show --stat --format= HEAD | tail -1

Why use `git diff --stat HEAD`:

• git diff --stat only shows unstaged changes
• git diff --cached --stat only shows staged changes
• git diff --stat HEAD shows BOTH staged and unstaged changes combined
• The last line (tail -1) is the summary line with total file count and line changes

Difficulty Assessment Criteria:

Model + Reasoning Effort Combinations:

选型由 scripts/select-review-model.mjs 根据实时 codexradar 智商/成本/耗时数据驱动决定：

1. 先判定难度等级（Normal / Difficult / Critical）
2. 调用脚本获取该难度下的推荐 model + effort（以及按实测耗时推导的 timeout）

脚本指标与 codexradar 站点「综合成本 × 智力」图表同量纲：

• iq = p / n * 150（0-150 刻度）
• price = mean(actual_cost_usd)；minutes = mean(duration_sec) / 60

选型主约束是实测平均耗时（时间预算），每档一个目标函数，在全部 model × effort 组合上全局比较：

• 普通 = 平均耗时 ≤ 25min 且 IQ ≥ 80 的组合里最便宜者（日常审查省钱优先，但保证 IQ > 80）
• 困难 = 平均耗时 ≤ 28min 的组合里 IQ 最高者；IQ 并列容差（<1.5）内取更便宜者
• 关键 = 同困难，但时间预算放宽到 45min

两条规则合起来天然落在成本-智力 Pareto 前沿上：

• 时间预算排除慢档（避免选到平均耗时远超预期的"高 effort 慢档"）。
• IQ 并列容差避免为噪声级 IQ 差付数倍成本，也让"贵而不智"的档（如 sol max 比 sol xhigh 贵还弱）不会中选。

超时不再写死：timeout = ceil(实测平均分钟 × 2)，随选中档位走，由脚本输出的 timeoutMinutes / timeoutMs 给出。fallback 候选也各带自己的 timeout，重试时用它自己的时限。

脚本内置 1 小时 TTL 缓存（~/.cache/codex-review/radar.json），网络与缓存都不可用时回退到保守默认值：

时间预算与 IQ 下限可用 --max-minutes / --iq-floor 覆盖（分钟 / 0-150 刻度）。若时间预算内无组合达标，脚本退化为取全局最高 IQ，不会无解。

Model Fallback Policy:

• Determine availability from the actual codex review result. Do not use codex debug models as a preflight gate.
• Treat only explicit model or reasoning-effort availability failures as a fallback trigger, such as a model not found, unavailable model access, or an unsupported reasoning effort.
• Do not fall back for review findings, lint failures, authentication or network failures, timeouts, or a model-metadata warning when the review has started.
• Dynamic fallback chain: use the fallback array returned by select-review-model.mjs, ordered by descending IQ. Each entry is from a different model family than the primary, because a same-family effort swap cannot work around a model-unavailable failure. Retry each candidate in order after an explicit availability failure.
• Per-candidate timeout: each fallback entry includes its own timeoutMs (derived from that candidate's measured minutes). Use it when retrying, not the primary's timeout.
• If the script itself fails or returns no fallback, use the built-in defaults as the final fallback.
• Run lint only once. On an availability failure, retry only codex review with the next candidate. Stop after exhausting the fallback chain and report the error.

Critical Tasks (meets any condition, use data-driven selection):

• Modified files ≥ 30
• Total code changes (insertions + deletions) ≥ 2000 lines
• Involves core architecture/algorithm changes (user explicitly mentioned)
• Config: Run node <skill-dir>/scripts/select-review-model.mjs --difficulty critical; use the returned primary model/effort and the returned timeoutMs as the Task timeout
• If the script is unavailable, fallback to built-in default: model=gpt-5.6-sol effort=xhigh, timeout 53 minutes

Difficult Tasks (meets any condition):

• Modified files ≥ 10
• Total code changes (insertions + deletions) ≥ 500 lines
• Single metric: insertions ≥ 300 lines OR deletions ≥ 300 lines
• Cross-module refactoring
• Config: Run node <skill-dir>/scripts/select-review-model.mjs --difficulty difficult; use the returned primary model/effort and timeoutMs
• If the script is unavailable, fallback to built-in default: model=gpt-5.6-sol effort=xhigh, timeout 53 minutes

Normal Tasks (other cases):

• Config: Run node <skill-dir>/scripts/select-review-model.mjs --difficulty normal; use the returned primary model/effort and timeoutMs
• If the script is unavailable, fallback to built-in default: model=gpt-5.6-luna effort=xhigh, timeout 47 minutes

Evaluation Method:

You MUST parse the git diff --stat HEAD output correctly to determine difficulty:

# Get the summary line (last line of git diff --stat HEAD)
git diff --stat HEAD | tail -1
# Example outputs:
# "20 files changed, 342 insertions(+), 985 deletions(-)"
# "1 file changed, 50 insertions(+)"  # No deletions
# "3 files changed, 120 deletions(-)"  # No insertions

Critical: Why the summary line matters:

• Each file shows individual stats: file.go | 171 ++++++++++++++++++++-
• Only the LAST line has the total: 6 files changed, 1341 insertions(+), 18 deletions(-)
• You must extract the last line with tail -1 to get accurate totals

Parsing Rules:

1. Extract file count from "X file(s) changed" (handle both "1 file" and "N files")
2. Extract insertions from "Y insertion(s)(+)" if present (handle both "1 insertion" and "N insertions"), otherwise 0
3. Extract deletions from "Z deletion(s)(-)" if present (handle both "1 deletion" and "N deletions"), otherwise 0
4. Calculate total changes = insertions + deletions

Important Edge Cases:

• Single file: "1 file changed" (singular form)
• No insertions: Git omits "insertions(+)" entirely → treat as 0
• No deletions: Git omits "deletions(-)" entirely → treat as 0
• Pure rename: May show "0 insertions(+), 0 deletions(-)" or omit both

Decision Logic (check in order, first match wins):

• IF file_count >= 30 OR total_changes >= 2000 → Critical (run script --difficulty critical)
• IF file_count >= 10 → Difficult (run script --difficulty difficult)
• IF total_changes >= 500 → Difficult (run script --difficulty difficult)
• IF insertions >= 300 OR deletions >= 300 → Difficult (run script --difficulty difficult)
• ELSE → Normal (run script --difficulty normal)

Example Cases:

• ⭐ "50 files changed, 2000 insertions(+), 1500 deletions(-)" → Critical task, run script --difficulty critical → use returned primary (currently gpt-5.6-sol effort=xhigh), use returned timeoutMs
• ✅ "20 files changed, 342 insertions(+), 985 deletions(-)" → Difficult task, run script --difficulty difficult → use returned primary (currently gpt-5.6-sol effort=xhigh), use returned timeoutMs
• ✅ "5 files changed, 600 insertions(+), 50 deletions(-)" → Difficult task, run script --difficulty difficult → use returned primary (currently gpt-5.6-sol effort=xhigh), use returned timeoutMs
• ❌ "3 files changed, 150 insertions(+), 80 deletions(-)" → Normal task, run script --difficulty normal → use returned primary (currently gpt-5.6-luna effort=xhigh), use returned timeoutMs
• ❌ "1 file changed, 50 insertions(+)" → Normal task, run script --difficulty normal → use returned primary (currently gpt-5.6-luna effort=xhigh), use returned timeoutMs

普通任务落在 gpt-5.6-luna effort=xhigh 是符合预期的：它是"耗时 ≤ 25min 且 IQ ≥ 80"里最便宜的（约 $0.31 / 23.5min / IQ 87.1）。在 Pareto 前沿上再往上，terra max 仅多 2.7 IQ 却要近 8 倍成本，sol max 比 sol xhigh 贵还弱——这类坏拐点都被选型规则跳过。困难/关键档当前都落在 sol xhigh：它是高价区性价比拐点（IQ 103.6 / $6.26 / 26min），比顶点 sol ultra（106.7 / $20.95 / 54min）只低 3 IQ，成本却只有 1/3。

Dynamic Model Selection Flow:

After determining the difficulty level, obtain the recommended model and effort dynamically:

# Resolve the skill directory path (adjust if your skill installation path differs)
SKILL_DIR="$(cd "$(dirname "$0")" && pwd)/scripts" 2>/dev/null || SKILL_DIR="$HOME/.claude/skills/codex-review/scripts"
MODEL_JSON=$(node "$SKILL_DIR/select-review-model.mjs" --difficulty <normal|difficult|critical>)
PRIMARY_MODEL=$(echo "$MODEL_JSON" | jq -r '.primary.model')
PRIMARY_EFFORT=$(echo "$MODEL_JSON" | jq -r '.primary.effort')
PRIMARY_TIMEOUT_MS=$(echo "$MODEL_JSON" | jq -r '.primary.timeoutMs')   # timeout derived from measured minutes