What Is the Role of better-interface in the Review Pipeline?

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 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, 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 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.

# 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:

# 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:

/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 line 13.

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