megalinter-fix

MegaLinter fix

Fix the MegaLinter errors you were given (output contract of megalinter-check: linter keys, error counts, files, sample error lines).

1. Prepare

• If the current branch is the default branch (main/master), create a branch first: git checkout -b megalinter/fix-<topic>.
• Group the errors by linter key. Handle blocking linters (❌) first; mention non-blocking ones (⚠️) to the user but don't fix them unless asked.

2. Load the fix guides — lazily

For each failing linter only, read its fix guide from this skill's directory: linters/<linter_key_lower>.md (e.g. linters/python_ruff.md). The index is in linters/README.md.

Each guide contains a generated block (auto-fix support, config/ignore files, rule documentation URLs, tuning variables, known non-lint failure patterns) and researched fix instructions. Never load guides for linters without errors.

3. Fix

In this order:

1. Auto-fixable linters (guide says auto-fix supported): if a container engine is available, run npx mega-linter-runner --linter <KEY> --fix [failing files...] (add --container-engine podman when using podman; use npx mega-linter-runner@beta when .mega-linter.yml pins MEGALINTER_VERSION: beta — see the version rule in megalinter-check). Otherwise apply the underlying tool's documented fix behavior manually. If no engine is installed/running, ask the user first, then follow container-engine.md in the megalinter-check skill directory.
2. Manual fixes: fix remaining errors file by file following the guide's instructions. Consult the rule documentation URLs when unsure what a rule means.
3. Errors not covered by the guide (unknown rule, missing/outdated guide): browse the web — fetch the rule's official documentation (start from the URLs in the guide's generated block) or search for the exact error message — before deciding on a fix. Never guess a fix or a suppression syntax.
4. Ambiguous cases (fix would change behavior, several valid approaches, false positive suspected): ask the user, presenting the options — fix this way, inline-disable with justification, or ignore.

4. Disabling (always with user confirmation)

When fixing is not relevant (false positives, rule conflicts with project style, linter not applicable):

• Narrowest first: inline-disable comment on the line → rule exclusion in the linter's config file → <KEY>_FILTER_REGEX_EXCLUDE → <KEY>_DISABLE_ERRORS: true (non-blocking) → DISABLE_LINTERS (last resort).
• The guide gives the exact syntax for each level. Never disable anything without explicit user confirmation.
• If a project-mode linter reports unexpected results tied to its exclusions or config resolution, check its console log for [Excluded directories] lines: MegaLinter automatically forwards excluded directories through extra CLI arguments or generated ignore/config files. Disabling that forwarding for the linter (<LINTER_KEY>_FORWARD_EXCLUDED_DIRECTORIES: false) restores the tool's native behavior — useful when the repository's own ignore/config files are already complete.

5. Verify and finish

1. Re-check with the megalinter-check skill (targeted re-check mode: only the fixed linters/files). Iterate at most 3 times in total.
2. Show the user a summary: fixed / disabled (with justification) / remaining.
3. Commit on the working branch with a clear message. Ask before pushing; never push to the default branch.
4. If the push triggers a CI run and the repository auto-applies fixes (APPLY_FIXES_MODE: commit), MegaLinter may push a [MegaLinter] Apply linters fixes commit on top of yours: watch the run with megalinter-check, which handles that commit (see its "MegaLinter auto-fix commits" section) — always pull before making further edits.

Optimization: sub-agents (Claude Code and compatible agents)

If sub-agents are available and megalinter-fixer is installed (see megalinter-setup), fan out one megalinter-fixer per failing linter in parallel, giving each: the linter key, its error list, and the content of its fix guide. Each fixer returns its fixed count, modified files, and an unresolved list (possibly containing proposed_disable suppressions — fixers never apply disables themselves). Consolidate, ask the user about every unresolved item and proposed disable, apply the confirmed ones yourself, then run the targeted re-check (via megalinter-runner agents when available).

When MegaLinter is installed as an agent plugin the definitions are namespaced (megalinter:megalinter-watcher, megalinter:megalinter-runner, megalinter:megalinter-fixer); installed as skills they keep their bare names. Use whichever form your platform lists.

Without sub-agents, fix linters sequentially inline.