How Findings Are Ranked and Capped in the better-interface Skill: A Complete Guide

The better-interface skill enforces a strict 15-finding cap and ranks issues using a four-tier pipeline: automatic triggers first, then severity (HIGH/MEDIUM/LOW), followed by reach, and finally fix impact.

The better-interface skill in the jakubkrehel/skills repository serves as an orchestration layer that consolidates results from all better-* domain reviews. Understanding how findings are ranked and capped in the better-interface skill is essential for interpreting review outputs correctly, as the system employs specific severity escalations and quantitative limits to prioritize the most critical interface defects.

The 15-Finding Cap and Severity Architecture

The skill imposes hard limits on output volume to ensure actionable reports. According to skills/better-interface/SKILL.md, the ranking system operates within strict quantitative boundaries while classifying every finding through a standardized severity taxonomy.

Maximum Findings Limit

The skill reports at most 15 findings for any single review. This cap applies regardless of how many domain-specific issues are detected across the codebase. When the total number of qualifying findings exceeds this threshold, the system truncates the output but explicitly notes how many items were omitted.

Three-Tier Severity Classification

Every finding is first classified on a shared three-tier ladder defined in lines 71-76 of the SKILL.md file:

• HIGH – Blocks a task, misleads the user, hides content or controls, risks data loss, or causes systemic failure.
• MEDIUM – Meaningfully harms comprehension, efficiency, adaptability, or consistency.
• LOW – Isolated polish with limited task impact.

This classification forms the primary sorting key before secondary ranking factors are applied.

Escalation Triggers and Automatic HIGH Severity

Certain "trigger" conditions bypass standard severity assessment and are automatically assigned HIGH severity regardless of other contextual factors. As documented in skills/better-interface/SKILL.md (lines 79-94), these triggers include:

• Missing accessible name on interactive elements
• Lack of focus indicator for keyboard navigation
• Motion animations ignoring prefers-reduced-motion
• Contrast failures below WCAG thresholds
• Other critical accessibility or usability blockers

These trigger-based findings always appear first in the final report, even when multiple HIGH severity issues exist.

The Ranking Algorithm: From Severity to Fix Impact

After trigger classification and severity assignment, the better-interface skill applies a deterministic sorting pipeline. The complete ranking order is: trigger → severity → reach → fix-impact.

Primary Sort by Severity

Findings are bucketed by their severity tier, with HIGH issues appearing before MEDIUM, and MEDIUM before LOW. This ensures that critical blockers receive immediate attention regardless of other quantitative factors.

Secondary Sort by Reach and Fix Impact

Within each severity tier, the system applies two additional ranking criteria:

1. Reach – Quantifies how many places the symptom appears across the interface. Higher reach scores prioritize issues affecting multiple screens or components.
2. Fix impact – Measures how much a single fix resolves. A shared-component fix outranks the same symptom appearing in a leaf component because resolving the shared element eliminates the issue across all consuming instances.

This secondary sorting ensures that high-leverage fixes appear before localized, single-instance issues.

Handling the Cap: Omission Notices and Report Structure

When the sorted list exceeds 15 items, the skill applies the cap and generates a transparent omission notice. According to lines 95-96 of skills/better-interface/SKILL.md, the final report lists the highest-ranked findings first and explicitly states how many findings were omitted due to the cap.

The following Python example demonstrates the expected JSON structure and sorting logic that the better-interface skill applies internally:

# Example finding structure produced by a domain skill

finding = {
    "description": "Button lacks an accessible name",
    "path": "src/components/SubmitBtn.jsx:12",
    "severity": "HIGH",                 # Trigger‑based, forced HIGH

    "reach": 3,                         # Affects 3 screens

    "fixImpact": "shared-component",    # Fix replaces a shared token

}

# `better-interface` collects findings from all domains, sorts them,

# then enforces the 15‑item cap:

all_findings = collect_findings_from_domains()
sorted_findings = sorted(
    all_findings,
    key=lambda f: (
        {"HIGH": 0, "MEDIUM": 1, "LOW": 2}[f["severity"]],
        -f["reach"],
        {"shared-component": 0, "leaf": 1}[f["fixImpact"]]
    )
)
capped_findings = sorted_findings[:15]
omitted = len(sorted_findings) - len(capped_findings)

report = {
    "findings": capped_findings,
    "omitted_count": omitted,
}

Implementation in SKILL.md

The ranking and capping behavior is formally specified in skills/better-interface/SKILL.md. This file defines the orchestration logic that consolidates inputs from all better-* domain reviews, applies the severity triggers, executes the multi-tier sorting algorithm, and enforces the 15-item output limit. The skills/better-interface/review-format.md file consumes these ranked findings to generate the final structured output, while skills/better-interface/agents/openai.yaml provides the agent configuration wiring the skill into the Claude-Code execution environment.

Summary

• Hard cap: The better-interface skill never reports more than 15 findings per review.
• Automatic escalation: Trigger conditions (missing accessible names, contrast failures, etc.) force HIGH severity regardless of context.
• Ranking pipeline: Issues sort by trigger status, then severity tier, then reach (scope of impact), then fix impact (shared vs. leaf components).
• Transparency: When findings exceed the cap, the report notes exactly how many items were omitted.
• Source authority: All logic is defined in skills/better-interface/SKILL.md within the jakubkrehel/skills repository.

Frequently Asked Questions

What is the maximum number of findings the better-interface skill can report?

The skill enforces a strict maximum of 15 findings per review. This cap is defined in skills/better-interface/SKILL.md and applies to all consolidated reports regardless of how many domain-specific issues are detected.

How does the better-interface skill determine if a finding is HIGH severity?

Findings receive HIGH severity through two paths: standard classification for blockers that halt tasks or risk data loss, or automatic escalation via trigger conditions. Triggers include missing accessible names, lack of focus indicators, motion violating prefers-reduced-motion, and contrast failures—these bypass normal assessment and are forced to HIGH.

What happens when there are more than 15 findings in a review?

The system sorts all findings by the ranking pipeline (severity, reach, fix impact), takes the top 15, and generates an omission notice. The final report includes the omitted_count field indicating how many lower-ranked findings were excluded from the output.

Where is the ranking logic defined in the jakubkrehel/skills repository?

All ranking rules, severity definitions, escalation triggers, and capping behavior are specified in skills/better-interface/SKILL.md (lines 26-96). Additional context appears in skills/better-interface/review-format.md for output formatting and skills/better-interface/agents/openai.yaml for agent configuration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}