UX: Add PROOF9 terminology tooltips and glossary to Proof page

[frankbria]

Problem

The Proof page shows columns like 'Glitch Type', 'Severity', 'Obligations', and status values (open/satisfied/waived) without any inline explanation. New users are expected to know PROOF9 domain terminology.

Impact

Users cannot interpret proof results or decide how to act on failing gates, creating high friction in the quality validation workflow.

Recommendation

1. Add help icon (ⓘ) next to 'Glitch Type', 'Severity', 'Obligations' column headers with tooltip definitions
2. Add status legend below table header: open = must pass, satisfied = passed/evidence collected, waived = approved exception
3. Add page-level intro: "PROOF9 tracks quality requirements with evidence. Requirements must be satisfied before shipping."
4. Link to /help or docs for full PROOF9 reference

Acceptance Criteria

• Tooltip on each PROOF9-specific column header
• Status legend visible on page
• Page intro text explains PROOF9 purpose
• Help link provided for full reference
• New users can understand table without prior knowledge

Affected Components

web-ui/src/app/proof/page.tsx, web-ui/src/components/proof/ProofStatusBadge.tsx

[coderabbitai]

🔗 Related PRs

#461 - feat(web-ui): PROOF9 requirements list, detail, and dashboard widget (#458) [closed]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[traycerai]

Warning

Something went wrong while processing your request.

Reference ID: f469dc86-04a1-489a-ac84-a8e925dc8da6

Please try again or contact support if the issue persists, referencing this ID.

[coderabbitai]

Coding Plan

Summary

• Establish tooltip infrastructure by adding the Radix tooltip primitive and creating a shadcn/ui-style wrapper component
• Add unobtrusive info icons with contextual tooltips to domain-specific column headers (Glitch Type, Severity, Gates)
• Provide a compact inline status legend that explains the three status values without requiring users to leave the page
• Enhance page intro text and add an in-page help section with anchor link for users who want more detailed explanations

Design Choices

Design Choice 1: Help link destination

Options Considered:

1. Create a placeholder external link (e.g., /docs/proof9) to be updated when documentation exists
2. Add an in-page help section with an anchor link from the header area

Chosen Option: 2

Rationale: Add an in-page collapsible or static help section at the bottom of the page with an anchor link, providing immediate value without requiring a separate page build.

Design Choice 2: Info icon selection

Options Considered:

1. InformationCircleIcon - standard info icon convention
2. HelpCircleIcon - question-mark style help indicator

Chosen Option: 1

Rationale: InformationCircleIcon is the conventional choice for inline explanatory tooltips and aligns with common UI patterns.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Add Tooltip Infrastructure

This phase establishes the tooltip primitive required for the column header enhancements. The codebase currently lacks any tooltip component, so this must be added before the Proof page can use interactive tooltips.

Task 1: Install Radix Tooltip Package

Install the @radix-ui/react-tooltip package as a project dependency.

• Add @radix-ui/react-tooltip to dependencies in web-ui/package.json
• Run package installation to update node_modules and lockfile

Task 2: Create Tooltip Component

Create the shadcn/ui-style Tooltip wrapper component following established patterns.

• Create web-ui/src/components/ui/tooltip.tsx following the existing shadcn/ui wrapper pattern used in dialog.tsx, tabs.tsx, and other primitives
• Export Tooltip, TooltipTrigger, TooltipContent, and TooltipProvider components
• Apply consistent styling with Tailwind classes matching the design system (background, border radius, padding, animation)
• Use @radix-ui/react-tooltip primitives as the foundation

🤖 Prompt for AI agents

This phase sets up the tooltip infrastructure needed by the Proof page by
installing the Radix tooltip package and creating a shadcn/ui-style wrapper
component.

- Add `@radix-ui/react-tooltip` to the dependencies in `web-ui/package.json` and
run package installation to update node_modules and lockfile
- Create `web-ui/src/components/ui/tooltip.tsx` following the same shadcn/ui
wrapper pattern used in existing components like `dialog.tsx` and `tabs.tsx`
  - Use `@radix-ui/react-tooltip` primitives as the foundation
- Export four named components: `Tooltip`, `TooltipTrigger`, `TooltipContent`,
and `TooltipProvider`
- Apply Tailwind CSS classes consistent with the existing design system
(background, border radius, padding, animation)

Phase 2: Enhance Proof Page UX

This phase implements all user-facing changes to the Proof page: tooltips on domain-specific columns, a status legend, improved intro text, and a help reference.

Task 1: Add Tooltips to Column Headers

Add info icons with explanatory tooltips to the Glitch Type, Severity, and Gates column headers.

• Import Tooltip, TooltipTrigger, TooltipContent, TooltipProvider from @/components/ui/tooltip in web-ui/src/app/proof/page.tsx
• Import InformationCircleIcon from @hugeicons/react
• Wrap the page content in <TooltipProvider> (typically at the component root level)
• Modify the three target <th> elements to include an info icon wrapped in tooltip components:
  • Glitch Type: Explain what glitch types represent (e.g., "The category of quality issue this requirement addresses")
  • Severity: Explain severity levels and their implications (e.g., "Impact level: critical, high, medium, or low")
  • Gates: Clarify that gates are obligations that must be satisfied (e.g., "Number of evidence gates that must pass to satisfy this requirement")
• Style info icons to be subtle and non-intrusive (small size, muted color, inline with header text)

Task 2: Add Status Legend

Add a visible legend section explaining the meaning of open, satisfied, and waived statuses.

• Add a new <div> section in web-ui/src/app/proof/page.tsx positioned between the stats summary bar and the table
• Include three legend items with visual status indicators (can reuse badge styling from ProofStatusBadge or use colored dots):
  • open (red): Requirements that must still be satisfied before shipping
  • satisfied (green): Requirements that have been proven with collected evidence
  • waived (gray): Requirements with an approved exception, no evidence required
• Style as a compact horizontal row with flex gap-* layout to keep it unobtrusive
• Use text-sm text-muted-foreground styling consistent with the existing stats summary

Task 3: Update Page Intro and Add Help Reference

Enhance the page header with more instructive intro text and add a link to detailed help content.

• Update the subtitle paragraph in web-ui/src/app/proof/page.tsx to be more instructive for new users (e.g., "PROOF9 tracks quality requirements with evidence. Requirements must be satisfied or waived before shipping.")
• Add a "Learn more" or help link near the page header that anchors to an in-page help section
• Create a collapsible or static help section at the bottom of the page (before </main>) containing:
  • Brief explanation of PROOF9 purpose and workflow
  • Definitions of key terms (Glitch Type, Severity, Gates/Obligations)
  • Explanation of the requirement lifecycle (open → satisfied/waived)
• Use an id attribute for the section to enable anchor linking (e.g., id="proof9-help")
• Style the help section with a bordered card or subtle background to distinguish it from the main content

🤖 Prompt for AI agents

This phase implements all user-facing UX improvements to
`web-ui/src/app/proof/page.tsx`, including column header tooltips, a status
legend, updated intro text, and an in-page help section.

**Tooltips on Column Headers:**
- Import `Tooltip`, `TooltipTrigger`, `TooltipContent`, `TooltipProvider` from
`@/components/ui/tooltip`
- Import `InformationCircleIcon` from `@hugeicons/react`
- Wrap the page content root in `<TooltipProvider>`
- Update the three target `<th>` elements (Glitch Type, Severity, Gates) to each
include an `InformationCircleIcon` wrapped in tooltip components with the
following copy:
  - **Glitch Type**: "The category of quality issue this requirement addresses"
  - **Severity**: "Impact level: critical, high, medium, or low"
- **Gates**: "Number of evidence gates that must pass to satisfy this
requirement"
- Style icons to be small, muted, and inline with the header text

**Status Legend:**
- Add a new `<div>` between the stats summary bar and the table
- Include three legend items using badge styling from `ProofStatusBadge` or
colored dots:
  - **open** (red): "Requirements that must still be satisfied before shipping"
- **satisfied** (green): "Requirements that have been proven with collected
evidence"
- **waived** (gray): "Requirements with an approved exception, no evidence
required"
- Layout as a compact horizontal row using `flex gap-*`
- Apply `text-sm text-muted-foreground` styling consistent with the existing
stats summary

**Page Intro and Help Reference:**
- Update the subtitle paragraph to read: "PROOF9 tracks quality requirements
with evidence. Requirements must be satisfied or waived before shipping."
- Add a "Learn more" anchor link near the page header pointing to `#proof9-help`
- Add a help section before `</main>` with `id="proof9-help"` containing:
  - A brief explanation of PROOF9 purpose and workflow
  - Definitions of Glitch Type, Severity, and Gates/Obligations
  - Explanation of the requirement lifecycle (open → satisfied/waived)
- Style the help section as a bordered card or with a subtle background to
visually separate it from the main content

Research

The web-ui uses Next.js with shadcn/ui components built on Radix UI primitives, and @hugeicons/react for icons. The Proof page (web-ui/src/app/proof/page.tsx) displays PROOF9 requirements in an 8-column table with a stats summary bar above it. Currently, no Tooltip component exists in the codebase—only native HTML title attributes are used for basic hover text. The shadcn/ui components are located in web-ui/src/components/ui/ and follow a consistent wrapper pattern around Radix primitives. The @radix-ui/react-tooltip package is not currently installed.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

This phase sets up the tooltip infrastructure needed by the Proof page by
installing the Radix tooltip package and creating a shadcn/ui-style wrapper
component.

- Add `@radix-ui/react-tooltip` to the dependencies in `web-ui/package.json` and
run package installation to update node_modules and lockfile
- Create `web-ui/src/components/ui/tooltip.tsx` following the same shadcn/ui
wrapper pattern used in existing components like `dialog.tsx` and `tabs.tsx`
  - Use `@radix-ui/react-tooltip` primitives as the foundation
- Export four named components: `Tooltip`, `TooltipTrigger`, `TooltipContent`,
and `TooltipProvider`
- Apply Tailwind CSS classes consistent with the existing design system
(background, border radius, padding, animation)
===============================================================================

Task: 2

This phase implements all user-facing UX improvements to
`web-ui/src/app/proof/page.tsx`, including column header tooltips, a status
legend, updated intro text, and an in-page help section.

**Tooltips on Column Headers:**
- Import `Tooltip`, `TooltipTrigger`, `TooltipContent`, `TooltipProvider` from
`@/components/ui/tooltip`
- Import `InformationCircleIcon` from `@hugeicons/react`
- Wrap the page content root in `<TooltipProvider>`
- Update the three target `<th>` elements (Glitch Type, Severity, Gates) to each
include an `InformationCircleIcon` wrapped in tooltip components with the
following copy:
  - **Glitch Type**: "The category of quality issue this requirement addresses"
  - **Severity**: "Impact level: critical, high, medium, or low"
- **Gates**: "Number of evidence gates that must pass to satisfy this
requirement"
- Style icons to be small, muted, and inline with the header text

**Status Legend:**
- Add a new `<div>` between the stats summary bar and the table
- Include three legend items using badge styling from `ProofStatusBadge` or
colored dots:
  - **open** (red): "Requirements that must still be satisfied before shipping"
- **satisfied** (green): "Requirements that have been proven with collected
evidence"
- **waived** (gray): "Requirements with an approved exception, no evidence
required"
- Layout as a compact horizontal row using `flex gap-*`
- Apply `text-sm text-muted-foreground` styling consistent with the existing
stats summary

**Page Intro and Help Reference:**
- Update the subtitle paragraph to read: "PROOF9 tracks quality requirements
with evidence. Requirements must be satisfied or waived before shipping."
- Add a "Learn more" anchor link near the page header pointing to `#proof9-help`
- Add a help section before `</main>` with `id="proof9-help"` containing:
  - A brief explanation of PROOF9 purpose and workflow
  - Definitions of Glitch Type, Severity, and Gates/Obligations
  - Explanation of the requirement lifecycle (open → satisfied/waived)
- Style the help section as a bordered card or with a subtle background to
visually separate it from the main content

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!