spec

Artifacts Page Improvements

2026-04-04

Artifacts Page Improvements

Exec Summary

*Pending rewrite after problem statement is approved.*

1. Problem Statement and Goal

Problems

1. I can't tell what's relevant without opening every artifact. The artifacts page is a flat list of 24 items. There's no visual signal for whether something is a current draft I need to act on, a completed deliverable, or a stale plan that was superseded months ago. I have to click into each one and read the frontmatter to figure out if it matters right now. That means the page fails at its most basic job: helping me find what I need quickly.

2. I lose time scanning past artifacts that no longer matter. Three artifacts are superseded, one is archived, and several are completed. They sit alongside active drafts with equal visual weight. When I'm looking for the spec I need to review, I'm mentally filtering out noise every time. The page gets worse as more artifacts accumulate because the ratio of current-to-stale keeps dropping.

3. I can't see how artifacts connect to the work they support. Artifacts are created for tasks (a spec for JAM-18, a research brief for JAM-17), but that relationship only exists as a markdown link I manually pasted into a task's Details field. From the artifacts page, there's no way to see which task an artifact belongs to. From a task, there's no structured link back. I end up holding the mapping in my head or searching chat history.

4. Navigating between related artifacts and tasks requires too many steps. If I'm reviewing a task and want to read its spec, I scroll through the Details field looking for a link. If I'm reading an artifact and want to check the task status, I have to go back to the board and find the right card. There's no two-way navigation. This friction compounds when tasks have multiple artifacts (a spec and a research brief) or when an artifact informs multiple tasks.

5. The type system has drifted and the page doesn't help me see that. We decided on two artifact types (spec, research-brief), but the existing collection uses eight different types from before that decision. The page treats all types identically, so there's no prompt to clean up inconsistencies and no way to scan by type.

Goal

The artifacts page should help me answer three questions in under 10 seconds:

  1. What artifacts need my attention right now?
  2. What artifact(s) belong to a specific task, and vice versa?
  3. Where did we land on a past decision? (finding a completed artifact quickly)

2. Success Metric

3. Current State

4. Platform Capabilities

Mission Control already:

What's missing:

5. Community Patterns

Linear's docs section groups by project and shows status. Notion databases let you toggle between views (table, gallery, board). The common pattern for document management in productivity tools: default view hides archived/completed items, with a toggle to show all.

6. Options

Option A: Status Groups + Type Filter (minimal)

Group artifacts by status (Active/Draft, Completed, Archived/Superseded). Add a type filter dropdown (All, Spec, Research Brief). Archived/Superseded collapsed by default.

Pros: Solves the core scanning problem. Low build effort. Cons: No task linkage. No project grouping (depends on JAM-25).

Option B: Option A + Task Linkage

Add a task field to frontmatter. Show the associated task ID (e.g. "JAM-18") as a clickable badge on each artifact card. Add a reverse link on the task detail view.

Pros: Connects artifacts to their context. Two-way navigation. Cons: Requires updating all existing artifact frontmatter. Medium build effort.

Option C: Option B + Smart Default View

Same as B, plus: default view only shows active/draft artifacts. A toggle reveals completed/archived. Pinned artifacts always show at top regardless of status.

Pros: Best scanning experience. Pete sees what matters immediately. Cons: Slightly more UI complexity.

7. Recommendation

Option C. The whole point is making the page scannable. Hiding stale artifacts by default and connecting artifacts to tasks are both necessary for that.

Proposed layout

Header: "Artifacts" title + filter bar

Pinned section (if any pinned artifacts exist):

Active section (default view):

Archived section (hidden by default, revealed by toggle):

Artifact card design

┌─────────────────────────────────────────┐
│ ● Spec                        JAM-18 →  │
│ Workspace Backup & Version Control      │
│ Draft · Updated Apr 3                   │
└─────────────────────────────────────────┘

Frontmatter additions

Add to artifact frontmatter schema:

Data migration

Update existing artifacts to add task field where applicable:

Status normalization

Reduce to 4 statuses (map existing values):

8. Security Considerations

No new security concerns. Artifacts are already readable by anyone with MC access. No new data exposure.

9. Pete's Setup Checklist

None. This is a build task with no external dependencies.

10. Implementation Scope

David builds:

  1. Artifact list component rewrite (components/artifacts/ArtifactList.tsx or equivalent):
  1. Artifact card component (components/artifacts/ArtifactCard.tsx):
  1. Frontmatter parser update:
  1. Data migration script:
  1. Artifact detail view:

11. Validation Criteria

12. Test Plan

Test 1: Default view

Test 2: Archive toggle

Test 3: Type filter

Test 4: Task linkage

Test 5: Card information

13. Category

Tool - UI improvement to existing Mission Control feature

14. Context Loading

15. Guardrails

16. Handoff