Paths: File paths (shared/, references/, ../ln-*) are relative to skills repo root. If not found at CWD, locate this SKILL.md directory and go up one level for repo root.

ln-813-optimization-plan-validator

Type: L3 Worker Category: 8XX Optimization

Validates optimization plan (performance_map + hypotheses + context) via parallel agent review before committing to code changes. Catches feasibility issues, missing hypotheses, and incorrect conflict mappings before the strike.

Overview

Aspect	Details
Input	`.optimization/{slug}/context.md` (performance_map, hypotheses, suspicion_stack)
Output	Verdict (GO / GO_WITH_CONCERNS / NO_GO), corrected context.md, agent feedback summary
Pattern	Parallel agent review (Codex + Gemini) + own feasibility check → merge → verdict

Workflow

Phases: Load Context + Health Check → Materialize for Agents → Launch Agents → Feasibility Check → Merge + Debate → Verdict

Phase 0: Load Context + Health Check

MANDATORY READ: Load shared/references/agent_review_workflow.md MANDATORY READ: Load shared/references/agent_delegation_pattern.md

Slug Resolution

If invoked via Agent with contextStore containing slug — use directly.
If invoked standalone — ask user for .optimization/ target directory or scan for single slug.

Step 1: Load Context

Read .optimization/{slug}/context.md from project root. Verify required sections present:

Section	Required	Verify
Performance Map	Yes	`performance_map.baseline` has measurements
Hypotheses	Yes	At least 1 hypothesis with `files_to_modify`
Suspicion Stack	Yes	At least 1 confirmed suspicion
Test Command	Yes	Non-empty `test_command`

If missing → Block: "context.md incomplete — run profiler and researcher first."

Step 2: Agent Health Check

python shared/agents/agent_runner.py --health-check

0 agents available → agents_launched = SKIPPED, proceed with own feasibility check only
Agents available → continue to Phase 1

Phase 1: Materialize Context for Agents

Prepare context for external agents (they cannot read .optimization/ directly):

Ensure .agent-review/ directory exists (with .gitignore containing *)
Copy .optimization/{slug}/context.md → .agent-review/context/{id}_optimization_plan.md
Build per-agent prompts per agent_review_workflow.md Step: Build Prompt (steps 1-9). Use review_base.md + modes/plan_review.md

Optimization-Specific Focus Areas

Replace default {focus_areas} in prompt with:

MANDATORY READ: Load optimization_review_focus.md

Save per-agent prompts to .agent-review/{agent}/{id}_optimization_review_prompt.md

Phase 2: Launch Agents (Background)

Launch BOTH agents as background Bash tasks:

python shared/agents/agent_runner.py \
  --agent codex-review \
  --prompt-file .agent-review/codex/{id}_optimization_review_prompt.md \
  --output-file .agent-review/codex/{id}_optimization_review.md \
  --cwd {project_root}

python shared/agents/agent_runner.py \
  --agent gemini-review \
  --prompt-file .agent-review/gemini/{id}_optimization_review_prompt.md \
  --output-file .agent-review/gemini/{id}_optimization_review.md \
  --cwd {project_root}

Both run in background (run_in_background=true). Proceed to Phase 3 while agents work.

Phase 3: Own Feasibility Check (while agents run)

Perform independent validation of the optimization plan:

Check	How	Fail Action
Files exist	For each hypothesis: verify every file in `files_to_modify` exists	Flag hypothesis as INVALID
No file conflicts	Check uncontested hypotheses don't modify same file lines	Flag overlap as CONCERN
Suspicion coverage	Cross-reference `suspicion_stack` (confirmed) with hypotheses	Flag uncovered suspicions as MISSING_HYPOTHESIS
Evidence backing	Each hypothesis should trace to a profiler finding or research source	Flag unsupported as WEAK_EVIDENCE
Conflicts correct	Verify `conflicts_with` mappings make sense (H1 really makes H3 unnecessary?)	Flag incorrect as BAD_CONFLICT
Fix Hierarchy	Verify hypotheses ordered Configuration→...→Removal. Flag if top hypothesis is level 4-5	CONCERN: "config-level fix may be available"
Removal guard	Any "remove feature" hypothesis MUST have paired "optimize feature" alternative	CONCERN: "removal without optimization alternative"
Assumption verification	Each hypothesis's premises — verified by profiler data or just assumed?	Flag: "assumption not verified: {premise}"
Depth check	Did profiler go inside all accessible slow services? Check performance_map for surface-level entries	CONCERN: "service X profiled at surface level only"

Output

feasibility_result:
  valid_hypotheses: [H1, H2, H4]
  invalid_hypotheses: [{id: H3, reason: "file not found: src/cache.py"}]
  concerns: [{type: "file_overlap", detail: "H1 and H2 both modify src/api.py"}]
  missing: [{suspicion: "N+1 in loop at handler.py:45", note: "no hypothesis addresses this"}]

Phase 4: Merge Agent Feedback + Debate

Wait for agent results, then merge per shared/references/agent_review_workflow.md:

Parse agent suggestions from both result files
Merge with own feasibility findings (Phase 3)
For EACH suggestion: dedup → evaluate → AGREE or DISAGREE (debate per shared workflow)
Apply accepted corrections directly to .optimization/{slug}/context.md:
- Remove invalid hypotheses
- Add warnings to concerns
- Adjust conflicts_with if agents found errors
- Add missing hypotheses if agents identified gaps

Save review summary → .agent-review/review_history.md

Display: "Agent Review: codex ({accepted}/{total}), gemini ({accepted}/{total}), {N} corrections applied"

Phase 5: Verdict

Verdict	Condition
GO	All hypotheses valid, no critical issues, agents agree plan is feasible
GO_WITH_CONCERNS	Minor issues found and documented as warnings in context.md. Safe to proceed
NO_GO	Critical feasibility issue (files missing, fundamental approach flaw, both agents reject)

Output

validation_result:
  verdict: "GO" | "GO_WITH_CONCERNS" | "NO_GO"
  corrections_applied: <number>
  hypotheses_removed: [<ids>]
  hypotheses_added: [<ids>]
  concerns: [<list>]
  agent_summary: "codex: PLAN_ACCEPTABLE, gemini: SUGGESTIONS (2 accepted)"

Return verdict to coordinator. On NO_GO: coordinator presents issues to user.

Error Handling

Error	Recovery
Context file missing	Block: "run profiler and researcher first"
Both agents unavailable	Proceed with own feasibility check only (reduced confidence)
Agent timeout	Use results from available agent + own check
Context file malformed	Block: "context.md missing required sections"

References

shared/references/agent_review_workflow.md — merge + debate protocol
shared/references/agent_delegation_pattern.md — agent invocation pattern
shared/agents/prompt_templates/modes/plan_review.md — plan review template
optimization_review_focus.md — optimization-specific focus areas

Definition of Done

Context file loaded and validated (all required sections present)
Agent health check performed
Context materialized to .agent-review/ for agents
Both agents launched (or SKIPPED if unavailable)
Own feasibility check completed (files exist, no conflicts, evidence backing)
Agent results merged and debated
Corrections applied to context.md
Verdict issued (GO / GO_WITH_CONCERNS / NO_GO)
Review summary saved to .agent-review/review_history.md

Version: 1.0.0 Last Updated: 2026-03-15