Introducing a new way to review your PRs.

Read the announcement

pbakaus / impeccable

The design vocabulary for your coding agent. Steer with polish and bolder, review with critique and audit, catch AI slop before it ships.

View on GitHub

32 documents · Updated Nov 20, 2026

docs / detector-analysis-pipeline

Detector analysis pipeline

The detector analysis pipeline is the intended path from a project input to an actionable UI quality result. It discovers the target, chooses the evidence surface that can answer the question, gathers findings, applies project policy, and returns a result for a person or an automated caller. The implementation files that previously supplied this path are deleted in the current checkout, so this page records the system boundary and its expected behavior rather than a current code map.

Pipeline model

The pipeline joins several evidence paths behind one result contract. This keeps a local source scan useful for fast feedback while allowing a rendered page scan to answer questions that source text cannot prove.

flowchart LR
    A[Project input] --> B[Target discovery]
    B --> C{Evidence surface}
    C -->|Source| D[Source analysis]
    C -->|Static HTML| E[Document analysis]
    C -->|Rendered URL| F[Browser analysis]
    D --> G[Shared findings]
    E --> G
    F --> G
    G --> H[Project policy]
    H --> I[Actionable result]

The pipeline has four useful boundaries:

  • Discovery defines what belongs in the scan.
  • Mode selection defines what evidence the detector can collect.
  • Finding collection preserves the rule and target that produced each result.
  • Result processing applies context, ignores, advisory policy, and output rules.

Input discovery

Input discovery turns a user target into a scan plan. The plan can represent local source, a static HTML document, standard-input content, or a URL that must be loaded as a page. Directory scans should stay within project-owned source and avoid unrelated generated or dependency content.

Discovery is also the point where project ownership matters. A target can belong to a different project than the process working directory, so context must follow the target rather than the command that started the scan. The design system profiling page explains why this ownership boundary matters for consistency findings.

References: docs/quality-detector.md• L16-34 docs/design-system-profiling.md• L17-21

Analysis mode selection

Mode selection matches the input to the evidence it can provide. Source analysis reads authored patterns and can preserve source locations. Static HTML analysis reasons about a local document and its styles. Browser analysis loads a URL so the detector can inspect runtime state, layout, and painted results.

The modes are complementary rather than interchangeable. A source result can identify a risky declaration without proving that it wins in the cascade. A rendered result can show what a user sees without giving a reliable source line for every cause. The detection engines and antipattern rules page describes the evidence limits of each mode.

References: docs/quality-detector.md• L16-34 docs/quality-detector.md• L36-58 docs/detector-engines-and-rules.md• L22-54

Project context

Project context supplies the policy and visual reference used while a target is analyzed. It includes the design-system expectations and the ignore decisions that tell the detector which differences are intentional. Context must be resolved per project so a multi-project scan does not compare one project with another project's rules.

Context changes the meaning of a finding but does not replace the evidence that produced it. A design-system check can report drift only when the project has enough reference data to make a safe comparison. A missing reference should cause the check to abstain, not to invent a default standard.

References: docs/design-system-profiling.md• L5-21 docs/design-system-profiling.md• L51-69 docs/detector-command-and-configuration.md• L77-103

Finding collection

Each analysis surface returns findings through a shared contract. The contract lets output, hooks, agent workflows, and browser-facing tools use the same rule identity and policy fields without knowing which evidence surface produced the result.

Finding records

A finding identifies the antipattern, explains the concern, points to a file or URL, and includes the strongest available evidence. Source paths can provide a line and snippet. Document and browser paths can provide an element or page context instead. The record also carries status information such as severity or advisory state so consumers do not need to infer policy from the rule name.

Findings remain tied to their target while the coordinator combines results from many targets. This makes a directory scan useful as one report without losing the location needed to fix an individual problem. The quality detector page gives the broader rule and result model.

References: docs/quality-detector.md• L60-88 docs/detector-engines-and-rules.md• L101-117

Cross-file context

A project scan can add relationships between files after it discovers them. Import and stylesheet links provide usage context for a finding, but they do not turn the relationship map into a second full analysis. The important boundary is that every eligible target keeps its own analysis result while related files help an engineer understand where the source is used.

This context is most useful for source findings. A problem in a shared component can affect many pages, while a problem found only in a rendered URL belongs to the state of that page at scan time. The report should preserve that difference instead of flattening all evidence into one undifferentiated list.

References: docs/quality-detector.md• L126-138 docs/detector-engines-and-rules.md• L101-109

Result processing

Result processing applies project policy after collection. It removes intentional file, rule, value, and inline exceptions, separates advisory notes from blocking findings, and formats the remaining records for people or machines. This order keeps policy consistent across source, document, and browser results.

The final result has two consumers with different needs. Human output emphasizes location and explanation. Machine output keeps a stable structure and status so scripts and agent workflows can act without parsing prose. Command details and exit behavior belong in detector commands and configuration.

References: docs/detector-command-and-configuration.md• L50-67 docs/detector-command-and-configuration.md• L124-159 docs/quality-detector.md• L82-88

Evidence boundaries

The pipeline is useful because each mode has a clear claim boundary. Source and static checks provide fast local evidence. Browser checks provide stronger evidence about the page a user can see. Neither path should be treated as proof outside the state it inspected.

Source and rendered evidence

Source analysis can identify authored values, patterns, and likely problems before a site runs. It cannot prove the final cascade, dynamic content, layout, or painted pixels. Static HTML narrows that gap by modeling document structure and local styles, but it still does not replace a live browser for script-driven behavior.

Browser analysis can inspect computed state, geometry, runtime errors, visibility, and visual contrast. Its result depends on the URL, viewport, loaded assets, and page state at scan time. A source pass and a rendered pass therefore answer different questions and can both be valid without producing identical findings.

References: docs/quality-detector.md• L36-58 docs/detector-engines-and-rules.md• L24-54

Current source status

The detector orchestration and filesystem files listed in the refresh change set are deleted from the current checkout. The page therefore does not name those paths as active entry points. Use the related knowledge-base pages for the intended product contract, and treat any future detector implementation as a new source of truth for path-level details.

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep target discovery and analysis-mode selection aligned. A newly discoverable input must have a defined evidence path.
  • Keep project ownership attached to each target. A multi-project scan must not reuse context from the process working directory.
  • Keep finding fields stable across source, static HTML, browser, CLI, and agent consumers.
  • Keep policy application after collection and consistent across every evidence surface. A waiver must not work only for one mode.
  • Keep advisory status separate from blocking status in both human output and machine output.
  • Keep source evidence and rendered evidence distinct. Do not use a source-only result as proof of runtime layout or painted contrast.

Important failure modes

TriggerConsequenceGuard
An input has no matching analysis modeThe target is skipped or receives weaker coverage than the caller expects.Define the target type and its evidence contract together.
One project supplies context for another project's targetDesign-system findings can report false drift or miss real drift.Resolve context from the target's owning project.
A source finding is treated as proof of rendered behaviorThe report can blame code that the browser does not use or miss a runtime-only defect.Request a rendered URL scan when cascade, layout, or pixels matter.
Advisory findings are counted as blocking failuresAutomation can reject a change because of a review note.Preserve advisory status through filtering, output, and exit handling.
A finding loses its target or rule identity during aggregationA consumer cannot locate the problem or apply the correct ignore.Keep the shared finding contract intact while combining results.
The detector implementation is restored without updating this page's contractOnboarding guidance can describe behavior that differs across entry points.Recheck discovery, routing, context, collection, and result sections against the restored source.

Key files

FileWhy to read it
docs/quality-detector.mdGives the product-level purpose, analysis surfaces, finding policy, and shared detector boundaries.
docs/detector-command-and-configuration.mdExplains how callers select targets, configure scans, manage ignores, and consume results.
docs/detector-engines-and-rules.mdExplains what evidence each analysis surface can provide and how rules become findings.
docs/design-system-profiling.mdExplains target-owned design context and how authored or rendered values become comparison evidence.