Remediation flow

The remediate command generates or validates structured remediation plans
based on stored audit results.

Modes

Generate mode

remediate <skill> [--target-score N] [--dry-run]
  │
  ├── resolve skill path → locate most recent stored audit
  │     └── latestAuditJSON(.context/audits/<skill>/) → most recent <date>/audit.json
  │
  ├── load audit JSON → *scorer.Result
  │
  ├── determine target score (default: min(current + 20, 140))
  │
  ├── build remediation frontmatter:
  │     ├── execution summary (current → target)
  │     ├── score range (current, target, max)
  │     ├── grade range (current_grade, target_grade)
  │     └── critical issues
  │
  ├── build gaps (dimensions sorted by max-score descending)
  │     ├── current score, max, gap
  │     ├── associated diagnostics
  │     └── generic advice per dimension
  │
  ├── build phases:
  │     ├── Phase 1: Critical fixes
  │     ├── Phase 2: Core improvements
  │     └── Phase 3: Stretch goals
  │     └── Each phase has steps with verification commands
  │
  ├── build effort estimates:
  │     ├── overall effort (S/M/L)
  │     ├── total steps
  │     └── time estimate per effort level
  │
  ├── render:
  │     ├── Markdown (.context/plans/<skill>-remediation-plan-<date>.md)
  │     └── JSON (--json flag)
  │
  └── if --dry-run: stdout only

Validate mode

remediate <skill> --validate
  │
  ├── resolve plan path (direct path or glob in .context/plans/)
  │
  ├── reporter.ValidateRemediationPlan(planPath)
  │     ├── extract YAML frontmatter from `---` block
  │     └── validate against regex patterns and allowed values:
  │           ├── plan_date: YYYY-MM-DD
  │           ├── skill_name: kebab-case
  │           ├── source_audit: .context/audits/.../*.md path
  │           ├── score pattern: NNN/140 (NN%)
  │           ├── valid grades: A+, A, B+, B, C+, C, D, F
  │           ├── valid priorities: critical, high, medium, low
  │           ├── valid severities: critical, major, minor, info
  │           ├── valid efforts: S, M, L
  │           ├── step pattern: ## N.
  │           └── notes rating: N/10
  │
  └── returns list of validation errors (empty = valid)

Plan schema

The remediation plan follows a JSON schema defined at
cmd/assets/schemas/remediation-plan.schema.json. Key structural types:

remPlanFrontmatter (YAML frontmatter)
  ├── title, type ("PLAN"), status ("DRAFT"), date, effort (S/M/L/TBD),
  │   value ("MEDIUM"), themes (["SKILL-QUALITY"])
  │     └── matches the standard .context/ frontmatter schema, so a freshly
  │         generated plan is picked up by context-index/frontmatter
  │         validation without hand-patching. `value` (ADR-049) and a non-empty
  │         `themes` list (ADR-051) are required on DRAFT plans, so the generator
  │         emits both; the frontmatter is written with 2-space indentation to
  │         match the validator's block-list parser.
  ├── plan_date, skill_name, source_audit
  ├── execution_summary (current_score, target_score)
  ├── score_range (min, max, current, target)
  ├── grade_range (current_grade, target_grade)
  ├── critical_issues → []remCritical{description, dimension}
  └── phases → []remPhase{
        phase, title, objective,
        steps → []remStep{
          step, action, details,
          verification → string (shell command),
          code → remCode{language, content},
          effort → remEffort{size, ...},
          success_criteria → []remSuccessCriterion,
          notes → remNotes{rating, text}
        }
      }

Source files