gf-lint

name	gf-lint
description	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.
allowed-tools	["Bash","Read","Glob"]

GF Lint Skill

Lint SystemVerilog files with structured output for orchestration.

Tool Detection

Before running lint, check if Verilator is available:

which verilator

If Verilator is not available, check for Verible:

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:

ls *.sv rtl/*.sv 2>/dev/null | head -20

2. Run Verilator Lint

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

/* 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

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