Plan Site UX at Scale

Problem

The current plan site works well for small projects but will hit usability pain points as the number of entities grows. Specific issues:

• Sidebar overload: Every entity is listed flat within its type group, sorted alphabetically by ID. At 50+ work items, this becomes an unusable wall of links with no way to find what you need without scrolling.
• No filtering from the sidebar: The {% backlog %} rune supports field:value filtering, but only inside page content. There's no way to narrow the sidebar itself.
• Dashboard is static: The auto-generated dashboard shows four fixed sections (active milestone, ready, in-progress, recent decisions). It doesn't surface blocked items, overall progress, or let users scope to a specific milestone.
• Tags are invisible in navigation: Every entity carries tags, but they're only visible on the entity page itself. There's no cross-cutting view by tag, assignee, or milestone.
• No keyboard-driven navigation: For a developer-facing tool, mouse-only interaction feels slow.

This spec captures a set of improvements to address these, ordered by impact. All features described here build on the infrastructure established by SPEC-014 (HTML adapter + client behaviors).

Prerequisite

SPEC-014 — Plan Site via HTML Adapter. That work provides @refrakt-md/behaviors integration and renderFullPage(), which the features below depend on for client-side interactivity.

Features

1. Collapsible Status Groups in Sidebar

Priority: High

Replace the flat entity list with status-grouped, collapsible sections within each entity type:

Work Items
  ▸ In Progress (3)
  ▸ Ready (7)
  ▾ Review (2)
      WORK-031 Migrate renderer
      WORK-028 Add highlight support
  ▸ Done (24)
  ▸ Draft (5)

Behavior:

• Items are grouped by status within each entity type
• Groups are collapsible (toggle on click)
• Terminal statuses (done, fixed, accepted, complete, superseded, deprecated, wontfix, duplicate) are collapsed by default
• Active statuses (in-progress, ready, review, confirmed) are expanded by default
• The count badge shows how many items are in each group
• Collapse state is persisted in localStorage so it survives page navigation

Status ordering within each type (mirrors workflow progression):

• Work: in-progress → review → ready → blocked → draft → pending → done
• Bug: in-progress → confirmed → reported → fixed → wontfix → duplicate
• Spec: review → draft → accepted → superseded → deprecated
• Decision: proposed → accepted → superseded → deprecated
• Milestone: active → planning → complete

Active/in-progress statuses appear first so the most actionable items are always visible at the top.

Implementation: A new sidebar-collapse behavior in @refrakt-md/behaviors or as a plan-specific behavior. The server renders the full grouped structure; the behavior adds toggle controls and manages collapse state.

2. Sidebar Search / Filter Bar

Priority: High

A text input at the top of the sidebar that filters the visible items in real-time:

[🔍 status:ready priority:high    ]

Behavior:

• Typing filters items by matching against ID, title, tags, assignee, and milestone
• Plain text matches fuzzily across all fields (e.g., typing "auth" shows WORK-012 Implement authentication)
• Supports the existing field:value filter syntax for precise filtering (e.g., status:ready, priority:high, tags:css)
• Multiple filters combine with AND logic (same as the {% backlog %} rune)
• Multiple values for the same field combine with OR logic
• Filter clears on Escape
• / keyboard shortcut focuses the filter input from anywhere on the page

Data requirements: Navigation items need additional data-* attributes beyond the current id, status, and label:

• data-tags — comma-separated tag list
• data-priority — priority value (work items)
• data-severity — severity value (bugs)
• data-assignee — assignee value
• data-milestone — milestone value
• data-complexity — complexity value (work items)

These are added during buildNavRegion() (from SPEC-014) so no pipeline changes are needed.

Implementation: A small client-side behavior (~2KB). All data is already present in the DOM — no server round-trip needed. Works in conjunction with collapsible groups (filtering expands matching groups automatically).

3. Enhanced Dashboard

Priority: Medium

Improve the auto-generated dashboard to give better at-a-glance project health:

Progress summary (top of dashboard):

35 work items: 12 done · 3 in progress · 7 ready · 2 blocked · 11 draft
8 bugs: 2 fixed · 1 in progress · 3 confirmed · 2 reported

A simple text-based summary — no charts or visualizations. Counts per status, color-coded with the existing status palette.

Blocked items callout: A dedicated section with red/warning styling that surfaces all items with status: blocked. These need attention first and shouldn't be buried in the general backlog. Each blocked item shows its title, ID, and — if detectable from content — what it's blocked on.

Per-milestone scoping: The dashboard groups work items and bugs by milestone when multiple milestones exist:

v0.5.0 (active) — 6 of 14 done
  ▸ In Progress (2)
  ▸ Ready (4)
  ▸ Done (6)

v0.6.0 (planning) — 0 of 8 done
  ▸ Ready (3)
  ▸ Draft (5)

Unassigned — 13 items
  ▸ ...

When only one milestone exists (or none), the current flat layout is used.

Recent activity: A section showing items whose status changed recently, detected via file modification time (mtime). Shows the last 10 changes with their old → new status transition if detectable.

4. Tag-Based Cross-Cutting Views

Priority: Medium

Auto-generated pages that group entities by tag, assignee, or milestone — accessible from a "Views" section in the sidebar:

Views
  By tag: runes (8) · css (5) · pipeline (3)
  By assignee: unassigned (12) · claude (8)
  By milestone: v0.5 (9) · v0.6 (4)

Each view page uses the existing {% backlog %} rune with appropriate filters. Pages are generated during the aggregate pipeline phase (same as the dashboard), so they require no manual authoring.

View pages are generated only when useful:

• "By tag" appears when there are 3+ distinct tags
• "By assignee" appears when there are 2+ distinct assignees
• "By milestone" appears when there are 2+ milestones

5. Keyboard Navigation

Priority: Low

Keyboard shortcuts for fast navigation in the plan site:

Implementation: A keyboard-nav behavior. The sidebar items get tabindex attributes and the behavior manages a virtual focus cursor. Visual focus indicator matches the existing active link style.

6. Dependency Visualization

Priority: Low

Work items and bugs reference each other by ID in their content. Surface these relationships explicitly:

On each entity page, a "Relationships" section (auto-injected, not authored):

Blocked by: WORK-003 (in-progress), WORK-007 (done)
Blocks: WORK-012, WORK-015
Related: SPEC-005, ADR-003

Each reference is a live link. Status badges are shown inline so you can see at a glance whether blockers are resolved.

Detection: During the register pipeline phase, scan entity content for ID references matching (WORK|SPEC|BUG|ADR)-\d+ patterns. Build a bidirectional relationship index in the EntityRegistry. During postProcess, inject the relationships section into each entity page.

In the sidebar (optional, low priority): Blocked items could show a small indicator (e.g., a red dot) when their blockers are unresolved.

Implementation Phases

These features are independent and can be implemented in any order, but the suggested sequencing maximizes value:

Phase 1 (immediate post-SPEC-014):

• Collapsible status groups
• Sidebar search/filter
• These two features address the primary scalability pain point

Phase 2:

• Enhanced dashboard
• Tag-based views
• These improve project-level visibility

Phase 3:

• Keyboard navigation
• Dependency visualization
• These are power-user and planning features

Scope Boundaries

In scope: UX design and behavior for the plan site rendered by plan serve and plan build.

Out of scope:

• Embedding plan content in a regular refrakt site (separate concern)
• Real-time collaboration or multi-user features
• Charting, Gantt diagrams, or complex visualizations
• Plan content editing from the browser (the plan site is read-only; editing happens in files)
• Mobile-specific UI (responsive is sufficient)