linting-workflow-skill

name	linting-workflow-skill
description	Generic linting workflow for multiple languages with auto-fix and error resolution
license	Apache-2.0
compatibility	opencode
metadata	{"audience":"developers","workflow":"code-quality","protocol":"autoresearch-opt-in"}

What I do

I provide a generic linting workflow for multiple languages:

• Detect project language and linter configuration
• Run linting and apply auto-fix when available
• Guide resolution of linting errors
• Verify fixes and commit changes

When to use me

Use when:

• Linting code before committing or PRs
• Building workflow skills with code quality checks
• Need consistent linting across multiple languages

This is a framework skill - provides linting logic that other skills extend.

Steps

Step 1: Detect Language and Linter

Detection:

• package.json + tsconfig.json → TypeScript (ESLint)
• package.json → JavaScript (ESLint)
• pyproject.toml / requirements.txt → Python (Ruff)
• go.mod → Go (golint/golangci-lint)
• Gemfile → Ruby (RuboCop)

Configuration files:

• ESLint: eslint.config.ts/js/mjs, .eslintrc.json/js/yaml
• Ruff: pyproject.toml, .ruff.toml, ruff.toml

Step 2: Detect Package Manager

Language	Manager	Lock File	Command
JS/TS	npm	package-lock.json	npm run <script>
JS/TS	yarn	yarn.lock	yarn <script>
JS/TS	pnpm	pnpm-lock.yaml	pnpm run <script>
Python	Poetry	pyproject.toml	poetry run <script>
Python	pip	requirements.txt	Direct command

Step 3: Run Linting

Commands:

# JavaScript/TypeScript (ESLint)
npm run lint              # npm
yarn lint                 # yarn
pnpm run lint            # pnpm
npx eslint .             # direct

# Python (Ruff)
ruff check .             # direct
poetry run ruff check .  # poetry

Step 4: Apply Auto-Fix

Auto-fix commands:

• ESLint: npm run lint -- --fix
• Prettier: npx prettier --write .
• Ruff: ruff check . --fix
• Black: black .

Auto-fix capabilities:

• Style violations, unused variables, simple syntax issues
• Formatting, indentation, quotes
• Unused imports, simple refactorings

Step 5: Fix Remaining Errors

Error categories:

• Syntax errors (prevents code from running)
• Style violations (code style guidelines)
• Potential bugs (risky code patterns)
• Deprecation warnings (deprecated features)
• Type errors (TypeScript type mismatches)
• Missing docstrings (public functions/classes)

Resolution workflow:

1. Run auto-fix first
2. Fix remaining errors incrementally
3. Re-run linting after each batch
4. Use error messages for guidance

Step 6: Verify and Commit

Re-run linting:

# Re-check after manual fixes
npm run lint      # or
ruff check .

Commit fixes:

git add .
git commit -m "fix(lint): resolve linting errors"

Best Practices

• Run linting before committing
• Apply auto-fix before manual fixes
• Fix errors incrementally, re-run between batches
• Don't disable rules as workaround
• Configure editor to lint on save
• Integrate into CI/CD pipelines
• Use pre-commit hooks (Husky, pre-commit)

Common Issues

Linter Not Found

Install linter:

npm install --save-dev eslint  # ESLint
pip install ruff                # Ruff

Config File Missing

Create default config:

• ESLint: .eslintrc.json with {"extends": "eslint:recommended"}
• Ruff: pyproject.toml with [tool.ruff] line-length = 88

Too Many Errors

• Focus on one category at a time
• Fix incrementally
• Re-run after each batch

Auto-Fix Doesn't Work

• Some errors require manual intervention
• Review error messages
• Check if rule supports auto-fix

Iteration Protocol (opt-in)

DO NOT execute any of the following unless AUTORESEARCH_PROTOCOL=1 is set in your environment. When unset, this skill behaves exactly as documented in all sections above; the Iteration Protocol block is descriptive only.

When AUTORESEARCH_PROTOCOL=1:

1. Gate check: confirm env var is set; if unset, follow default behavior above.
2. Auto-detection: if this skill is invoked on a task that looks iterative (multiple cycles expected), prompt ONCE per session: "This looks iterative. Enable autoresearch protocol? (y/n)". On "y", continue; on "n", default behavior. Cache the answer for the session.
3. 5-stage loop: cycle Understand → Hypothesize → Experiment → Evaluate → Log & Iterate. See autoresearch-core-skill/SKILL.md.
4. Evaluator contract: emit {"pass":bool,"score":N} JSON from a mechanical evaluator. Pass determines keep/revert; score logged to linting-results.tsv. See autoresearch-core-skill/references/evaluator-contract.md.
5. Stuck detection: 3 consecutive non-improving iterations → strategy pivot; 5 consecutive → paradigm shift. See autoresearch-core-skill/references/stuck-detection.md.
6. Audit trail: append every iteration to linting-results.tsv (8-column: iteration, commit, metric, delta, status, description, timestamp, evaluator_output). See autoresearch-core-skill/references/audit-trail.md.
7. Crash recovery: syntax errors → fix immediately (don't count); runtime → max 3 fix attempts then skip; timeout → revert + log; OOM → smaller variant. See autoresearch-core-skill/references/crash-recovery.md.
8. Git-as-memory: commit before each verify; auto-revert (git reset --hard HEAD~1) on pass:false.
9. Iteration safety: bounded-by-default (Iterations: 25); safety blocks .env, node_modules/, rm -rf, git push --force. See autoresearch-core-skill/references/iteration-safety.md.

Skill-specific override

Stuck detection + crash recovery. 3 consecutive iterations without reducing lint-error-count → pivot to a different rule category (e.g., from E to W, or from style to type). Crash recovery: syntax errors introduced by auto-fix → revert immediately (don't count as iteration); rule conflicts → skip rule, log to linting-results.tsv.

Max iterations

• Default: 25 iterations
• Hard cap: 100 (explicit Iterations: unlimited overrides)