AGENT SKILL

x-review-pr

Tech Lead holistic review with 45-point checklist covering Clean Code, SOLID, architecture, framework conventions, tests, TDD process, security, and cross-file consistency. Produces GO/NO-GO decision. Use for final review before merge.

License 许可
MIT
最近更新
2026-10-27
Stars
★ 0
Forks
1

01 前言 Front Matter

name
x-review-pr
description
Tech Lead holistic review with 45-point checklist covering Clean Code, SOLID, architecture, framework conventions, tests, TDD process, security, and cross-file consistency. Produces GO/NO-GO decision. Use for final review before merge.
allowed-tools
Read, Write, Edit, Bash, Grep, Glob, AskUserQuestion, Skill
argument-hint
[PR-number or STORY-ID] [--no-auto-remediation] [--interactive] [--non-interactive] [--resume-review <pr>]
context-budget
heavy
user-invocable
true
requires-capabilities
[]

02 资源文件 2

03 SKILL.md 正文

Global Output Policy

  • Language: English ONLY.
  • Tone: Technical, Direct, and Concise.
  • Efficiency: Remove all conversational fillers and greetings to save tokens.

Skill: Review PR (Tech Lead Review)

Purpose

Execute a senior-level holistic review with a 45-point rubric. This is the standalone version of Phase 6 from x-implement-story. The Tech Lead reviews the consolidated PR diff for cross-file consistency and overall quality.

Triggers

  • /x-review-pr — review current branch against main
  • /x-review-pr NNN — review PR #NNN
  • /x-review-pr STORY-ID — review by story ID

Prerequisites

  • Code must be committed
  • Branch should have changes relative to main
  • Ideally, specialist reviews (/x-review-codebase) have already been run

Workflow

Five phases (Rule 25 REGRA-001, EPIC-0055). Each opens with TaskCreate + --mode pre gate, closes with TaskUpdate(completed) + POST/FINAL gate. P3 iterates sub-tasks per cycle. Mapping: P0 Context (Steps 0-3) · P1 Review (Step 4) · P2 Verdict (Steps 5,7) · P3 Remediation (Steps 6,8, iterative) · P4 Final approval.

<!-- phase-no-gate: read-only pre-check + context gathering; no artifact produced until Phase 1 -->

Phase 0 — Context & idempotency

Open (close with TaskUpdate(id: phase0TaskId, status: "completed") after Step 3):

TaskCreate(subject: "{STORY_ID} › Review-PR › Phase 0 - Context", activeForm: "Loading PR context")

Step 0 — Idempotency Pre-Check (RULE-002 — Artifact reuse)

Before executing the Tech Lead review, check if a report already exists and is still valid.

  1. Extract story ID from argument or branch name (e.g., story-XXXX-YYYY)
  2. Derive epic directory: ai/epics/epic-XXXX/reviews/
  3. Check if Tech Lead report exists:
    ls ai/epics/epic-XXXX/reviews/review-tech-lead-story-XXXX-YYYY.md 2>/dev/null
    
  4. If report exists AND the branch has no new commits since last report:
    # Compare report mtime with latest commit date
    stat -c %Y ai/epics/epic-XXXX/reviews/review-tech-lead-story-XXXX-YYYY.md 2>/dev/null
    git log -1 --format=%ct HEAD
    
    • If mtime(report) >= commit_date: log Reusing existing tech lead review from {date} and skip to Step 5 (dashboard update)
    • If code changed after report: proceed with full review
  5. If no report exists, proceed normally

Idempotency Summary:

Aspect Behavior
Check Compare mtime(report) vs mtime(latest commit)
Skip Reuse existing report when mtime(report) >= commit_date
Override Proceed with full review when code changed after report

Step 1 — Detect Context

Determine what to review and set [BASE_BRANCH]:

  • PR number: gh pr view NNN --json title,body,baseRefName,headRefName,files
  • STORY reference: Find and checkout the branch
  • No argument: Use current branch, BASE_BRANCH=main

Validate diff exists:

git diff [BASE_BRANCH] --stat
git diff [BASE_BRANCH] --name-only

Step 2 — Gather Context

Read knowledge packs to calibrate the review:

  • knowledge/coding-standards/coding-conventions.md — {{LANGUAGE}} naming, injection, mapper conventions
  • knowledge/architecture/architecture-principles.md — layer boundaries, dependency direction
  • rules/05-quality-gates.md — coverage thresholds, merge checklist
  • knowledge/testing/testing-philosophy.md — TDD workflow, Double-Loop TDD, TPP ordering

Check for existing artifacts (extract epic ID XXXX and story sequence YYYY from story ID):

  • Specialist review reports (ai/epics/epic-XXXX/reviews/review-*-story-XXXX-YYYY.md)
  • Implementation plan (ai/epics/epic-XXXX/plans/plan-story-XXXX-YYYY.md)
  • Test plan (ai/epics/epic-XXXX/plans/tests-story-XXXX-YYYY.md)
  • Common mistakes document

Step 3 — Template Detection

Before executing the review, check if the Tech Lead review template exists:

test -f .claude/templates/_TEMPLATE-TECH-LEAD-REVIEW.md && echo "TL_TEMPLATE_AVAILABLE" || echo "TL_TEMPLATE_MISSING"
  • If TL_TEMPLATE_AVAILABLE: Read template at .claude/templates/_TEMPLATE-TECH-LEAD-REVIEW.md for required output format. Follow ALL sections defined in the template. The report MUST include a standardized header with Story ID, Date, Author (Tech Lead), and Template Version (RULE-011 — Standardized artifact headers). Score MUST be in format XX/45 with status GO/NO-GO (RULE-005 — Quality gates).
  • If TL_TEMPLATE_MISSING: log warning Template not found, using inline format and use the inline format as fallback (RULE-012 — Graceful template fallback). Dashboard and remediation updates are skipped when template is absent.

Fallback (RULE-012 — Graceful template fallback): When template is not available (pre-EPIC-0024 projects), the current inline format is used as fallback. Skip dashboard and remediation updates since they depend on template-based artifacts.

Persist interactiveMode to execution-state.json (EPIC-0068 — consumed by Stop hook enforce-continuous-flow.sh):

Skill(skill: "x-internal-update-status", args: "--file ai/epics/epic-XXXX/execution-state.json --type story --id <STORY-ID> --field interactiveMode --value <interactive|non-interactive>")

Value: "interactive" when --interactive passed or CLAUDE_LEGACY_INTERACTIVE=1; otherwise "non-interactive" (Rule 20 default, EPIC-0061).

TaskUpdate(id: phase0TaskId, status: "completed")

Phase 1 — Execute 45-point review

Open a phase tracker; PRE gate ensures Phase 0 completed:

Skill(skill: "x-internal-verify-phase-gates", model: "haiku", args: "--mode pre --skill x-review-pr --phase Phase-1-Review")
TaskCreate(subject: "{STORY_ID} › Review-PR › Phase 1 - Review", activeForm: "Running 45-point tech-lead review")

Close with TaskUpdate(id: phase1TaskId, status: "completed") + POST gate after Step 4 finishes (the rubric execution is the evidence):

Skill(skill: "x-internal-verify-phase-gates", model: "haiku", args: "--mode post --skill x-review-pr --phase Phase-1-Review --expected-artifacts ai/epics/epic-XXXX/reviews/review-tech-lead-story-XXXX-YYYY.md")

Step 4 — Execute Tech Lead Review

The Tech Lead review covers:

  1. List ALL modified files: git diff [BASE_BRANCH] --name-only
  2. View FULL diff: git diff [BASE_BRANCH]
  3. For EACH source file, read FULL content and apply 45-point checklist
  4. Focus on CROSS-FILE issues (inconsistencies, cross imports, repeated patterns)
  5. Compile and verify: {{COMPILE_COMMAND}} + {{BUILD_COMMAND}}
  6. Execute full test suite (MANDATORY — EPIC-0042):
    {{TEST_COMMAND}}
    
    • If ANY test fails: record test failures in report AND set decision to automatic NO-GO (overrides rubric score)
    • Log each failing test name and failure reason in the report under a dedicated Test Execution Results section
  7. Execute coverage analysis (MANDATORY — EPIC-0042):
    {{COVERAGE_COMMAND}}
    
    • If line coverage < 95% or branch coverage < 90%: record as CRITICAL finding in report
    • Include coverage percentages in the Test Execution Results section
    • Absolute-gate note (Rule 05 RULE-005-01): the gate fires regardless of whether the deficit was caused by this PR or was pre-existing on the base branch. The Tech Lead MUST NOT override NO-GO with a "pre-existing" justification. The only permitted escape paths are: (a) close the gap in this PR, (b) close it in a predecessor PR, or (c) merge an approved ADR that temporarily lowers the gate for a specific package (with sunset date).
  8. Execute smoke tests (CONDITIONAL — EPIC-0042, only when testing.smoke_tests == true):
    {{SMOKE_COMMAND}}
    
    • If ANY smoke test fails: record as CRITICAL finding AND set decision to automatic NO-GO
    • If testing.smoke_tests == false: log "Smoke tests skipped (testing.smoke_tests=false)" and proceed
  9. If specialist reports exist, verify CRITICAL issues were fixed

45-Point Rubric

Section Points What it checks
A. Code Hygiene 8 Unused imports/vars, dead code, warnings, method signatures, magic
B. Naming 4 Intention-revealing, no disinformation, meaningful distinctions
C. Functions 5 Single responsibility, size <= 25 lines, max 4 params, no flags
D. Vertical Formatting 4 Blank lines between concepts, Newspaper Rule, class size <= 250
E. Design 3 Law of Demeter, CQS, DRY
F. Error Handling 3 Rich exceptions, no null returns, no generic catch
G. Architecture 5 SRP, DIP, architecture layer boundaries (per project rules), follows plan
H. Framework & Infra 4 DI, externalized config, native-compatible, observability
I. Tests & Execution 6 ALL tests pass, coverage >= 95%/90%, smoke tests pass, test quality
J. Security & Production 1 Sensitive data protected, thread-safe
K. TDD Process 5 Test-first commits, Double-Loop TDD, TPP progression, atomic cycles

Decision Criteria

Condition Decision
>= 38/45 + zero issues GO
< 38/45 OR any issue NO-GO
ANY test failure (unit, integration, or smoke) NO-GO (automatic, overrides score)
Coverage below 95% line OR 90% branch NO-GO (automatic, overrides score — absolute gate per Rule 05 RULE-005-01; pre-existing deficits are NOT an excuse)

Phase 2 — Compile verdict & publish dashboard

Open a phase tracker (PRE gate: Phase 1 must have completed):

Skill(skill: "x-internal-verify-phase-gates", model: "haiku", args: "--mode pre --skill x-review-pr --phase Phase-2-Verdict")
TaskCreate(subject: "{STORY_ID} › Review-PR › Phase 2 - Verdict", activeForm: "Compiling GO/NO-GO verdict")

Close with TaskUpdate(id: phase2TaskId, status: "completed") + POST gate after Step 7:

Skill(skill: "x-internal-verify-phase-gates", model: "haiku", args: "--mode post --skill x-review-pr --phase Phase-2-Verdict --expected-artifacts ai/epics/epic-XXXX/reviews/dashboard-story-XXXX-YYYY.md")

Step 5 — Update Consolidated Dashboard

After saving the Tech Lead report, update the consolidated dashboard (RULE-006).

The dashboard is cumulative (RULE-006): created by /x-review-codebase (specialist scores), updated by /x-review-pr (Tech Lead Score).

  1. Check if dashboard exists:

    test -f ai/epics/epic-XXXX/reviews/dashboard-story-XXXX-YYYY.md && echo "DASHBOARD_EXISTS" || echo "DASHBOARD_MISSING"
    
  2. If dashboard exists (created by x-review-codebase):

    • Read ai/epics/epic-XXXX/reviews/dashboard-story-XXXX-YYYY.md
    • Update the Tech Lead Score section: replace placeholder --/45 | Status: Pending with actual score XX/45 | Status: GO/NO-GO
    • Update the Overall Score to include Tech Lead score in the total
    • Update the Overall Status considering both specialist scores and Tech Lead decision: status is updated to reflect all 8 specialists + Tech Lead combined assessment
    • Append a new Round to the Review History section with date, Tech Lead score, and status
    • Preserve all existing specialist scores and previous rounds
  3. If dashboard does not exist (x-review-codebase was not executed):

    • Log: Dashboard not found, creating fresh dashboard
    • Check dashboard template:
      test -f .claude/templates/_TEMPLATE-CONSOLIDATED-REVIEW-DASHBOARD.md && echo "DASHBOARD_TEMPLATE_AVAILABLE" || echo "DASHBOARD_TEMPLATE_MISSING"
      
    • If template available: read template and create ai/epics/epic-XXXX/reviews/dashboard-story-XXXX-YYYY.md with only the Tech Lead Score populated (specialist scores marked as -- / Pending)
    • If template missing: skip dashboard creation with warning

<!-- phase-no-gate: remediation is iterative by nature; each cycle K emits its own sub-task. Gate would fire inside the loop. -->

Phase 3 — Remediation loop (iterative)

Runs only on NO-GO (or --no-auto-remediation bypass at Step 8.4). Each cycle chained via addBlockedBy, cap 3 per Rule 20:

TaskCreate(subject: "{STORY_ID} › Review-PR › Phase 3 - Remediation cycle 1", activeForm: "Running remediation cycle 1")
TaskUpdate(id: cycle1Id, status: "completed")
TaskCreate(subject: "{STORY_ID} › Review-PR › Phase 3 - Remediation cycle 2", activeForm: "Running remediation cycle 2") /* addBlockedBy: [cycle1Id] */
TaskUpdate(id: cycle2Id, status: "completed")

On convergence (GO) or exhaustion (REVIEW_REMEDIATION_EXHAUSTED / REVIEW_FIX_LOOP_EXCEEDED), proceed to Phase 4.

Step 6 — Update Remediation Tracking

After updating the dashboard, update the remediation tracking file.

  1. Check if remediation exists:

    test -f ai/epics/epic-XXXX/reviews/remediation-story-XXXX-YYYY.md && echo "REMEDIATION_EXISTS" || echo "REMEDIATION_MISSING"
    
  2. If remediation exists (created by x-review-codebase):

    • Read ai/epics/epic-XXXX/reviews/remediation-story-XXXX-YYYY.md
    • For each finding in the remediation tracker:
      • If the Tech Lead confirms the finding is fixed (code reviewed and issue resolved): update status from Open -> Fixed
      • If the finding remains unfixed: keep status as Open
    • Add new findings identified by the Tech Lead that are not present in the existing remediation tracker, with status Open
    • Update the Remediation Summary counts to reflect new statuses
  3. If remediation does not exist (x-review-codebase was not executed):

    • Log: Remediation not found, creating fresh remediation with Tech Lead findings
    • Check remediation template:
      test -f .claude/templates/_TEMPLATE-REVIEW-REMEDIATION.md && echo "REMEDIATION_TEMPLATE_AVAILABLE" || echo "REMEDIATION_TEMPLATE_MISSING"
      
    • If template available: read template and create ai/epics/epic-XXXX/reviews/remediation-story-XXXX-YYYY.md with only findings from the Tech Lead review (all as Open)
    • If template missing: skip remediation creation with warning

Phase 4 — Final approval & report

Open a phase tracker (PRE gate: Phase 2 verdict must be resolved; Phase 3 may have run):

Skill(skill: "x-internal-verify-phase-gates", model: "haiku", args: "--mode pre --skill x-review-pr --phase Phase-4-Approval")
TaskCreate(subject: "{STORY_ID} › Review-PR › Phase 4 - Approval", activeForm: "Finalizing approval and report")

Close with TaskUpdate(id: phase4TaskId, status: "completed") + FINAL gate (composes with Rule 24 mandatory-artifact scan):

Skill(skill: "x-internal-verify-phase-gates", model: "haiku", args: "--mode final --skill x-review-pr --phase Phase-4-Approval --expected-artifacts ai/epics/epic-XXXX/reviews/review-tech-lead-story-XXXX-YYYY.md,ai/epics/epic-XXXX/reviews/dashboard-story-XXXX-YYYY.md,ai/epics/epic-XXXX/reviews/remediation-story-XXXX-YYYY.md")

Step 7 — Process Result

============================================================
 TECH LEAD REVIEW — [STORY_ID]
============================================================
 Decision:  GO | NO-GO
 Score:     XX/45 (GO >= 38)
 Critical:  N issues
 Medium:    N issues
 Low:       N issues

 Test Execution Results (EPIC-0042):
 Test Suite:    PASS (XXX tests, X failures)
 Coverage:      XX% line, XX% branch
 Smoke Tests:   PASS/FAIL/SKIP (N tests)
------------------------------------------------------------
 Report:      ai/epics/epic-XXXX/reviews/review-tech-lead-story-XXXX-YYYY.md
 Dashboard:   ai/epics/epic-XXXX/reviews/dashboard-story-XXXX-YYYY.md (updated)
 Remediation: ai/epics/epic-XXXX/reviews/remediation-story-XXXX-YYYY.md (updated)
============================================================

Replace "Test Suite", "Coverage", and "Smoke Tests" placeholders with actual values from Step 4 execution (Steps 4.6, 4.7, 4.8). If smoke tests were skipped (testing.smoke_tests=false), show SKIP (0 tests).

Step 8 — Handle NO-GO (Auto-Remediation — EPIC-0042)

When the review results in NO-GO, automatically dispatch remediation instead of waiting for manual input:

  1. Classify NO-GO findings:

    • TEST_FAILURE: unit/integration/smoke test failures detected in Step 4.6-4.8
    • COVERAGE_GAP: coverage below 95% line or 90% branch detected in Step 4.7
    • CODE_QUALITY: rubric score below threshold (non-test issues)
  2. Auto-remediate by classification:

    For TEST_FAILURE: Dispatch a general-purpose agent to fix failing tests:

    Agent(
      subagent_type: "general-purpose",
      description: "Fix failing tests for NO-GO remediation",
      prompt: "Read the failing test output from the review report at ai/epics/epic-XXXX/reviews/review-tech-lead-story-XXXX-YYYY.md. Identify the root cause of each failing test. Fix the IMPLEMENTATION (NOT the test) to make tests pass. Run {{TEST_COMMAND}} to verify the fix. Commit via Skill(skill: 'x-commit-changes', args: '--type fix --subject \"fix failing tests from tech lead review\"')."
    )
    

    For COVERAGE_GAP: Dispatch a general-purpose agent to add missing test coverage:

    Agent(
      subagent_type: "general-purpose",
      description: "Add test coverage for NO-GO remediation",
      prompt: "Read the coverage report. Identify uncovered lines/branches. Write tests for the uncovered code paths following TDD discipline (test first). Run {{TEST_COMMAND}} + {{COVERAGE_COMMAND}} to verify coverage meets 95% line / 90% branch. Commit via Skill(skill: 'x-commit-changes', args: '--type test --subject \"add test coverage for uncovered branches\"')."
    )
    

    For CODE_QUALITY: Apply fixes inline following the remediation tracking file guidance.

  3. Re-run review automatically (max 2 cycles total):

    • After remediation agent completes, re-execute Step 4 (full review)
    • If still NO-GO after 2 cycles: proceed to Step 8.4 (Exhausted-Retry Gate)
  4. Opt-out: Pass --no-auto-remediation flag to force manual mode (skips auto-remediation agents; proceeds directly to Step 8.4 on NO-GO).

Step 8.4 — Exhausted-Retry Gate (Rule 20 Interactive Gate)

Reached when auto-remediation cycles are exhausted (2 retries without convergence) or when --no-auto-remediation is set and the review returns NO-GO.

Non-interactive path (default — --interactive absent or --non-interactive deprecated flag): Skip AskUserQuestion. Print HALT text and return NO-GO:

REVIEW NO-GO: Auto-remediation exhausted without convergence. Remaining issues recorded in report.
Run with --resume-review <pr> --interactive to re-enter the gate interactively.

Exit with NO-GO. No state file written. (--non-interactive DEPRECATED — same as default; WARN emitted per Rule 20 EPIC-0061.)

Interactive path (--interactive present):

Initialize gateAttempts = 0.

Gate loop:

WHILE gateAttempts < 3:
  Present AskUserQuestion:
    question: "Auto-remediation exhausted after 2 retry cycles. The Tech Lead review returned NO-GO. How would you like to proceed?"
    options:
      - { header: "Proceed", label: "Continue (Recommended)", description: "Re-dispatch auto-remediation (+2 loops). If the review converges to GO, the gate closes and the skill exits normally." }
      - { header: "Fix PR", label: "Run x-fix-pr and retry", description: "Invokes x-fix-pr on the current PR; reapresents this menu on return." }
      - { header: "Abort", label: "Cancel the operation", description: "Terminates the skill with REVIEW_REMEDIATION_EXHAUSTED. No further remediation is attempted." }

  On PROCEED (slot 1):
    gateAttempts++
    Re-dispatch auto-remediation agents (same classification logic as Step 8 sub-steps 1-3, with 2 new retry cycles)
    Re-execute Step 4 (full review)
    IF review returns GO:
      Exit gate with GO — skill completes normally
    ELSE:
      IF gateAttempts >= 3:
        Emit REVIEW_FIX_LOOP_EXCEEDED and terminate (see below)
      ELSE:
        Continue loop (reapresent menu)

  On FIX-PR (slot 2):
    gateAttempts++
    Write/update state file at plans/review/<pr>/state.json (opt-in persistence):
      phase: "GATE_FIX_PR"
      lastPhaseCompletedAt: <ISO-8601 UTC now>
      lastGateDecision: "FIX_PR"
      fixAttempts: [... previous ..., { at: <now>, delegateSkill: "x-fix-pr", prNumber: <PR>, outcome: "pending" }]
      schemaVersion: "1.0"
    Invoke x-fix-pr via Rule 13 Pattern 1 INLINE-SKILL:

        Skill(skill: "x-fix-pr", args: "<PR>")

    Update last fixAttempt.outcome to "applied" (or appropriate outcome)
    Update state file: lastGateDecision = "FIX_PR", lastPhaseCompletedAt = <now>
    IF gateAttempts >= 3:
      Emit REVIEW_FIX_LOOP_EXCEEDED and terminate (see below)
    ELSE:
      Continue loop (reapresent menu)

  On ABORT (slot 3):
    Emit: "Review NO-GO final: operator aborted after ${gateAttempts} remediation attempt(s) on PR ${PR}"
    Exit with code REVIEW_REMEDIATION_EXHAUSTED

Guard-rail — REVIEW_FIX_LOOP_EXCEEDED (3 consecutive PROCEED or FIX-PR without convergence):

When gateAttempts >= 3 without converging to GO, terminate the gate automatically:

REVIEW_FIX_LOOP_EXCEEDED: Loop de fix excedeu 3 tentativas no review do PR ${PR};
gate encerrado com ABORT automático.
Retomar via --resume-review ${PR} com --non-interactive ou intervenção manual.

No 4th option is offered. The gate terminates immediately. The menu was presented exactly 3 times (RULE-002 invariant: total option count remains 3 at all previous presentations).

State File (opt-in)

Written only when the operator selects FIX-PR (slot 2) in Step 8.4. Enables resume via --resume-review <pr>. Path: plans/review/<pr-number>/state.json. Schema version "1.0" with fields phase, lastPhaseCompletedAt, lastGateDecision, fixAttempts[], schemaVersion.

See references/full-protocol.md for the full JSON schema, field definitions, and --resume-review resume semantics.

Phase 5 — Emit Frontmatter (MANDATORY — Rule 24 §Camada-1)

<!-- TELEMETRY: phase.start --> Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh start x-review-pr Phase-5-Frontmatter

MANDATORY TOOL CALL (Rule 24 §Camada-1): This phase MUST NOT be inlined, simulated, or omitted. The LLM MUST prepend the populated YAML frontmatter to the tech-lead review artifact. Absent frontmatter is detected by audit-review-frontmatter.sh (Layer 3 CI) and the Stop hook (Layer 2 runtime). There is no fallback when frontmatter emission fails.

TaskCreate( subject: "<STORY_ID> › Phase 5 › Emit tech-lead review frontmatter", activeForm: "Emitting tech-lead review frontmatter", metadata: { "phase": "Phase 5", "parentSkill": "x-review-pr", "storyId": "<STORY_ID>", "epicId": "<EPIC_ID>", "expectedArtifacts": ["<path to techlead-review-story-XXXX-YYYY.md>"] } )

Invoke pre-gate (Rule 25 §Invariants 4):

Skill(skill: "x-internal-verify-phase-gates", model: "haiku", args: "--mode pre --phase 'Phase 5' --skill x-review-pr")

After Phase 4 has produced the prose body of techlead-review-story-<STORY_ID>.md, prepend the YAML frontmatter block conforming to governance/schemas/review-frontmatter-1.0.json. The full YAML template and field notes are in references/full-protocol.md §Phase 5.

Key fields: schema-version: "1.0", generated-by: x-review-pr@<40-hex SHA> (matches schema pattern ^(x-review-codebase|x-review-pr)@[0-9a-f]{40}$), decision (GO|NO-GO|GO-WITH-RESERVATIONS), score, score-max: 55, severity-counts, blocking-findings. The reviewers field is NOT emitted (Tech Lead is sole reviewer). Use checklist: with sub-fields passed: (integer), total: 45, and failed-sections: (YAML list) instead.

After writing the artifact, validate:

Bash command: `$CLAUDE_PROJECT_DIR/.claude/scripts/audit-review-frontmatter.sh --story <STORY_ID>`

If the script returns exit ≠ 0, abort with REVIEW_FRONTMATTER_INVALID. No fallback.

Invoke post-gate (Rule 25 §Invariants 4):

Skill(skill: "x-internal-verify-phase-gates", model: "haiku", args: "--mode post --phase 'Phase 5' --skill x-review-pr --expected-artifacts <path to techlead-review-story-XXXX-YYYY.md>")

TaskUpdate(taskId: <id from TaskCreate above>, status: "completed")

<!-- TELEMETRY: phase.end --> Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh end x-review-pr Phase-5-Frontmatter ok

Error Codes

Code Condition Message
REVIEW_REMEDIATION_EXHAUSTED Operator selected ABORT in Step 8.4 gate "Review NO-GO final: operador abortou após ${N} tentativas de remediation no PR ${PR}"
REVIEW_FIX_LOOP_EXCEEDED 3 consecutive PROCEED or FIX-PR attempts without converging to GO "Loop de fix excedeu 3 tentativas no review do PR ${PR}; gate encerrado com ABORT automático. Retomar via --resume-review ${PR} com --non-interactive ou intervenção manual."
GATE_SCHEMA_INVALID State file at plans/review/<pr>/state.json fails Rule 20 schema validation "State file inválido para gate em {path}: {campo} ausente ou mal-formado"

Output Artifacts

  • ai/epics/epic-XXXX/reviews/review-tech-lead-story-XXXX-YYYY.md — Tech Lead review report
  • ai/epics/epic-XXXX/reviews/dashboard-story-XXXX-YYYY.md — Updated consolidated dashboard
  • ai/epics/epic-XXXX/reviews/remediation-story-XXXX-YYYY.md — Updated remediation tracking
  • plans/review/<pr-number>/state.json — Gate state (opt-in, written only on FIX-PR selection)

Error Handling

Scenario Action
No diff exists between branches Abort with message: "No changes detected between current branch and base. Nothing to review."
Template _TEMPLATE-TECH-LEAD-REVIEW.md missing Log warning, use inline format as fallback (RULE-012 — Graceful template fallback). Skip dashboard and remediation updates.
Specialist review reports not found Proceed with Tech Lead review only; note absence in report
Compilation or build failure Record failure in report, deduct points from Framework & Infra section
Test suite failure (unit/integration) Automatic NO-GO regardless of rubric score; record all failing tests in report
Coverage below threshold (< 95% line or < 90% branch) Automatic NO-GO; record coverage gap as CRITICAL finding
Smoke test failure Automatic NO-GO; record failing smoke tests as CRITICAL finding
NO-GO after 2 retry cycles Route to Step 8.4 Exhausted-Retry Gate
NO-GO with --no-auto-remediation Route directly to Step 8.4 Exhausted-Retry Gate
--non-interactive after retry exhausted Skip gate; emit legacy HALT text; return NO-GO
State file missing on --resume-review Start gate fresh; emit warning
State file schema invalid Emit GATE_SCHEMA_INVALID; start gate fresh

Integration Notes

Skill Relationship Context
x-implement-story called-by Produces the same artifact as Phase 6
x-review-codebase reads Reads specialist review reports for cross-validation
x-review-codebase complements /x-review-codebase = breadth (7 specialists), /x-review-pr = depth (1 Tech Lead)
  • Dashboard (Step 5) is cumulative — created by /x-review-codebase, updated by /x-review-pr (RULE-006)
  • Remediation tracking (Step 6) enables FIXED status tracking after Tech Lead review
  • Templates in .claude/templates/ are copied verbatim by PlanTemplatesAssembler — not rendered by the engine
  • Fallback (RULE-012 — Graceful template fallback): When templates are absent (pre-EPIC-0024 projects), inline format is used and dashboard/remediation updates are skipped

04 同仓库更多 Skills

review-bench
review-bench/edercnj_ia-dev-environment

x-parallel-eval

Detects and classifies file-collision risks between work units (tasks, stories, or epic phases) before parallel execution. Reads ## File Footprint blocks produced by x-task-plan / x-story-plan, applies the parallelism-heuristics knowledge pack (hard / regen / soft categories + hotspot overrides), and emits a collision matrix + serialization recommendation in Markdown (default) or JSON.

★ 0
review-bench
review-bench/edercnj_ia-dev-environment

parallelism-heuristics

Canonical catalog of file-collision heuristics for parallel task, story, and epic execution. Defines the File Footprint block format, the three Conflict Categories (hard / regen / soft), a hotspot list of high-contention paths, and the degrade-with-warning policy. Consumed by x-task-plan, x-story-plan, x-epic-map, x-parallel-eval, and x-dev-*-implement.

★ 0
review-bench
review-bench/edercnj_ia-dev-environment

x-watch-pr-ci

Polls a PR's CI checks and Copilot review status, blocking until checks complete or timeout. Returns one of 8 stable exit codes (SUCCESS=0, CI_PENDING_PROCEED=10, CI_FAILED=20, TIMEOUT=30, PR_ALREADY_MERGED=40, NO_CI_CONFIGURED=50, PR_CLOSED=60, PR_NOT_FOUND=70). Writes a versioned state-file for session resume.

★ 0
review-bench
review-bench/edercnj_ia-dev-environment

x-validate-docs

Documentation freshness gate: validates 6 dimensions (readme, api-specs, grpc-proto, adr, skill-docs, system-architecture) against code changes in a PR. Stack-aware — only validates targets declared/auto-detected from ProjectConfig.documentation.targets. Returns exit non-zero on staleness; produces structured report.

★ 0
review-bench
review-bench/edercnj_ia-dev-environment

x-update-system-architecture

Incrementally updates docs/architecture/system.md after an epic completes. Appends new entries to the Decision Log (§11) using x-internal-write-report --append (dedup by ## ID: marker) and surgically inserts component/integration changes into sections 1-10 via Edit. Idempotent: re-running with the same epic produces a byte-identical system.md.

★ 0
review-bench
review-bench/edercnj_ia-dev-environment

x-update-architecture

Incrementally updates the service architecture document with changes from architecture plans. Adds new components, integrations, flows, and ADR references without rewriting existing content. Use after implementation to keep architecture documentation current.

★ 0