Imported from atlanhq/application-sdk (.claude/skills/remediate/SKILL.md). Install upstream with npx skills add atlanhq/application-sdk --skill remediate. Copyright stays with the author.

/remediate — Conformance Remediation Loop

What it does

Runs an iterative, gated remediation loop over the conformance suite's findings:

1. Detect — run suite.runner --series <series> to get the current SARIF report; collect FAILING (and, with --strict, WARNING) findings.
2. Fix or suppress — for each finding, propose an edit (fix or suppression directive) guided by the rule's atlan/hint and the area prescription in $PROGRAMS/areas/<area>.prose.md (where PROGRAMS=$(uv run atlan-application-sdk-conformance programs-dir)).
3. Re-check (narrowest gate) — re-run the suite scoped to the touched file; confirm the finding's fingerprint is gone.
4. Orthogonal gate — for source-logic fixes, run the test suite; if it fails, revert the edit.
5. Loop — repeat until the finding-set is empty, an oscillation is detected, or the attempt cap (5) is reached.
6. Residue report — emit a structured markdown report of everything that needs human attention.

Usage

/remediate                              # all areas, default mode (FAILING only)
/remediate --strict                     # all areas, strict mode (FAILING + WARNING)
/remediate --area error-handling        # error-handling only
/remediate --area error-handling --strict
/remediate application_sdk              # restrict to application_sdk/ subtree only
/remediate --area error-handling application_sdk
/remediate --rule L004                  # exactly one rule (one-rule-per-run)
/remediate --rule L001,L011             # a specific set of rules
/remediate --area dockerfile --apply-unverifiable   # let I-series apply (docker-build gated)
/remediate --apply-unverifiable         # P/I/S apply instead of only proposing

Rule argument: restricts the run to exact rule IDs. Pushed down to the runner natively as --rule <IDS> whenever the pinned runner accepts the flag — the SARIF comes back scoped to exactly these rules, one descriptor per requested rule. A runner that rejects the flag falls back to the narrowest --series plus a rule-id post-filter inside detect-violations. Because tier is per-rule and not per-series, --rule is also the only way to express "the blocking rules first".

Path argument: a repo-root-relative path prefix that filters which findings are remediated. It does not change what the runner scans — the runner always scans the whole repo. Findings outside the prefix are left untouched.

Modes

Default — remediates only FAILING (BLOCK-tier, gate-blocking) findings.

Strict (--strict) — also remediates WARNING (WARN-tier) findings. Each WARNING is cleared by either a real fix or a justified inline suppression. Every suppression is routed to the residue report for human audit.

Headless / harness-driven mode

When a harness invokes this skill non-interactively (no shell, a hard time budget, detection pre-executed), the caller states so in its prompt. Honor these adjustments — they replace the corresponding steps of the loop, and nothing else changes:

• The shell being disabled is policy, not an error. Never attempt to run a command. Every command-shaped step is pre-handled by the caller: the detect step has already run (the caller names the SARIF path, typically in the repository root) and the findings ride the prompt. Work from those.
• Recheck is the caller's. The harness re-runs detection and every gate after the session ends — an in-session recheck is neither possible nor needed. Make the edits, then end the session.
• Pace yourself: edit early, edit incrementally. Begin applying fixes within your first few actions and fix each site as you inspect it. Do NOT survey the whole repository before the first edit — headless sessions have a hard deadline, and analysis without edits is discarded at it.
• Residue is a report, not a retry loop. A finding that genuinely cannot be fixed safely is skipped (last resort) and the caller accounts for it; do not burn the budget re-attempting it.
• All standing rules hold unchanged: never add a suppression outside strict mode, never touch tests/, .github/, or conformance/, never commit or push — leave changes in the working tree.

Area status

The live program (conformance-remediation.prose.md, resolved from the installed package via programs-dir) fans out to every area below; remediate-finding dispatches each finding to its area prescription.

To add a new area prescription: author <programs-dir>/areas/<name>.prose.md and add a dispatch branch to <programs-dir>/functions/remediate-finding.prose.md. The contract-toolkit area is the first example of an area using orthogonal_gate="pkl-eval" instead of "tests" — useful precedent for any future area whose fixes are validated by regenerating derived artifacts rather than by running the test suite.

Execution instructions

First resolve the live programs directory (the contracts ship inside the installed atlan-application-sdk-conformance package — the remediation/programs/ tree in the repo root is the design doc only):

PROGRAMS=$(uv run atlan-application-sdk-conformance programs-dir)

Phase 1: Baseline

Call detect-violations to run the suite and capture the before-state. Use the full enabled series so every remediable area is covered (scope is auto-detected, so app-only series no-op on the SDK):

let before = call detect-violations
  scope: .
  series: E,L,C,P,O,D,B,I,T,K,S
  rule_ids: <--rule argument split on commas, if any>
  target: if strict then "failing+warning" else "failing"
  path_prefix: <path argument, if any>

Copy before.sarif_path → remediation/runs/before.sarif to preserve it before the remediation loop overwrites detect.sarif. Note the counts (failing, warning, suppressed) from before.findings. Do not invoke suite.runner directly — detect-violations is the single owner of that invocation.

Phase 2: Execute the remediation loop

Read and execute the OpenProse contracts in $PROGRAMS, starting with conformance-remediation.prose.md. The contracts are self-contained English-plus-ProseScript — execute them directly as an agent (no separate OpenProse runtime required for the skill path).

Execution order (from conformance-remediation.prose.md):

1. Run every area responsibility in parallel (error-handling, deprecation, dependency, prescriptions, optimizations, dockerfile, tests, logging, ci, contract-toolkit, security) — the top-level contract fans out to all of them; do not hardcode a subset.

2. Each area responsibility calls the detect-fix-recheck pattern (patterns/detect-fix-recheck.prose.md), which loops:

   • functions/detect-violations.prose.md — run suite.runner, parse SARIF
   • functions/remediate-finding.prose.md — propose fix or suppress (dispatches on finding.area, e.g. deprecation → areas/deprecation.prose.md)
   • functions/recheck-narrowest.prose.md — deterministic re-check
   • functions/orthogonal-gate.prose.md — test suite (fix path only)

3. Accumulate residue across all areas; emit the unified report.

If the OpenProse skill is installed, you may alternatively run: npx reactor run conformance-remediation scope=<path> mode=<default|strict>

Phase 3: After-state

Call detect-violations again and copy the result to after.sarif:

let after = call detect-violations
  scope: .
  series: E,L,C,P,O,D,B,I,T,K,S
  rule_ids: <--rule argument split on commas, if any>
  target: if strict then "failing+warning" else "failing"
  path_prefix: <path argument, if any>

Copy after.sarif_path → remediation/runs/after.sarif. Compare after.findings counts against Phase 1. The failing count should be 0 (or equal to the escalated residue count — never silently passed). In strict mode, warning should also be 0.

Phase 4: Residue report

All residue items (judgment fixes, suppressions, recheck-failures, oscillations) are written to remediation/runs/residue.md with:

• rule_id, file, line, fingerprint
• proposed edit (if any)
• classification and outcome
• reason the item is in residue

Review each item before merging.

Anti-gaming disciplines (design §6)

OpenProse contracts

The full program is in remediation/programs/. For Reactor-ready execution:

# Install (dev-only — never a SDK runtime dep):
npm i -D @openprose/reactor @openprose/reactor-cli @openprose/reactor-devtools

# Scaffold state (first time):
npx reactor init remediation

# Compile DAG:
npx reactor compile

# Run:
npx reactor run conformance-remediation scope=. mode=default