F Kitchen Sink

UX audit rules

Cognitive clarity

Rule handbook metadata

Rule
AI.CONTEXT.COGNITIVE_CLARITY · lane ai
Page status
stale
page_version
147f28c00ed45941c1315962642216c8aa994bc2dbb23cf8c520b91f309b0a2a
generated_at
2026-05-19T20:15:00.000Z
registry_fingerprint
6773fda516344e110b5a7b1435e655e1264e773825ca8bbe62194189891c42ba

How this rule is fixed

This is an AI-enabled rule. Pass/fail requires model judgment; there is no deterministic fixer in the pilot registry.

  • Harness: invoke-ai-ruleset-harness.sh runs design-rules/ai/run-design-ai-rule.sh on the Before fixture and expects findings with matching principleId.
  • Remediation: Cursor agent plans from forge-ux-remediation.plan.md after sitewide audit — not handbook After copy.

Detection module: docs/design/ux-audit/ai-enabled-design-principles.md#ai-context-cognitive-clarity. Scroll down for Before / After examples and Evidence and remediation steps.

Purpose

Kitchen Sink landing_page and product_page shells (landing-hero, forge-section, section-label, forge-card) are built to tell a product story in layers. This AI rule judges whether a first-time reader can build the right mental model in one pass—without insider vocabulary, heading bait-and-switch, or reference dumps where an outcome should live.

Deterministic checks (DET.SECTION.HEADING, DET.CONTEXT.BURDEN, DET.PROSE.LENGTH) catch structural budgets and heading order; this rule covers judgment they miss: acronyms used before definition, section titles that do not match body substance, and technical depth placed above the fold before the reader knows what the product does.

Plan: Read the first viewport and the next section as a stranger—note undefined terms, logical jumps, and headings that promise one job but deliver another. Do: Lead with problem → outcome → mechanism; define Forge terms inline on first use; link schemas, APIs, and long indexes below the story. Check: A colleague can paraphrase the page's single promise without guessing. Adjust: If the same clarity defect repeats (undefined product names in heroes, misleading section-label text), propose a deterministic DET.* companion.

Passing signals

  • Hero copy states what it is and who it is for in plain language before naming sub-products (product-landing-title → short landing-hero-tagline → one primary CTA).
  • Product names (Lenses, LCDL, Fleet, ForgeSDLC) appear after a one-line plain-language gloss, or only in a dedicated ecosystem band—not unexplained in the headline.
  • Each section-label and following h2/h3 match the section body (no "Quickstart" band that is actually a schema dump).
  • Progressive disclosure: API tables, prop lists, and long forge-support asides live in the next forge-section or behind a clear "Read reference" link—not in the hero grid.
  • Headings follow a scannable ladder (h1 once, section jobs obvious); in-page TOC entries (DET.NAV.IN_PAGE_TOC) align with what the eye sees.
  • Paragraphs stay readable (DET.PROSE.LENGTH); lists use at most three bullets per card when explaining outcomes.

Failing signals

  • Headline or tagline stacks acronyms and internal codenames with no inline definition ("LCDL + Fleet + Lenses control plane" before the reader knows the problem).
  • section-label or card card-label promises onboarding or outcomes but the body is endpoint lists, generated nav, or maintainer-only detail.
  • Heading text is generic ("Overview", "Details", "More") while the section mixes unrelated jobs—reader cannot predict what they will learn.
  • Hero landing-hero-explainer or landing-hero-clarification paragraphs jump from trust model to JSON shapes without a mechanism sentence in between.
  • First screen reads like documentation cover: dense forge-card tiles with implementation vocabulary and no outcome framing.
  • Jargon is reused in CTAs and secondary links before it was introduced anywhere on the page.

Before example

Before (failing example)

Forge Platform

LCDL, Fleet, and Lenses in one spine

POST /v1/jobs, SQLite job store, governed task operators, and workspace hash catalogs.

Open schemas API reference

Outcomes

What you get on day one

Reference

Job plane endpoints

  • POST /v1/jobs — docker_argv payload
  • GET /v1/jobs/{id} — status and logs pointer

Failing KS markup: undefined product names in the hero, misleading section label, reference dump in the outcomes band.

After example

After (passing example)

Forge Platform

Governed delivery from intent to evidence

Teams delegate more work to agents but still need clear intent, review gates, and proof.

Lenses (workspace visibility), LCDL (governed LLM tasks in Python), and Fleet (bounded job execution)—linked below, not assumed.

See how it works Read the docs

Outcomes

What you get on day one

Trust

Bounded execution

Human approval points and inspectable job history.

Speed

Agent-ready structure

Intent and evidence without a docs dump in the hero.

Depth

Reference when you need it

Schemas and API tables live in Reference—not the first screen.

Passing KS markup: plain-language promise first, terms defined on first use, outcomes band matches labels, reference deferred.

Evidence and remediation

Capture: first-viewport screenshot, heading outline (H1–H3), and a plain-language paraphrase test ("What is this page asking me to believe?"). Note any acronym or product name that appears before definition.

Remediate (in order):

  1. Rewrite hero to problem → outcome; move endpoint lists, schemas, and maintainer vocabulary to Reference or a lower forge-section.
  2. Align every section-label / h2 with the section's single job (DET.SECTION.SINGLE_JOB); split mixed bands.
  3. Define Forge terms inline on first use (short parenthetical or landing-hero-clarification sentence)—then reuse freely.
  4. Stage depth: outcome cards in band two; mechanism diagram or steps in band three; link walls last.
  5. Re-check DET.SECTION.HEADING order and DET.CONTEXT.BURDEN after edits.
  6. If the pattern repeats (e.g. undefined product names in heroes), propose a deterministic companion such as a glossary-first hero lint or heading/substance matcher.