What it does #

From release 2.3.0, Norma ships two AI-powered scanners alongside the deterministic rulesets:

• Architecture / SOLID Analyzer — detects design smells that pattern-matching rules can’t easily catch: dependency-inversion violations, single-responsibility offenders, interface-segregation problems, and other SOLID-related architectural issues. Pro-only — see Pro-only rulesets.
• Prompt Scanner — reviews LLM prompts in your repository (Markdown, YAML, or code-embedded) for injection risks, missing output schemas, unpinned model versions, ambiguous instructions, and other prompt-quality concerns.

Because these scanners reason over your code rather than pattern-match, their output benefits from a quick human sanity check. Norma keeps their findings on their own tab so they can’t accidentally get mixed with deterministic issues, distort your issue counts, or move your Production Ready Score.

Some Norma scanners are powered by AI rather than deterministic rule engines. Their results live on a dedicated AI Findings tab so you can review them separately from your standard issues. They complement your scan — a quick review is recommended before acting on each one — and they don’t contribute to your Production Ready Score.

Where to see them #

Open any repository — click the AI Findings tab (fourth tab, sibling to Overview, Coverage, and Issues). The tab carries a small AI chip so it’s easy to spot.

If your last scan produced AI findings, you’ll also see a callout on the Overview tab:

N AI findings ready for review · Not included in your score · View AI Findings

The callout is count-only and disappears when you have no AI findings. It never breaks down by severity and it never contributes to the score ring — the score stays purely deterministic.

When you’d use it #

• Architectural refactors. The SOLID Analyzer surfaces the kind of design debt that shows up in code review, not in a linter. Use it to pick refactor targets.
• AI-powered features you’re shipping. If your repository contains prompts driving LLM calls, the Prompt Scanner catches classes of issues (prompt injection, unpinned models, cost blow-ups) that deterministic rules don’t cover.
• Second opinion on a codebase you’re new to. AI Findings tends to surface higher-level “why is this shaped this way?” questions that are useful when you’re onboarding into an unfamiliar repository.

What’s on the tab #

At the top, a persistent banner reminds you of the ground rules:

These findings are generated by AI and complement your deterministic scan — a quick review is recommended before acting on each one. They don’t contribute to your Production Ready Score.

Below the banner, a tool toggle lets you switch between Architecture / SOLID Analyzer and Prompt Scanner. Only tools with findings on your last scan are shown — if the Prompt Scanner has nothing to report, its option is hidden.

The table has five columns:

Filters at the top of the table mirror the standard Issues tab: search, severity, impact area, module. Sort options include Confidence (high → low or low → high), Newest first, and Severity.

Click any row to open the finding detail.

Reading a finding #

Clicking a row opens a side panel with the following, in order:

• Rule name, slug, severity chip, and tool chip (SOLID or Prompt).
• Why this was flagged — the AI’s explanation of what it saw and why it flagged this specific piece of code.
• Confidence — the score as a large percentage plus a meter. Click Why this score to see the AI’s reasoning about the confidence itself (why it’s 94% and not 100%, or why it’s 55%). Not every finding has this — when it’s missing, the expander is hidden.
• Suggested fix — a concrete, per-finding fix proposed by the AI. Some findings don’t come with a suggested fix; when that’s the case, the section is simply not shown.
• Code snippet — the offending code with a copy button. SOLID findings often reason about a class or module rather than a single line, so this block is sometimes empty and hidden.
• File · Detected · Impact area · Est. time to fix — the same metadata footer as a deterministic issue detail.

AI Findings on Rulesets #

If a rule fires only AI findings on your repository (no deterministic issues), you’ll see a small +N AI findings chip next to its zero deterministic count in the Rulesets view. Clicking the chip jumps you to the AI Findings tab pre-filtered by that rule — so a rule with zero deterministic hits doesn’t look broken when it’s actually catching things on the AI side.

Why they don’t affect the score #

The Production Ready Score is a stability contract: the same code, scanned twice, should give you the same number. AI-powered scanners reason over code rather than pattern-match, so their output can shift slightly between scans. To keep the score repeatable, AI findings are excluded from:

• The Production Ready Score ring on the Overview tab.
• The READY / NOT READY label.
• Each area sub-score (Security, Performance, Architecture, Maintainability, Scalability, Manageability).
• The badge summary and per-tool metric counts.

They still appear on the AI Findings tab, still count on the callout, and are still linked from Rulesets — they just don’t move a headline number. See Production Ready Score for how the deterministic score is computed.

Human-in-the-loop review actions (accept, dismiss, defer) are on the roadmap for a later release. In this release, AI Findings is read-only — a review-and-act surface, not a triage queue. Look for a placeholder band in the finding detail saying “AI-generated · Review actions coming soon” — that’s where those controls will land.

Limits & notes #

• AI Findings run automatically on every scan. There’s nothing to enable in Settings — if your repository’s detected stack includes rules the AI scanners cover, they’ll appear on the next scan.
• AI findings never contribute to the Production Ready Score, the READY / NOT READY label, the badge, or any area sub-score. This is by design and won’t change.
• Confidence is AI self-reported. Treat it as a triage hint, not a guarantee. A 90% confidence finding is a stronger signal than a 55% one, but neither replaces your judgement — always sanity-check before acting on the suggested fix.
• Suggested fixes are per-finding, not per-rule. Two findings of the same SOLID rule will produce two independent fix suggestions tailored to the code around each occurrence.
• The AI Findings count and the Issues count don’t overlap. A finding is either deterministic (in the Issues tab) or AI (in the AI Findings tab), never both — no double counting.
• Empty is a valid state. A scan that finishes with zero AI findings is a valid outcome — the tab shows “No AI findings on your last scan” and the Overview callout is hidden.
• No review actions in this release. Accept / Dismiss / Defer, status filters, and bulk actions are planned for a future release.

Related #

• Reading results — the standard Issues tab, for deterministic findings.
• Production Ready Score — the deterministic-only score AI findings deliberately don’t touch.
• Coverage tab — see every ruleset and rule that ran on your code, deterministic and AI.
• Rulesets overview — how rulesets attach to your stack.
• Pro-only rulesets — the SOLID Analyzer is Pro-only; here’s what “locked” means on Free and what happens on upgrade / downgrade.
• Glossary — definitions of AI Findings, Confidence, and related terms.