# Gf Lint

> SystemVerilog lint checker with structured output for orchestration. Runs Verilator lint, categorizes errors/warnings, explains issues, and returns a parseable result block for /gf orchestration.

- Skill: `codejunkie99/gf-lint` (Agent Skill)
- Install (CLI): `npx skillmds@latest add codejunkie99/gf-lint`
- Raw SKILL.md: https://api.skillmd.com/api/skills/codejunkie99/gf-lint/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: codejunkie99 (https://skillmd.com/u/codejunkie99)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/codejunkie99/gf-lint

---


# GF Lint Skill

Lint SystemVerilog files with structured output for orchestration.

## Tool Detection

Before running lint, check if Verilator is available:
```bash
which verilator
```

If Verilator is not available, check for Verible:
```bash
which verible-verilog-lint
```

If neither is available, return immediately:
```
---GATEFLOW-RESULT---
STATUS: ERROR
ERRORS: 0
WARNINGS: 0
FILES: []
DETAILS: No lint tool available. Install Verilator (recommended) or Verible.
  macOS: brew install verilator
  Linux: sudo apt install verilator
---END-GATEFLOW-RESULT---
```

Do NOT attempt to lint without a tool. Return the ERROR status and let the orchestrator handle it.

---

## Instructions

### 1. Identify Files to Lint

**If files specified in args:**
Use the provided file paths.

**If no files specified:**
Auto-detect SV files:
```bash
ls *.sv rtl/*.sv 2>/dev/null | head -20
```

### 2. Run Verilator Lint

```bash
verilator --lint-only -Wall <files>
```

### 3. Parse and Categorize Output

Count issues by category:
- **ERRORS**: `%Error:` lines - must be fixed
- **WARNINGS**: `%Warning-*:` lines - should be reviewed

### 4. Explain Common Warnings

For each warning type found, explain:

| Warning | Meaning | Fix |
|---------|---------|-----|
| UNUSED | Signal declared but not used | Remove signal or suppress with `/* verilator lint_off UNUSED */` |
| UNDRIVEN | Signal never assigned a value | Assign the signal or connect it |
| WIDTH | Bit width mismatch in operation | Add explicit sizing: `[7:0]` |
| CASEINCOMPLETE | Case statement missing items | Add `default:` branch |
| LATCH | Inferred latch from incomplete if/case | Add default assignment at start of always_comb |
| BLKSEQ | Blocking assignment in always_ff | Use `<=` (non-blocking) in sequential blocks |
| PINCONNECTEMPTY | Module port left unconnected | Connect or explicitly mark as `.*` |
| IMPLICIT | Implicit wire declaration | Declare with `logic` or `wire` |

### 5. Return Structured Result

**ALWAYS end your response with this exact block format:**

```
---GATEFLOW-RESULT---
STATUS: PASS|FAIL|ERROR
ERRORS: <count>
WARNINGS: <count>
FILES: <comma-separated list>
DETAILS: <one-line summary>
---END-GATEFLOW-RESULT---
```

**Status definitions:**
- `PASS`: No errors, warnings OK (0-N warnings acceptable)
- `FAIL`: One or more errors found
- `ERROR`: Could not run lint (missing files, tool error)

### 6. Example Output

```
Running lint on: rtl/fifo.sv, rtl/uart.sv

$ verilator --lint-only -Wall rtl/fifo.sv rtl/uart.sv

%Warning-UNUSED: rtl/fifo.sv:25: Signal 'debug_flag' is not used
%Warning-WIDTH: rtl/uart.sv:42: Operator ASSIGN expects 8 bits but got 16

## Summary

**Files:** 2 | **Errors:** 0 | **Warnings:** 2

### Warnings Explained

1. **UNUSED** (rtl/fifo.sv:25): `debug_flag` is declared but never read
   - Fix: Remove if unneeded, or suppress with lint pragma

2. **WIDTH** (rtl/uart.sv:42): Assigning 16-bit value to 8-bit signal
   - Fix: Truncate explicitly `data[7:0]` or widen the target

---GATEFLOW-RESULT---
STATUS: PASS
ERRORS: 0
WARNINGS: 2
FILES: rtl/fifo.sv,rtl/uart.sv
DETAILS: Lint passed with 2 warnings
---END-GATEFLOW-RESULT---
```

### 7. Error Case Example

```
$ verilator --lint-only -Wall rtl/broken.sv

%Error: rtl/broken.sv:10: syntax error, unexpected IDENTIFIER

---GATEFLOW-RESULT---
STATUS: FAIL
ERRORS: 1
WARNINGS: 0
FILES: rtl/broken.sv
DETAILS: Syntax error on line 10
---END-GATEFLOW-RESULT---
```

## Usage by /gf Orchestrator

The `/gf` skill uses this skill internally and parses the result block:

```
Parse ---GATEFLOW-RESULT--- block:
- STATUS: PASS -> proceed to next step
- STATUS: FAIL -> spawn sv-refactor agent with error context
- STATUS: ERROR -> report issue to user
```

## Verilator v5 New Warnings

### Lint Warnings (enabled by -Wall)
| Code | Description |
|---|---|
| ASSIGNEQEXPR | `=` used inside expression (may mean `==`) |
| ALWNEVER | `always @*` has empty event list |
| ALWCOMBORDER | Variable set after use in `always_comb` |
| IMPLICITSTATIC | Task/function variable implicitly static |
| WIDTHEXPAND | Value is zero-expanded |
| WIDTHTRUNC | Value is truncated |
| ENUMVALUE | Enum assigned incompatible type |
| CASEOVERLAP | Case values overlap |
| CASTCONST | `$cast` always succeeds or fails |
| CMPCONST | Comparison always yields constant |
| MISINDENT | Misleading indentation |
| MULTIDRIVEN | Signal driven by multiple always blocks |
| SYNCASYNCNET | Signal mixed sync/async resets |
| INFINITELOOP | Loop condition always true |
| SELRANGE | Selection index out of bounds |

### Style Warnings (enabled by -Wall)
| Code | Description |
|---|---|
| ASCRANGE | Packed vector with ascending range `[0:7]` |
| DECLFILENAME | Module name doesn't match filename |
| DEFPARAM | Deprecated `defparam` |
| GENUNNAMED | Generate block unnamed |
| IMPORTSTAR | `import pkg::*` in `$unit` scope |

### v5 Behavior Changes
- WIDTH is now a meta-category: disabling WIDTH disables WIDTHEXPAND + WIDTHTRUNC
- `--assert` enabled by default since v5.038
- `--lint-only` now implies `--timing`

## Warning Suppression

### Inline Pragma
```systemverilog
/* verilator lint_off WIDTH */
assign narrow = wide;
/* verilator lint_on WIDTH */
```

### Control File
```
lint_off -rule WIDTH -file "*.sv" -match "Operator ASSIGN*"
```

## Error Message Format

```
%Error: file.sv:42:5: syntax error, unexpected ';'
%Warning-WIDTH: file.sv:25:15: Operator ASSIGN expects 8 bits
```

### Exit Codes
| Code | Meaning |
|---|---|
| 0 | Success (no errors or fatal warnings) |
| 1 | Errors or warnings (warnings are fatal by default) |

Use `-Wno-fatal` to make warnings non-fatal.

## Machine-Readable Output

```bash
verilator --lint-only --diagnostics-sarif *.sv  # SARIF JSON output
```