# What Is the Role of better-interface in the Review Pipeline? > Discover how the better-interface skill orchestrates the review pipeline, aggregating and ranking findings for the UI. Learn its crucial role in delivering clear verdicts. - Repository: [Jakub Krehel/skills](https://github.com/jakubkrehel/skills) - Tags: deep-dive - Published: 2026-09-12 --- **The `better-interface` skill acts as the central orchestrator that aggregates findings from all `better-*` domain skills, ranks them by severity, consolidates duplicates, and issues the final verdict in the UI review pipeline.** In the `jakubkrehel/skills` repository, `better-interface` serves as the foundation of the UI audit system. Unlike domain-specific skills that contain individual linting rules, this skill coordinates the entire review lifecycle from request routing to final approval. Understanding its pivotal role is essential for configuring automated UI reviews that avoid rule duplication and conflicting verdicts. ## Core Orchestration Responsibilities According to [`AGENTS.md`](https://github.com/jakubkrehel/skills/blob/main/AGENTS.md) lines 58-77, `better-interface` manages five distinct stages that transform raw domain findings into a coherent audit report. ### Routing Requests to Domain Skills The orchestrator automatically dispatches review requests to every `better-*` domain skill registered in the ecosystem. This includes specialized auditors like `better-accessibility`, `better-colors`, and `better-layout`. Rather than executing UI checks itself, `better-interface` initiates parallel review jobs across the entire domain skill surface. ### Aggregating Findings by User Impact Once domain skills complete their analysis, `better-interface` collects all reported issues into a unified dataset. It applies a **severity scale** to rank findings based on user impact, ensuring that critical accessibility failures surface above minor cosmetic inconsistencies. This ranking logic is shared across all UI reviews to maintain consistent prioritization standards. ### Consolidating Results and Enforcing the Finding Cap The skill implements intelligent deduplication logic to merge overlapping findings from multiple domain auditors. It also applies the **finding cap**—a threshold mechanism that prevents review fatigue by limiting the total number of reported issues. This consolidation step occurs in [`better-interface/review-format.md`](https://github.com/jakubkrehel/skills/blob/main/better-interface/review-format.md), which defines the standardized output schema produced after aggregation (lines 3-23). ### Delivering the Final Verdict After processing the consolidated findings, `better-interface` issues the definitive review decision. It returns either an `Approve` status or a `Block` status based on the aggregated severity of discovered issues. This verdict represents the authoritative conclusion of the entire UI review pipeline. ## The Reverse Hand-Off Mechanism The activation flow for `better-interface` operates opposite to most skills in the repository. Typically, users invoke a skill directly, which then performs its analysis. However, as documented in [`skills/interface-review/SKILL.md`](https://github.com/jakubkrehel/skills/blob/main/skills/interface-review/SKILL.md) lines 11-15, the change-scoped `interface-review` skill **hands its scope and classified findings upward** to `better-interface`. When `interface-review` detects modified UI files, it resolves the scope, classifies findings by status (introduced, regression, or pre-existing), and passes this data package to `better-interface`. The orchestrator then performs ranking, consolidation, and verdict generation before returning the final result downstream. ```yaml # skills/interface-review/agents/openai.yaml (simplified) steps: - name: resolve-scope # ... determine changed files ... - name: classify-findings # ... attach status (introduced, regression, pre‑existing) ... - name: hand-to-better-interface invoke: better-interface args: scope: "{{resolved_scope}}" findings: "{{classified_findings}}" ``` *The `hand-to-better-interface` step passes the scope and classified findings to the orchestrator, which then performs the severity ranking and verdict generation.* ## Critical Constraint: Direct Invocation Prevention `better-interface` **must not be user-invoked** directly from the command line or chat interface. The documentation explicitly prohibits direct invocation because it would break the upward hand-off mechanism from `interface-review`. If users bypass the change-scoped reviewer, `interface-review` would subsequently trigger its own analysis, causing duplicate rules to appear in the final output and potentially generating conflicting verdicts. This architectural constraint ensures that the severity logic, finding cap, and consolidation algorithms execute exactly once per review cycle. ## Executing the Orchestrated Review While you cannot invoke `better-interface` in isolation, you trigger the complete orchestrated review through the standard entry point: ```bash # Install the skills collection (if not already installed) npx skills add jakubkrehel/skills # Run the orchestrated UI review on the current repository better-interface ``` *Note: In production environments, this command executes automatically as part of the `interface-review` pipeline rather than as a standalone user command.* When using the Claude Code plugin, the skill is addressed under the `interfaces` namespace: ```text /interfaces:better-interface ``` This invocation routes through the proper hand-off mechanism, ensuring `interface-review` handles the scope resolution before `better-interface` performs the final orchestration. ## Summary - **Routes** review requests to every `better-*` domain skill in the ecosystem - **Ranks** aggregated findings using a standardized severity scale based on user impact - **Consolidates** duplicate issues and applies the finding cap to prevent review fatigue - **Issues** the final `Approve` or `Block` verdict based on aggregated severity - **Must not be user-invoked** to prevent duplicate rule execution and broken hand-off logic ## Frequently Asked Questions ### What happens if I invoke better-interface directly? Direct invocation breaks the review pipeline architecture. When you manually trigger `better-interface`, it executes its orchestration logic without the scoped findings from `interface-review`. Subsequently, `interface-review` would run its own analysis and attempt to hand off to `better-interface` again, resulting in duplicated rules and potentially conflicting verdicts in the final report. ### How does better-interface differ from interface-review? `interface-review` is the change-scoped reviewer that detects modified UI files and classifies findings by status (introduced, regression, or pre-existing). `better-interface` is the domain-agnostic orchestrator that receives these classified findings, applies severity ranking, consolidates duplicates, and issues the final verdict. The former handles *what changed*; the latter handles *how severe it is and whether to block the merge*. ### What is the "finding cap" in the review pipeline? The finding cap is a threshold mechanism implemented in `better-interface` that limits the total number of issues reported in a single review. After consolidating duplicates from all `better-*` domain skills, the orchestrator enforces this cap to prevent developer fatigue from excessive minor warnings, ensuring that only the most impactful issues surface for remediation. ### Which domain skills does better-interface coordinate? `better-interface` automatically routes requests to all skills following the `better-*` naming convention within the repository. This includes specialized auditors such as `better-accessibility`, `better-colors`, `better-layout`, and any future domain-specific UI skills added to the ecosystem, as listed in the root [`README.md`](https://github.com/jakubkrehel/skills/blob/main/README.md) line 13.