AgentSkillsCN

diagnose-state

读取 state.json 文件，诊断 PR 状态、错误信息、卡顿条目以及异常情况。

SKILL.md
--- frontmatter
name: diagnose-state
description: Read state.json and diagnose PR statuses, errors, stuck entries, and anomalies.
user-invocable: true

You are a diagnostics tool for the claude-code-reviewer service. Your job is to read and analyze the PR state file.

Input

The user may provide an optional argument: a PR identifier like owner/repo#N or just N (PR number).

Data Source

Read the state file at data/state.json. It follows the StateFileV2 format defined in src/types.ts:

  • •Top-level: { "version": 2, "prs": { "owner/repo#N": PRState, ... } }
  • •Each PRState has: identity (owner, repo, number), status, PR metadata, review history, skip tracking, error tracking, comment/review tracking, timestamps, debounce

If the file doesn't exist or is empty, report that and stop.

Modes

Summary Mode (no argument)

Present a dashboard of all tracked PRs:

  1. •

    Status Distribution — count PRs by status (pending_review, reviewing, reviewed, changes_pushed, error, skipped, closed, merged). Show as a table.

  2. •

    Error Entries — for each PR with status: "error", show:

    • •PR identifier (owner/repo#N)
    • •lastError.phase, lastError.message, lastError.sha (7 chars), lastError.occurredAt
    • •consecutiveErrors count
    • •Whether it's stuck (consecutiveErrors >= maxRetries from config.yaml, default: 3)
  3. •

    Skipped PRs — for each PR with status: "skipped", show:

    • •PR identifier and title
    • •skipReason (draft / wip_title / diff_too_large)
    • •skipDiffLines if reason is diff_too_large
  4. •

    Anomaly Detection — flag these conditions:

    • •Any PR in reviewing status (indicates a crash — store.ts resets these on startup, so this only appears in a raw file read before restart or during an active review)
    • •Any PR with consecutiveErrors >= maxRetries (stuck at max retries — read review.maxRetries from config.yaml, default: 3)
    • •Any reviewed PR with no commentId AND no reviewId (review posted but no tracking ID)
    • •Any reviewed PR where lastReviewedSha !== headSha (stale review — new push since last review)
    • •Any reviewed PR where comment-verifier.ts may have requeued it (reviewId/commentId is null but status is still reviewed)
  5. •

    Summary Line — total PRs, active (non-terminal), terminal (closed + merged)

Single-PR Mode (with argument)

Look up the PR by key. If only a number is given, search all entries for a matching number field. If not found, report that.

Display all fields of the PRState grouped:

  1. •Identity — owner, repo, number, key
  2. •Status — current status, with interpretation
  3. •PR Metadata — title, isDraft, headSha (abbreviated to 7 chars), baseBranch
  4. •Review History — show lastReviewedSha (7 chars), lastReviewedAt, then format each ReviewRecord as a table row:
    • •sha (7 chars) | reviewedAt | verdict | posted | findings count (by severity: issue/suggestion/nitpick/question/praise) | commentId/reviewId
    • •Show total findings breakdown across all reviews
  5. •Skip Tracking — skipReason, skipDiffLines, skippedAtSha
  6. •Error Tracking — lastError (phase, message, sha, occurredAt), consecutiveErrors
  7. •Comment/Review Tracking — commentId, commentVerifiedAt, reviewId, reviewVerifiedAt
  8. •Timestamps — firstSeenAt, updatedAt, closedAt, lastPushAt, lastReviewedAt
  9. •Anomalies — same checks as summary mode, applied to this PR

Output Format

Use markdown tables and clear section headers. Keep it scannable. Use ⚠ prefix for anomalies and errors.