Lint and Type-Check

Guides agents through discovering, executing, and resolving linter and static type-checker errors. Strictly forbids suppressing issues with @ts-ignore, eslint-disable, # noqa, or # type: ignore.

1. Purpose

Ensure code adheres to codebase static typing and style standards before committing. "Type-checking" verifies type safety without runtime execution (e.g. tsc --noEmit, mypy). "Linting" identifies stylistic defects, unused imports, syntax hazards, and antipatterns (e.g. eslint, ruff, golangci-lint).

2. When to Use

Use this skill when:

• Finishing a code change before opening a pull request or declaring task completion.
• Investigating pre-commit hook failures or CI lint pipeline failures.
• User requests: "Lint the project", "Run type checks", or "Fix lint errors".

3. When Not to Use

• Do not use to run functional or unit tests; use test-runner-debugger.
• Do not use to review architectural diffs for security risks; use diff-reviewer.
• Do not use to refactor working code when no lint errors exist; use small-refactor.

4. Required Inputs

• workspace_root: Directory containing the project (default: current working directory).
• target_files: Optional specific files modified (e.g. src/auth.ts).

5. Missing-Input Behavior

1. If no target files are specified: inspect git status --porcelain to identify changed files.
2. If tool configuration is unknown: inspect manifests (package.json, pyproject.toml, go.mod, Cargo.toml) to identify configured linter and type-checker commands.
3. Strict Prohibition: Never resolve a lint or type error by adding @ts-ignore, @ts-expect-error, eslint-disable, # noqa, # type: ignore, or any unless explicitly instructed by the user.

6. Procedure

Follow these numbered actions:

1. Action 1: Identify Configured Tools
   • Node/TypeScript: Check package.json scripts (lint, typecheck, check), tsconfig.json, .eslintrc*, biome.json.
   • Python: Check ruff check, flake8, mypy, pyright, black --check.
   • Go: Check golangci-lint run, go vet ./....
   • Rust: Check cargo clippy -- -D warnings.
2. Action 2: Execute Type-Check First
   • Run type-checker (e.g., npx tsc --noEmit or mypy <files>).
   • Fix type errors before linting, as types often eliminate underlying logic hazards.
3. Action 3: Execute Linter
   • Run linter command (e.g., npm run lint or ruff check .).
   • Parse output: extract file path, line number, column, rule name, and error description.
4. Action 4: Apply Root-Cause Fixes
   • Address the root cause (e.g., add missing return type, remove unused variable, handle null case).
5. Action 5: Re-Verify Clean Exit
   • Re-run type-checker and linter until exit code is 0 with zero errors and zero warnings.
6. Action 6: Emit Summary Report
   • Format per Section 8.

7. Decision Rules

• If safe auto-fix is available (e.g., eslint --fix or ruff check --fix): run auto-fix for formatting/whitespace, then manually fix remaining logical errors.
• If a type error is caused by a missing library type definition: check if @types/<pkg> is required in devDependencies.
• If an import is unused: delete the unused import statement; do not comment it out.

8. Output Format

Emit the report using this template:

### Lint & Type-Check Verification

- **Type Checker**: `[Command, e.g., npx tsc --noEmit]` -> [PASS | FAIL]
- **Linter**: `[Command, e.g., npm run lint]` -> [PASS | FAIL]
- **Files Checked**: [Count or file list]
- **Issues Resolved**: [Count]

#### Resolved Issues
| File | Line | Rule / Error Code | Root Cause & Resolution |
| :--- | :--- | :--- | :--- |
| `[file]` | `[line]` | `[e.g., TS2345]` | [Fixed type mismatch by casting or guard] |
| `[file]` | `[line]` | `[e.g., no-unused-vars]` | [Removed unused import variable] |

#### Final Verification Status
- Clean exit code `0` confirmed across all tools.

9. Verification Checklist

• Type-checker exited with code 0.
• Linter exited with code 0.
• Zero @ts-ignore or # noqa suppression comments were introduced.
• No unrelated files were reformatted.

10. Common Failures and Recovery

11. Stop or Escalation Conditions

Stop and ask the user when:

• Resolving a type error requires changing a public library API signature shared across external packages.

12. Examples

Example 1: Successful Execution

Input:

Target file: src/user.ts
Error: TS2322: Type 'string | null' is not assignable to type 'string'.
Line: 18: const username: string = user.getName();

Output:

### Lint & Type-Check Verification

- **Type Checker**: `npx tsc --noEmit` -> PASS
- **Linter**: `npm run lint` -> PASS
- **Files Checked**: 1 (`src/user.ts`)
- **Issues Resolved**: 1

#### Resolved Issues
| File | Line | Rule / Error Code | Root Cause & Resolution |
| :--- | :--- | :--- | :--- |
| `src/user.ts` | 18 | `TS2322` | `getName()` returns `string \| null`. Added nullish coalescing default: `const username: string = user.getName() ?? 'Guest';`. |

#### Final Verification Status
- Clean exit code `0` confirmed across all tools.

Example 2: Ambiguous or Missing Input

Input:

Lint the code.
Context: No manifest in directory.

Output:

### Lint & Type-Check: Halted - No Configuration Found

- **Status**: Halted

No linter or type-checker configuration was detected in the workspace (no `package.json`, `tsconfig.json`, `pyproject.toml`, or `.golangci.yml`). 
Please specify:
1. The programming language and tools used.
2. The specific command you use to lint or check types.

Example 3: Expected Final Output

Output:

### Lint & Type-Check Verification

- **Type Checker**: `mypy src/` -> PASS
- **Linter**: `ruff check src/` -> PASS
- **Files Checked**: 3
- **Issues Resolved**: 2

#### Resolved Issues
| File | Line | Rule / Error Code | Root Cause & Resolution |
| :--- | :--- | :--- | :--- |
| `src/api.py` | 12 | `F401` | Removed unused import `import sys`. |
| `src/client.py` | 44 | `arg-type` | Corrected timeout parameter type from `float` to `Optional[float]`. |

#### Final Verification Status
- Clean exit code `0` confirmed across all tools.