Lint triage

Lint Triage — RTL Lint & Methodology Violation Triage

A playbook for driving SynthPilot's lint/methodology tools to find real RTL problems, then sorting every violation into one of three buckets: fix it, waive it (with a stated justification), or ask the human. The deliverable is a triaged report, not a green number. A lint run that is "clean" because real violations were silenced is a failure of this skill.

This skill follows one discipline above all: measure → classify → fix the smallest safe thing → re-measure. It never invents a tool, never downgrades a severity to hide a problem, and never claims "lint clean" without fresh tool output proving it on the current source.

---

When to use

• User asks to "lint my RTL", "review my RTL", "check code quality", "find unintended latches", "clean up warnings", or "is this design lint-clean".
• Before synthesis sign-off, before a design review, or before handing RTL to a teammate, to catch latches, incomplete sensitivity lists, width mismatches, unconnected ports, blocking/non-blocking misuse, and methodology violations.
• After an RTL edit, to confirm a class of violations is actually gone (not just moved or masked).
• To produce a defensible waiver list — each waiver tied to an explicit reason — for items that are intentional and safe.

When NOT to use

• Timing closure (WNS/TNS negative, failing setup/hold). Lint is not timing. Use the timing-closure skill. check_async_reset here surfaces reset-path methodology issues, not slack.
• Pure CDC sign-off (metastability, gray-coding, handshake correctness). check_cdc_lint / report_cdc are a first screen only; deep CDC analysis is a separate playbook. Lint-triage flags CDC violations and hands them off.
• Functional verification (does the logic compute the right answer). That is simulation (sim_*), not lint. Lint cannot tell you a correct-looking design is functionally wrong.
• DRC / route sign-off (report_drc on a placed/routed design). Different stage, different tool.
• No project is open / Vivado is not reachable. Resolve Prerequisites first.

---

Prerequisites (verify first)

Do not run any check until these pass. If one fails, stop and report it — do not guess.

1. MCP / Vivado reachable. Call test_connection. If it fails, the Tcl server inside Vivado is not connected on TCP:9999 — report and stop.
2. A project is open with sources. Call get_project_info and list_source_files. If no project or no RTL sources, stop and ask the user to open the project / point at the files.
3. Top module is set (needed for elaboration-stage checks). If get_project_info shows no top, call set_top_module only with a name the user gave or that is unambiguous from list_source_files; otherwise ask.
4. Know which stage you can reach. Syntax-stage checks need only sources. Methodology-stage checks (run_full_lint_check, report_methodology, get_lint_violations, check_latches, check_fsm, check_coding_style, check_cdc_lint, check_simulation_mismatch) require an open synthesized design. Plan to reach that stage in Step 3 — do not call those tools before the design is open or they will error.

---

Methodology (numbered, real tool calls)

Work the stages in order. Each stage is cheaper/earlier than the next; do not skip ahead, because a syntax error makes every later check meaningless.

Step 1 — Establish the file baseline

• list_source_files and (if useful) check_compile_order. A wrong compile order produces phantom "undefined module" / black-box noise downstream; fix ordering before trusting any later result.
• Record the file set and top module. This is the scope every later claim is bounded to ("lint-clean" means these files, this top, nothing more).

Step 2 — Syntax-stage checks (no synthesis required)

Run the checks that work directly on source. These are fast and catch the errors that would otherwise abort synthesis:

• check_syntax (all sources) — must be clean before anything else is trustworthy.
• check_compile_order — ordering / include problems.
• check_black_box — undefined modules (missing files, typo'd module names, or a genuinely intended black box / external IP).
• check_port_width_mismatch — connection width mismatches at instantiation.
• check_unconnected_ports — dangling/unconnected ports.

If check_syntax reports errors, STOP the lint flow here. Classify and surface the syntax errors (Step 5 table) and do not pretend later stages are clean — you cannot run them on broken source.

Step 3 — Reach a synthesized design for methodology checks

Most high-value RTL lint (latches, FSM health, coding style, CDC, sim/synth mismatch) requires an elaborated/synthesized netlist.

• If a synthesized design is not already open, run synthesis. For anything beyond a tiny design prefer the async pattern: run_synthesis_async, then poll get_run_status until complete (multi-minute operations must not block).
• Then open_synthesized_design. (An already-open open_implemented_design also satisfies the prerequisite.)
• Also pull get_synthesis_warnings — synthesis warnings frequently are the lint findings (inferred latch, truncation, dropped logic) and corroborate the dedicated checks.

If synthesis fails, the failure itself is the top-priority violation: capture it, classify it (Step 5), and stop — there is nothing to lint on a netlist that doesn't exist.

Step 4 — Methodology / RTL-quality checks (on the open synth design)

Run the methodology suite and the targeted RTL checks:

• run_full_lint_check — full syntax + methodology pass; the broad sweep.
• report_methodology then get_lint_violations — the structured violation list you will triage (each item has a check name / ID).
• check_latches — inferred latches, the single most important RTL lint signal; an unintended latch is almost always a real bug.
• check_fsm — FSM encoding / unreachable-state / dead-state health.
• check_coding_style — synthesis-relevant coding issues.
• check_cdc_lint — first-screen clock-domain-crossing flags (hand deep CDC off).
• check_simulation_mismatch — constructs that simulate differently than they synthesize (the worst class: it works in sim, fails in hardware).

For any violation you do not understand, pull detail with report_lint_violation_detail(violation_id=...) before deciding what to do with it. Never triage blind.

Step 5 — Triage every violation

For each violation, read its detail and place it in exactly one bucket using the table below. Do not batch-waive. Do not batch-ignore. One verdict per item, each with a one-line reason.

Step 6 — Apply the smallest safe change, one class at a time

• Fixes are recommended, not silently applied. Latches, width mismatches, and sim/synth mismatches are RTL bugs — describe the exact edit (which signal, which always/process block, default assignment vs full case, blocking vs non-blocking) and let the human approve before you touch source with update_file / replace_in_file. Use read_file_lines to ground the recommendation in the real code.
• Waivers require a stated assumption. Only after the item is confirmed intentional do you call waive_lint_violation(check_name=..., reason="<why this is safe and intended>", objects=...). The reason string is mandatory and must be a real justification, not "waived".
• Change one class per iteration (e.g. fix latches, OR waive a reviewed style rule — not both), so the re-measure attributes cause to effect.

Step 7 — Re-measure (close the loop)

After each change class, re-run the relevant check on the current source/ netlist (re-synthesize if RTL changed) and diff the violation list. A fix is only "done" when the violation it targeted is gone from fresh tool output and no new violation appeared. Record before/after counts.

---

Classification / decision table

Map each violation to a cause and the smallest safe response. The default verdict is FIX; WAIVE is allowed only with an explicit, true justification; ASK when intent is unknown.

Symptom / check	Likely cause	Smallest safe response	Default verdict
check_latches finds inferred latch	Incomplete if/case or missing default in comb logic	Recommend full assignment (default value / else / default:); confirm with read_file_lines	FIX (RTL)
check_port_width_mismatch	Instantiation port width ≠ signal width	Recommend resizing the signal/port; never widen blindly — verify intent	FIX (RTL) / ASK
check_unconnected_ports	Dangling port	If functionally required → FIX (connect); if intentionally unused → tie-off/objects waiver with reason	FIX / WAIVE
check_black_box	Missing file, typo'd name, OR intended external IP/stub	If missing → add file / fix check_compile_order; if intended → WAIVE with reason	FIX / WAIVE
check_simulation_mismatch	Init values, #delay, sensitivity-list, X-pessimism gaps	RTL fix — these are silent hardware bugs	FIX (RTL)
check_fsm unreachable/dead state	Unhandled case / wrong reset / dead code	Recommend handling or removing the state; do not waive a reachable hole	FIX (RTL)
check_coding_style violation	Blocking/non-blocking misuse, mixed assigns, style rule	If functional risk → FIX; if cosmetic & team-approved → WAIVE with reason	FIX / WAIVE
check_cdc_lint flag	Unsynchronized crossing / missing handshake	Hand to CDC sign-off; never waive a real crossing to clear lint	ASK / FIX
report_methodology / get_lint_violations generic item	Vivado methodology rule (e.g. SYNTH-/TIMING- family)	Read report_lint_violation_detail; fix or justify per the item	depends → triage
Rule is a known false positive for this design	Tool over-reports a safe pattern	WAIVE the specific check_name/objects with a reason naming why it's safe	WAIVE
Intent genuinely unknown	Can't tell if the construct is deliberate	Present the finding + options; hand back to human	ASK

---

Iteration loop & STOP conditions

LOOP:
  1. Run the relevant check(s)            (Step 2 / Step 4)
  2. get_lint_violations  -> list
  3. For each item: report_lint_violation_detail -> classify (table)
  4. Apply ONE change class:
        - FIX  (recommend RTL edit, get approval, then update_file/replace_in_file)
        - WAIVE (waive_lint_violation with a real reason)   [reviewed items only]
  5. Re-synthesize if RTL changed; re-run the check          (Step 7)
  6. Diff before/after violation list
  -> repeat

STOP the loop when any of these is true:

• Clean: the targeted check returns zero violations on fresh output, and every remaining item is an explicit, justified waiver in list_waivers. This is the only "lint clean" you may claim — and only with the fresh output in hand.
• All remaining items need human judgment (ASK bucket): present options + trade-offs and hand back. Do not thrash trying to auto-resolve intent.
• A fix would require unapproved RTL surgery beyond the smallest safe change (architectural change, retiming logic, restructuring an FSM): surface the recommendation and stop; do not silently apply it.
• No progress / oscillation: the same violation count persists or a "fix" spawns new violations after two iterations. Stop, report the conflict, hand back.
• An upstream blocker reappears (syntax error, synthesis failure): drop back to that stage; the lower stage owns the fix.

---

Safety rails (do not violate)

• No fake-pass. Never make the number green by hiding a real problem. Do not call set_lint_severity to downgrade a check, disable_lint_rule, or waive_lint_violation on an item that could be a genuine bug just to clear it. A latch, width mismatch, CDC crossing, or sim/synth mismatch is presumed real until proven intentional.
• Waivers need a stated, true justification. Every waive_lint_violation call carries a reason that explains why the construct is safe and intended — scoped with objects to the specific cell/net where possible, never a blanket waiver of an entire check. If you cannot articulate the justification, you may not waive it; ask the user.
• Smallest safe change first. Prefer connecting a port, fixing compile order, or scoping a waiver over rewriting RTL. Constraint/config/style fixes before source edits; source edits before architectural changes.
• Recommend RTL edits; don't silently apply them. Show the exact change (file, line range from read_file_lines, before/after) and get approval before update_file / replace_in_file. Latch and mismatch fixes especially must be reviewed.
• Evidence before claims. "Lint clean" / "no latches" / "violation fixed" REQUIRES fresh output from the relevant tool after the change, on the current source/netlist. Never infer it from "I made the edit." If RTL changed, re-synthesize before re-checking — stale netlist results are not evidence.
• Stay in scope. Lint-triage flags timing/CDC/DRC items and hands them to the right skill. It does not pretend a CDC waiver or a severity downgrade closes a timing/CDC issue.
• Real tools only. Use only the SynthPilot tool names referenced here. If a needed capability is missing, say so plainly rather than inventing a tool.

---

Output

Deliver a triage report, not a verdict-by-assertion:

1. Scope — files (list_source_files) + top module + the stage reached (syntax-only vs synthesized). Every claim is bounded to this.
2. Violation summary — counts by severity/check, before vs after, from get_lint_violations / get_synthesis_warnings (fresh output, quoted/cited).
3. Triage table — one row per violation: check / ID | location | cause | verdict (FIX / WAIVE / ASK) | action taken or recommended.
4. Fixes applied — only those the user approved; show before/after snippet (read_file_lines) and the re-measured result proving the violation cleared.
5. Waivers — the current list_waivers output, each with its justification. Flag any waiver whose reason is weak so the human can revisit it.
6. Open items / hand-offs — ASK-bucket items with options + trade-offs, and anything routed to timing / CDC / DRC / simulation skills.
7. Honest status line — e.g. "Lint clean on <files>/<top> at synthesis stage: 0 unwaived violations, N justified waivers (fresh get_lint_violations output attached)." Never state "clean" without that fresh evidence; if blocked, say exactly what blocks it and what decision you need from the user.