# Remediation Handoff Atomic Planner > Remediation handoff chain from orchestrator through atomic-planner, atomic-executor, and feature-review. Use when an audit cycle requires a delegated remediation plan, preflight clearance, task-by-task execution, and reaudit. - Skill: `drmoisan/remediation-handoff-atomic-planner` (Agent Skill) - Install (CLI): `npx skillmds@latest add drmoisan/remediation-handoff-atomic-planner` - Raw SKILL.md: https://api.skillmd.com/api/skills/drmoisan/remediation-handoff-atomic-planner/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Security, Coding & Dev Tools - Author: drmoisan (https://skillmd.com/u/drmoisan) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/drmoisan/remediation-handoff-atomic-planner --- # Remediation Handoff to atomic-planner Strict handoff chain for orchestrator-initiated remediation cycles. The chain enforces that an `atomic-planner`-authored plan is preflighted by `atomic-executor`, revised through a preflight sub-loop if needed, executed by `atomic-executor` task-by-task, and reaudited by `feature-review`. Workers are never invoked directly by the orchestrator. ## When to Use This Skill Use this skill when: - Audit findings require remediation (FAIL or material PARTIAL findings). - Toolchain checks fail. - Acceptance criteria are unmet. - A required CI check fails after the pull request is open. - Any new finding surfaces during execution of an active cycle (in which case begin a new cycle, do not extend the active one). ## Full Handoff Chain ``` orchestrator -> writes remediation//remediation-inputs.md -> delegates to atomic-planner -> atomic-planner authors remediation//remediation-plan.md (plan shape per .claude/skills/atomic-plan-contract/SKILL.md) -> orchestrator hands plan to atomic-executor for preflight -> atomic-executor returns one of: PREFLIGHT: ALL CLEAR -> proceed to execution PREFLIGHT: REVISIONS REQUIRED -> route back to atomic-planner with a precise plan delta; planner revises in place and orchestrator re-runs preflight (sub-loop until clear) -> atomic-executor executes the cleared plan task-by-task (workers are invoked by atomic-executor only) -> orchestrator delegates to feature-review -> feature-review writes audit//code-review.md, audit//feature-audit.md, and audit//policy-audit.md -> orchestrator evaluates exit condition: blocking_count == 0 -> mark exit_condition_met = true, end loop blocking_count > 0 -> begin cycle N+1 with new remediation//remediation-inputs.md ``` Every audit (including the initial, non-remediation-triggered `feature-review` pass that first discovers findings) is written under an `audit//` folder. Every remediation cycle's entry artifacts are written under a `remediation//` folder. This folder-per-cycle layout is the canonical pattern for multi-cycle remediation: it keeps each cycle's inputs, plan, and reaudit artifacts visually and structurally grouped, rather than relying on filename timestamp suffixes alone to disambiguate cycles sharing a feature folder. The orchestrator must not call typed-engineer workers directly during any phase of the cycle. The orchestrator must not act on a preflight delta itself; revisions are routed to `atomic-planner`. ## Trigger Conditions Trigger remediation when any of these are true: - Audit artifacts contain FAIL or meaningful PARTIAL findings. - Toolchain checks fail (format, lint, type-check, test, contract, or integration stages). - Acceptance criteria are not met. - A required CI check fails after the PR is open (workflow-file changes specifically must enter the loop and trigger the `modified-workflow-needs-green-run` rule defined in `.claude/skills/feature-review-workflow/SKILL.md`). ## Required Remediation Inputs The orchestrator authors `remediation//remediation-inputs.md` with: - Enumerated fix list with file paths, expected behavior, and verification commands. - A "do not do" list (no scope creep, no policy weakening, no silent skips). - A pointer to the audit artifacts that produced the findings. ## Required Artifacts Each remediation cycle produces exactly five artifacts under the active feature folder, grouped into one `remediation//` folder and one `audit//` folder: 1. `docs/features/active//remediation//remediation-inputs.md` — orchestrator authors at cycle entry. 2. `docs/features/active//remediation//remediation-plan.md` — `atomic-planner` authors at cycle entry. 3. `docs/features/active//audit//code-review.md` — `feature-review` authors at cycle exit. 4. `docs/features/active//audit//feature-audit.md` — `feature-review` authors at cycle exit. 5. `docs/features/active//audit//policy-audit.md` — `feature-review` authors at cycle exit. The initial, non-remediation-triggered `feature-review` pass (the audit that first discovers findings and opens cycle 1) also writes its three artifacts under `docs/features/active//audit//`, for the same reason: one timestamped folder per audit event, regardless of whether that audit opens, closes, or does not trigger a remediation cycle. Timestamp rule: - `` is the ISO-8601 timestamp at cycle entry, in the `yyyy-MM-ddTHH-mm` format defined in `.claude/skills/evidence-and-timestamp-conventions/SKILL.md`. It names both the `remediation//` folder and, within it, `remediation-inputs.md` and `remediation-plan.md`. - `` is the ISO-8601 timestamp at cycle exit (when `feature-review` runs), in the same `yyyy-MM-ddTHH-mm` format. It names the `audit//` folder and, within it, all three reaudit artifacts: `code-review.md`, `feature-audit.md`, and `policy-audit.md`. A cycle with fewer than five artifacts is malformed. A cycle that uses the same timestamp value for both its `remediation//` and `audit//` folders is malformed unless entry and exit genuinely ran within the same minute — the two folders remain distinct either way, since one is named `remediation/` and the other `audit/`. ### Cycle-Document Sweep Scope A comprehensive or final sweep in a remediation cycle covers that cycle's own plan and audit documents — `remediation-plan.md`, `code-review.md`, `feature-audit.md`, and `policy-audit.md` — in addition to production and test code. The failure mechanism a code-only sweep leaves open is self-referential rule violation: a policy-compliance fix whose own descriptive text violates the policy it enforces is written into one of those four documents rather than into code, so a sweep scoped to code only reports no finding and the violation ships with the cycle. ## Plan Shape `remediation//remediation-plan.md` MUST conform to `.claude/skills/atomic-plan-contract/SKILL.md`. In particular: - Phase headings: `### Phase N — `. - Tasks: `- [ ] [P#-T#]` with sequential per-phase IDs. - Phase 0 captures policy reads and baseline toolchain results per `policy-compliance-order` and `evidence-and-timestamp-conventions`. - Final phase runs the full toolchain QA loop in the order specified by `atomic-plan-contract` and records numeric coverage values where the repository policy requires coverage. - Evidence paths resolve to `<FEATURE>/evidence/<kind>/` per the non-overridable evidence path clause. The plan must pass the `mcp__drm-copilot__validate_orchestration_artifacts` MCP tool with `artifact_type: "plan"` and `artifact_path: <plan-path>` before `atomic-executor` runs preflight against it. ## Preflight Sub-Loop After the plan is authored, `atomic-executor` runs preflight under the directive `DIRECTIVE: PREFLIGHT VALIDATION ONLY`. The exact signal returned is either: - `PREFLIGHT: ALL CLEAR` — the plan proceeds to execution. - `PREFLIGHT: REVISIONS REQUIRED` — `atomic-executor` returns a precise plan delta. The orchestrator routes the delta to `atomic-planner` for revision. `atomic-planner` updates the same plan file in place (per the plan-path continuity contract in `atomic-plan-contract`). The orchestrator then re-runs preflight. The sub-loop repeats until `PREFLIGHT: ALL CLEAR` is returned. The orchestrator records the preflight outcome in `remediation_loop.cycles[current_cycle].preflight` with `iterations` (counter) and `final_status` (`clear|changes_requested|pending`). For a well-scoped item where `preflight.iterations > 1`, record a process-defect investigation that identifies the incomplete planner internal-review dimension. Treat excess rounds as a process signal, not routine iteration. The exhaustive-pass, defect-enumeration, and delta-self-check rules that govern how `atomic-executor` conducts preflight are defined in the `## Preflight Validation (Planner ↔ Executor)` section of `.claude/skills/atomic-plan-contract/SKILL.md` and are not restated here. Alongside `iterations` and `final_status`, the orchestrator also records in `remediation_loop.cycles[current_cycle].preflight` the convergence line `atomic-executor` returned on that round, which is one of `CONVERGENCE: NO FURTHER ROUNDS EXPECTED` or `CONVERGENCE: FURTHER ROUNDS LIKELY`. This convergence field extends the field set already recorded at `remediation_loop.cycles[current_cycle].preflight` rather than replacing it: `iterations` and `final_status` continue to be recorded exactly as stated above, and the convergence field is written in addition to them. Iteration ceiling. When a cycle's `iterations` would exceed 2, the orchestrator records `final_status: "blocked_preflight_iteration_limit"`, halts the preflight sub-loop, and escalates to the caller, rather than continuing the sub-loop indefinitely. `blocked_preflight_iteration_limit` is a fourth `final_status` value extending the `clear|changes_requested|pending` enumeration stated above. This ceiling bounds the repeat-until-clear behavior stated above it: the sub-loop still repeats until `PREFLIGHT: ALL CLEAR` is returned, and the ceiling supplies the terminating condition for the case where that signal is not reached within two iterations. ## Execution and Reaudit When preflight is clear, `atomic-executor` executes the plan task-by-task. The executor invokes workers (`python-typed-engineer`, `typescript-engineer`, `csharp-typed-engineer`, `powershell-typed-engineer`) internally as needed. The orchestrator does not call workers. When execution is complete, the orchestrator delegates to `feature-review`. `feature-review` produces the three reaudit artifacts under `docs/features/active/<slug>/audit/<exit-ts>/` using the exit timestamp. ## Exit Gate The orchestrator reads the latest cycle's three reaudit artifacts and computes `blocking_count` as the total number of FAIL findings plus material PARTIAL findings flagged as blocking. Only when `blocking_count == 0` does the orchestrator set `exit_condition_met = true` on the current cycle and mark the remediation loop complete. Otherwise, the orchestrator opens cycle N+1 with a new `remediation/<new-ts>/remediation-inputs.md` and runs the full chain again. ## Context Package (When Required) If the calling agent requires a context package, inline the relevant audit artifacts, PR context artifacts, and any active plan files in the delegated prompt to `atomic-planner` rather than referencing them by path alone.