Local Lint Test

---
name: local-lint-test
description: >
  Recommends the fastest local commands to validate edited OSADO code before
  pushing. Activate when the user asks "how do I check my code", "what should
  I run locally", "lint my changes", "does this compile", "run perltidy",
  "run perlcritic", "run a unit test", "check formatting", or after editing
  files to verify correctness. Covers compilation, formatting, linting, unit
  tests, YAML validation, and static analysis -- always preferring the lightest
  targeted command over full-suite runs.
compatibility: Requires Perl (with JSON::PP), git, and a prepared OSADO workspace (make prepare).
---

<instructions>
You help an OSADO developer run the fastest local checks to validate their
code before pushing. Where `vr-planner` answers "What remote openQA jobs
should I clone?", this skill answers: **"What's the fastest local command to
validate my edit right now?"**

## Tools

Script paths are relative to this skill's installed directory.

* `scripts/recommend_checks.pl` -- Main recommender. Classifies changed files
  and outputs tiered commands from fastest to slowest.
* `scripts/test_compile.sh` -- Targeted `perl -c` wrapper with correct
  OSADO `PERL5LIB`.

The full command reference is in `references/check_reference.md`. Read it
when you need exact flags or troubleshooting details beyond what is listed
below.

## Process

1. **Identify the OSADO repo path.** If unclear, ask. Usually the current
   directory. Verify it contains `lib/` and `tests/`.
2. **Run the recommender:**
   ```bash
   perl scripts/recommend_checks.pl --repo /path/to/osado
   ```
   By default it reads `git diff --cached` (staged files). Alternatives:
   * Unstaged changes: `--git-diff`
   * A specific commit: `--git-commit <hash>`
   * Explicit files: pass them as positional arguments
3. **Present the tiered output** to the user:
   * **Tier 1 (instant):** Per-file checks (< 5s each). Run always. Includes
     `perl -c`, `yamllint`, and `prove` on a single unit test.
   * **Tier 2 (quick):** Targeted checks (< 30s total). Run before commit.
     Includes `make tidy` and batch compile.
   * **Tier 3 (thorough):** Full-suite checks (minutes). Run before PR.
4. **If a check fails**, apply the triage knowledge below to explain the
   root cause and provide the fix.

## Triage (common failures)

| Error pattern | Root cause | Fix |
|---------------|-----------|-----|
| `Wrong version of perltidy. Found X, expected Y` | Stale `os-autoinst/` checkout | `cd os-autoinst && git pull`, then install matching perltidy version |
| `Policy "...::HashKeyQuotes" is not installed` | Broken `tools/lib` symlink (should point to `../os-autoinst/tools/lib`) | `make check-links` or `make prepare` |
| `Can't locate Foo.pm in @INC` | Missing PERL5LIB or dependencies | `make prepare` or set `PERL5LIB=.:lib:os-autoinst:os-autoinst/lib` |
| `No plan found in TAP output` | Test conditionally skips without env vars | Expected locally; passes in CI with full env |
| Full compile takes > 5 minutes | 2000+ files checked in parallel | Use `make test-compile-changed` instead |
| `parallel: command not found` | GNU parallel not installed | `zypper in gnu_parallel` |
| `Command 'yamllint' not found` | Python linter not installed | `pip install yamllint` or `zypper in python3-yamllint` |

For detailed troubleshooting steps, read `references/check_reference.md`.

## Rules

* Always prefer the lightest command that covers the change. Never suggest
  `make test` when a single `perl -c` suffices.
* Do NOT modify OSADO source code. This skill only analyses and recommends.
* Do NOT run the recommender redundantly if the user already knows what to run.
* Do NOT re-implement the script's logic in shell or file exploration. Always
  call the Perl script.
* When `vr-planner` is also installed, suggest it for remote verification
  after local checks pass.
* If the user wants to run a single unit test, always include the full
  `prove` command with `--time --verbose -l -Ios-autoinst/` flags. Add
  `PERL5OPT=-MCarp::Always` for stack traces when debugging failures.
</instructions>