Ln 316 Review Refinement Worker

> Paths: File paths (references/, ../ln-*) are relative to this skill directory.

Type: L3 Worker Category: 3XX Planning

Review Refinement Worker

Mandatory Read

MANDATORY READ: Load references/evaluation_worker_runtime_contract.md, references/evaluation_summary_contract.md, references/refinement_trace_contract.md, references/cleanup_evidence_contract.md MANDATORY READ: Load references/agents/prompt_templates/iterative_refinement.md, references/agents/prompt_templates/refinement_perspectives.md MANDATORY READ: Load references/monitor_integration_pattern.md, references/agent_review_workflow.md (Step: Iterative Refinement)

Purpose

• run 2-stage refinement after merge using the non-host advisor agent via agent_runner.mjs
• Stage 1: 3 parallel independent advisor sessions (dryrunexecutor, newdevtester, adversarial_reviewer)
• Stage 2: 1 sequential advisor session (final_sweep) after merging Stage 1 results
• record refinement trace and cleanup evidence for every advisor session

Critical: refinement launches the advisor externally. Do NOT use host-native sub-agents for this phase.

Runtime

Runtime family:

• evaluation-worker-runtime

Required manifest fields:

• identifier
• phase_order
• summary_kind=review-refinement
• operation=refinement

Recommended phase_order:

1. PHASE_0_CONFIG
2. PHASE_1_STAGE1_PARALLEL
3. PHASE_2_STAGE2_FINAL_SWEEP
4. PHASE_3_WRITE_SUMMARY
5. PHASE_4_SELF_CHECK

Refinement State Machine

Critical: Independent Sessions

Each perspective MUST be a separate node agent_runner.mjs --agent {advisor_agent} invocation. Do NOT combine multiple perspectives into a single advisor prompt or session. Each iter{N}/ subdirectory = independent advisor process with its own PID.

Perspective Classification

| Stage | Perspective | Execution | Purpose | |-------|------------|-----------|---------| | 1 | dry_run_executor | parallel | Catch unexecutable steps, sequencing errors | | 1 | new_dev_tester | parallel | Catch implicit knowledge gaps, undefined terms | | 1 | adversarial_reviewer | parallel | Catch guaranteed failures, silent corruption | | 2 | final_sweep | after merge | Catch regressions and drift from Stage 1 fixes |

All 4 perspectives are MANDATORY. generic_quality is not included — it is covered by the Phase 2 advisor review (review_base.md + mode template).

Stage 1: Parallel Specialized Reviews

1. Build artifact: Read current state of reviewed artifact (Story+Tasks / plan file / context docs).
2. For EACH of 3 perspectives, in parallel:

a. Load perspective from refinement_perspectives.md matching the perspective name. b. Build prompt: fill iterative_refinement.md placeholders ({artifact_type}, {artifact_content}, {project_context}, {review_perspective}, {iteration_number}, {max_iterations}, {previous_findings_summary}). c. Save prompt to .hex-skills/agent-review/refinement/{identifier}/iter{N}/prompt.md

• iter1/ = dryrunexecutor
• iter2/ = newdevtester
• iter3/ = adversarial_reviewer

d. Launch independent advisor process: `` node references/agents/agent_runner.mjs --agent {advisor_agent} \ --prompt-file .hex-skills/agent-review/refinement/{identifier}/iter{N}/prompt.md \ --output-file .hex-skills/agent-review/refinement/{identifier}/iter{N}/result.md \ --cwd {project_dir} ``

1. Wait for ALL 3 via runtime sync-agent; Claude hosts may use Monitor for observability (see Waiting section below).
2. Parse results from each completed session: extract JSON from ## Structured Data section.
3. Merge findings: deduplicate by (area, issue), keep higher confidence.
4. Classify: HIGH (impact_percent >= 20%), MEDIUM (10-19%), LOW (3 min → run Liveness Protocol (see agent_review_workflow.md).

Do NOT use sleep or manual stat-polling as the primary wait mechanism.

Process Cleanup

After each advisor call (both stages):

1. Extract pid from runner stdout or metadata.
2. Run node references/agents/agent_runner.mjs --verify-dead {pid}.
3. Record cleanup evidence per cleanup_evidence_contract.md.
4. CLI advisor processes can accumulate on Windows if not killed.

Exit States

| State | Meaning | |-------|---------| | COMPLETED | Both stages done, all results merged | | PARTIAL_ERROR | Stage 1 had failures but Stage 2 completed | | ERROR | All Stage 1 advisor sessions failed (Stage 2 skipped) | | SKIPPED | No advisor available in health check |

Summary

Emit summary_kind=review-refinement.

Payload must include:

• worker=ln-316
• status
• operation=refinement
• warnings

Prefer these fields:

• stages_completed (int: 1 or 2)
• exit_reason (enum: COMPLETED, PARTIAL_ERROR, ERROR, SKIPPED)
• applied (int: total suggestions applied across all stages)
• architecture_gate_rejections (count)
• stage1_perspectives (list of completed perspective names)
• stage1_failed (list of failed perspective names)
• metadata.refinement_trace

Definition of Done

• [ ] Stage 1: all 3 advisor sessions launched in parallel
• [ ] Stage 2: final_sweep launched after Stage 1 merge
• [ ] All advisors launched via agent_runner.mjs (not host-native sub-agents)
• [ ] Runtime sync-agent used for waiting; Claude Monitor is optional observability
• [ ] Refinement trace recorded per refinement_trace_contract.md
• [ ] Cleanup evidence recorded for all launched processes
• [ ] review-refinement summary written
• [ ] Self-check passed

Version: 2.0.0 Last Updated: 2026-04-13

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: levnikolaevich
• Source: levnikolaevich/claude-code-skills
• License: MIT
• Homepage: https://levnikolaevich.github.io/claude-code-skills/

Install and usage instructions live in the source repository linked above.