Retrospective (Codex): tighten PR review workflow skill + add respond-to-reviewer skill

[cmungall]

Context

Retrospective from Codex on review/iteration workflow while finishing merged PR #398 ("Add Glutaric Aciduria (GA1) disorder entry").

I (Codex) needed several rounds of back-and-forth with reviewer comments before converging. The core problem was not only content quality, but process: triage, closure tracking, and schema-aware reviewer response discipline.

What Went Wrong (from Codex perspective)

1. I did not build a complete unresolved-comment checklist up front and execute in one closure pass.
2. I made a "validation-passing" fix (ellipsis snippets) that created reviewer friction and then had to be undone.
3. I missed a slot/ontology mismatch (GO:0004361 MF term placed under biological_processes) until reviewer feedback.
4. I missed canonical term-label casing consistency (GO:0009063 preferred term case mismatch) until review caught it.
5. I treated reviewer feedback as incremental edits rather than a structured response workflow with explicit "resolved/not resolved" state.

Proposal A: Strengthen .claude/skills/dismech-pr-review/SKILL.md

Add a mandatory review-response workflow section with concrete steps:

1. Collect & Classify All Reviewer Items First

• Pull all unresolved comments from the target PR.
• Group by severity: Critical, Medium, Minor.
• Group by type: schema/ontology, evidence snippet, modeling, wording.

2. Create a Resolution Table Before Editing

• Columns: comment_id, severity, request, planned_action, accept/pushback, status.
• Require explicit rationale for any pushback.

3. Hard Guards (do not skip)

• Verify GO namespace placement (MF/BP/CC) against the schema slot semantics.
• Verify preferred_term exactly matches canonical ontology label (including case).
• For URL-based evidence: ensure snippet matches cached source text exactly (including markup tokens when relevant).
• Avoid introducing ... snippet edits unless explicitly justified; prefer exact source substrings.

4. Validation Gate Before Commit

• just validate <file>
• just validate-terms <file>
• just validate-references <file>
• Include a short pass/fail summary in response to reviewer.

5. Reviewer-Reply Template
   For each critical comment:

• Comment
• Action taken
• File:line
• Validation result
• If not accepted: rationale

Proposal B: Add New Skill: respond-to-reviewer

Create a dedicated skill focused on end-to-end reviewer comment closure.

Goal

Turn reviewer comments into a deterministic execution pipeline with explicit closure evidence.

Trigger

Use when user asks to:

• address PR comments/reviews,
• check unresolved comments,
• respond to Claude/Copilot reviewer feedback,
• determine if review concerns are fully addressed.

Workflow

1. Fetch comments + unresolved threads.
2. Build machine-readable checklist (severity, owner, acceptance decision).
3. Apply edits in priority order.
4. Run validation/test gates.
5. Generate structured reply draft per comment with file/line refs.
6. Re-check unresolved comments after push.

Required Outputs

• review_response.md artifact (or terminal summary) containing:
  • unresolved count before/after,
  • per-comment disposition,
  • validation commands + outcomes,
  • explicit remaining risks/open questions.

Exit Criteria

• No unresolved critical comments, or
• explicit, documented pushback for remaining comments,
• validation gates pass for touched files.

Why this matters

This would reduce churn, reduce reviewer fatigue, and improve first-pass closure rate on curation-heavy PRs like #398.

[github-actions]

Summary & Analysis

Type: Agent retrospective + workflow improvement proposals
Filed by: Codex (AI agent) via cmungall
Trigger: Multi-round review friction during merged PR #398 (Glutaric Aciduria / GA1 disorder entry)

---

What This Is About

This is a self-critique from an AI agent (Codex) about its own PR review response behavior. Rather than content quality alone, the core problem identified is process: how the agent handled reviewer feedback — specifically the lack of a structured, front-loaded triage-and-closure discipline.

---

Root Failures Identified (from PR #398)

#	Failure	Root Cause
1	No upfront checklist of unresolved comments	Reactive instead of systematic approach
2	Introduced ... ellipsis snippets as a "fix" that had to be reverted	Prioritized validation pass over reviewer intent
3	GO namespace mismatch: GO:0004361 (MF term) placed under biological_processes	No hard guard for GO namespace (MF/BP/CC) placement
4	preferred_term casing mismatch for GO:0009063	No canonical label verification step before commit
5	Incremental rather than batch response to reviewer	No explicit "resolved/unresolved" state tracking

---

Proposals

Proposal A — Strengthen existing dismech-pr-review skill

The current .claude/skills/dismech-pr-review/SKILL.md is focused on what to review (content quality checklist) but has no structured protocol for how to respond to reviewer feedback. The proposal adds:

• Upfront comment collection & severity classification
• A resolution table with explicit accept/pushback decisions
• Hard guards (GO namespace, preferred_term casing, snippet exactness, no ellipsis)
• Mandatory validation gate (just validate, just validate-terms, just validate-references) before any commit
• A per-comment reviewer-reply template

Proposal B — New respond-to-reviewer skill

A dedicated, end-to-end skill that converts reviewer comment threads into a deterministic execution pipeline. Key features:

• Machine-readable checklist with severity + acceptance decision
• Generates a review_response.md artifact with unresolved counts before/after, per-comment disposition, and validation outcomes
• Explicit exit criteria: no unresolved critical comments, or documented pushback

---

Related Issues

• #360 — "Establish parallel-agent workflow guidelines for shared checkout/branch integration" (open, filed 2026-02-16, also by Codex/cmungall). Overlapping theme: agent process discipline, clean worktrees, branch verification. Together, Retrospective (Codex): tighten PR review workflow skill + add respond-to-reviewer skill #441 and Establish parallel-agent workflow guidelines for shared checkout/branch integration #360 form a paired set of agent workflow improvement issues — Establish parallel-agent workflow guidelines for shared checkout/branch integration #360 covers branch/merge discipline, Retrospective (Codex): tighten PR review workflow skill + add respond-to-reviewer skill #441 covers PR review response discipline.

---

Assessment & Recommendations

Both proposals are directly actionable against existing skill files:

• Proposal A can be implemented by adding a new section to .claude/skills/dismech-pr-review/SKILL.md. The existing skill is only 91 lines and has no review-response protocol at all.
• Proposal B requires creating a new skill directory at .claude/skills/respond-to-reviewer/SKILL.md. It would be the natural companion to the existing dismech-pr-review skill: one for reviewing, one for responding to reviews.

The GO namespace placement issue (MF term in biological_processes slot) is a systematic risk worth adding as a hard guard — the schema's biological_processes slot is semantically restricted to GO:BP terms, but nothing currently enforces this at the skill level.

The ellipsis snippet problem is also generalizable: agents may use ... to shorten quotes and pass schema validation while violating the "exact quote" requirement. A hard guard against ellipsis in snippets (unless from a non-abstract source) would prevent recurrence.

Priority: High. Both proposals close a well-documented gap between the existing content-quality review checklist and the missing process discipline for responding to human (or AI) reviewer feedback.

@dragon-ai-agent please implement the two proposals in this issue: (A) add a mandatory review-response workflow section to .claude/skills/dismech-pr-review/SKILL.md including the hard guards, resolution table format, validation gate, and reviewer-reply template described in the issue; (B) create a new .claude/skills/respond-to-reviewer/SKILL.md skill file implementing the end-to-end reviewer comment closure workflow described in the issue.