Skip to content

Remediation Plan

Use this skill to convert a gap analysis, audit report, or target state comparison into a structured, phased execution plan with dependencies, effort estimates, and risk management.

Problem

Gap analyses identify what's wrong. Teams need a plan that tells them what to do, in what order, with what effort, and what risks to watch for. Without structure, remediation becomes ad hoc — critical paths are missed, parallelisable work is serialised, and decisions block progress silently.

This skill produces a plan that:

  • organises work into phases with clear dependencies
  • sizes each task for sprint planning
  • identifies decisions that block progress and forces them to the surface
  • maps the critical path and parallelisable work
  • registers risks with mitigations so they don't surprise the team mid-execution

When To Use It

  • A gap analysis has been completed and needs to be turned into an execution plan.
  • A prototype needs a production readiness roadmap.
  • A decoupling, migration, or modernisation initiative needs phased planning.
  • Audit findings (security, design, operational) need a remediation sequence.
  • The user asks for a "remediation plan", "production readiness plan", "migration plan", "execution plan", or "roadmap".

Inputs

The skill needs one or more of:

  • A gap analysis report (from the gap-analysis skill or equivalent)
  • A target state description (architecture diagram, standards doc, or verbal description)
  • An audit report with findings and recommendations
  • Constraints: team size, timeline, external dependencies, blocked decisions

If no gap analysis exists, run the gap-analysis skill first or ask the user for the input findings.

Workflow

  1. Inventory the gaps. Read the input findings. Group them by domain (deployment, auth, observability, security, testing, operations). Use references/phase-patterns.md for common phase groupings.

  2. Identify dependencies. Map which gaps depend on others:

  3. Infrastructure must exist before deployment pipelines can target it
  4. Auth must work before security hardening makes sense
  5. Observability should be wired before production promotion

  6. Testing gaps can often be addressed in parallel with other phases Build a dependency graph. Identify the critical path.

  7. Group into phases. Each phase should:

  8. Have a clear entry condition (what must be done before it starts)
  9. Have a clear exit condition / deliverable list
  10. Be completable in 1–5 days by 1–2 people

  11. Contain tasks that are internally independent (parallelisable within the phase) Use references/phase-patterns.md for typical phase structures.

  12. Size each task. Use the effort scale from references/task-sizing.md. Include:

  13. Task description (action-oriented, specific)
  14. Effort estimate (Trivial / Small / Medium / Large)
  15. Issue/Jira ticket reference (if known, otherwise —)

  16. Status (⬜ Not started / 🔶 In progress / ✅ Complete)

  17. Surface decisions. List decisions that block one or more phases. For each:

  18. State the decision clearly
  19. List options with pros/cons
  20. Make a recommendation

  21. Note which phases are blocked until the decision is made

  22. Register risks. Use references/risk-template.md. For each risk:

  23. Impact (what goes wrong)
  24. Likelihood (Low / Medium / High)

  25. Mitigation (what to do about it)

  26. Define success criteria. For each major milestone (e.g., dev deployment, tst promotion, prd go-live), state the concrete criteria that must be met.

  27. Produce the plan. Use references/plan-template.md for the output structure.

  28. Hand off to WIP tracking (when execution starts). When the plan moves from draft to active execution, create a *.effort.json sidecar per plan-effort-estimate. Re-size steps with the Fibonacci scale — see the handoff rules in effort-scales.yaml.

Branching Rules

  • If the input is a gap analysis, map P0 gaps → early phases, P1 → middle phases, P2/P3 → later phases.
  • If the input is a decoupling/migration plan, organise phases around code movement: copy → wire → migrate consumers → validate → clean up.
  • If the input is an audit report, organise by severity: critical findings first, then high, then medium.
  • If the plan has more than 10 phases, consolidate. Most plans should have 5–8 phases.
  • If team size is 1, serialise all phases. If team size is 2+, show what can be parallelised.
  • If external dependencies exist (Azure subscription, Entra ID registration, security review), call them out as blockers with lead time estimates.

Execution Rules

  • Every task must be action-oriented and specific enough to create a Jira ticket from. "Improve observability" is too vague. "Add azure-monitor-opentelemetry dependency to services/api/pyproject.toml" is specific.
  • Include deliverables for each phase — concrete artifacts (files, configs, ADRs) that prove the phase is done.
  • Show the dependency map visually (ASCII diagram) so the critical path is obvious.
  • Include an effort summary table with total estimate and team size assumption.
  • Preserve architecture strengths from the gap analysis — do not plan work that would regress quality.
  • If the plan involves code vendoring or migration, include parity testing in the validation phase.
  • Keep decision tables separate from task tables — decisions are for leadership, tasks are for engineers.

References

Required Output

  • Current state summary (what exists, what's missing — brief).
  • Target architecture (diagram if applicable).
  • Phased execution plan with task tables per phase.
  • Dependency map (ASCII diagram showing phase ordering and parallelism).
  • Key decisions table (options, recommendations, which phases are blocked).
  • Risk register (impact, likelihood, mitigation).
  • Effort summary table (phase, effort, dependencies, status).
  • Success criteria per milestone.

Troubleshooting

Error: Plan has too many phases (10+) and feels overwhelming. Cause: Gaps were not consolidated by domain; each gap became its own phase. Solution: Merge related gaps into domain-based phases (see references/phase-patterns.md). Most plans should have 5–8 phases.

Error: Tasks are too vague to create tickets from. Cause: Task descriptions use abstract language ("improve", "set up") instead of specific actions. Solution: Each task must start with a verb and name the file, module, or endpoint affected. See task description rules in references/task-sizing.md.

Error: Plan stalls because decisions were not surfaced early. Cause: Decisions were embedded in task descriptions instead of tracked separately. Solution: Extract all blocking decisions into the Key Decisions table with options, recommendations, and which phases they block.

Completion Bar

  • Every gap from the input is addressed in at least one phase.
  • Phases have clear entry/exit conditions and deliverables.
  • The critical path is identified and the dependency map is consistent with phase ordering.
  • Decisions are separated from tasks and include actionable recommendations.
  • Risks have concrete mitigations, not just "monitor".
  • Effort estimates are realistic and team-size-aware.
  • The plan is directly convertible to Issues/Jira epics and stories.