ln-316-review-refinement-worker

What this skill does

> **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 (dry_run_executor, new_dev_tester, 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/ = dry_run_executor
      - iter2/ = new_dev_tester
      - 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}
      ```
3. **Wait for ALL 3** via runtime `sync-agent`; Claude hosts may use `Monitor` for observability (see Waiting section below).
4. **Parse results** from each completed session: extract JSON from `## Structured Data` section.
5. **Merge findings:** deduplicate by (area, issue), keep higher confidence.
6. **Classify:** HIGH (impact_percent >= 20%), MEDIUM (10-19%), LOW (< 10%).
7. **Architecture Gate** on each accepted fix: "Does this implement the correct architecture directly, without backward compatibility shims?"
8. **Apply accepted fixes.**
9. **Kill all 3 processes:** `node agent_runner.mjs --verify-dead {pid}` per session. MANDATORY on Windows.
10. **Record cleanup evidence** per `cleanup_evidence_contract.md` for each session.
11. **Build `{previous_findings_summary}`** for Stage 2.

If ALL 3 advisor sessions fail → EXIT(ERROR), skip Stage 2.
If some fail → continue with available results, record partial errors.

### Stage 2: Final Sweep

1. **Build artifact:** Read post-fix state after Stage 1.
2. **Load `final_sweep`** perspective from `refinement_perspectives.md`.
3. **Build prompt** with `{previous_findings_summary}` from Stage 1.
4. **Save prompt** to `.hex-skills/agent-review/refinement/{identifier}/iter4/prompt.md`.
5. **Launch advisor** (single independent session).
6. **Wait** via runtime `sync-agent`; Claude hosts may use `Monitor` for observability.
7. **Parse result,** apply any accepted fixes (Architecture Gate on each).
8. **Kill process,** record cleanup evidence.

### Waiting for Advisor Results (MANDATORY)

Use the active runtime `sync-agent` command before parsing or merge gates. `Monitor` is optional Claude Code observability only.

For EACH launched advisor process:

When running under Claude Code, optional observability:
```
Monitor(command="tail -f {agent_log} | grep --line-buffered -E 'Phase|ERROR|DONE'", timeout_ms=120000, description="advisor refinement {perspective_name}")
```

After each sync/monitor cycle:
- Check result file for `<!-- END_AGENT_REVIEW_RESULT -->` marker.
- Marker present → parse result, proceed.
- Marker absent, log growing → continue runtime sync or optional monitor cycle.
- Marker absent, log stale >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