PRD Navigation Components
Every PRD is a T-shaped document. Nobody can tell.
Layers
| Layer | What | For |
|---|---|---|
| Spec | Intent + Build + Stories | Engineering handoff |
Problem
Situation: Every active PRD has three layers — prompt-deck (pitch), pictures (pre-flight maps), and spec (build contract). These layers exist in the file system and are linked in the ## Layers block added by content fixes. But the navigation experience is markdown bullets — no visual weight, no spatial orientation, no breadcrumb when you're deep in a spec.
Intention: The T-shape should be visible and navigable. A reader landing on any PRD — index, prompt-deck, pictures, or spec — should immediately know where they are, what other layers exist, and how to move between them. The navigation cost should be zero.
Obstacle: src/pages/priorities/ lives outside Docusaurus's docs/ tree — it gets no auto-generated sidebar or breadcrumb. Fixing navigation requires either moving the tree (breaking change) or building custom components that replicate the spatial awareness Docusaurus provides for free in docs/.
Hardest Thing: The sidebar fix has three options, each with a real cost. Moving priorities/ to docs/ would give full Docusaurus sidebar behavior but requires updating every internal link. Manual sidebars.js config requires ongoing maintenance as PRDs are created or moved. A custom React component duplicates Docusaurus sidebar logic without the ecosystem.
Priorities
- Can a reader see all three layers from the PRD index? — Tab strip with icons, not plain bullets
- Does the reader know where they are on a sub-page? — Breadcrumb: Priorities › Agent Platform › Spec
- Does the sidebar show PRD children? — Full tree for the current PRD without custom code
- Is this zero-maintenance? — New PRDs auto-appear in nav, no config updates required
Scorecard
Priority Score: 288 (Pain 4 × Demand 4 × Edge 3 × Trend 3 × Conversion 2)
| # | Priority (should we?) | Preparedness (can we?) |
|---|---|---|
| 1 | Pain: 4 — dogfood found 4/7 issues are pure navigation gaps | Principles: 4 — T-shape architecture documented, FACT-STAR pattern clear |
| 2 | Demand: 4 — every agent and human reading PRDs hits this | Performance: 2 — no components exist yet, markdown-only today |
| 3 | Edge: 3 — standard web nav pattern, well understood | Platform: 4 — React component library exists, design tokens ready |
| 4 | Trend: 3 — PRD count grows, navigation cost compounds | Protocols: 3 — venture ProposalNavigation is the reference implementation |
| 5 | Conversion: 2 — internal tooling, not customer-facing | Players: 2 — engineering direction needed |
Build Order
| Sprint | What Ships | Acceptance |
|---|---|---|
| N1 | PRDLayerStrip component — renders deck · maps · spec as pill tabs with icons | All three layers visible on every PRD index with visual weight. Click → correct sub-page. |
| N2 | PRDBreadcrumb component — Priorities › [Category] › [PRD Name] › [Sub-page] | Every sub-page shows location. No "where am I?" moment. |
| N3 | Sidebar config for priorities/ — either sidebars.js custom config or docs/ migration | Left sidebar shows PRD children when on a PRD page. Zero manual updates for new PRDs. |
| N4 | Wire both components into all existing PRD pages | Full coverage: every index.jsx and every sub-page index uses the components. |
What Exists
| Component | State | Gap |
|---|---|---|
ProposalNavigation (ventures) | Working | PRD-specific — different back-link, different section structure |
PRDNavigation (prd-project-management-system) | Built (this session) | Only wired to one JSX page — most PRDs are markdown |
Markdown ## Layers blocks | Added (this session) | Plain bullets — no visual weight, no icons |
| Blockquote nav headers on sub-pages | Added (this session) | Markdown only — no breadcrumb hierarchy |
sidebars.js for priorities/ | Missing | src/pages/ gets no sidebar config |
Relationship to Other PRDs
| PRD | What It Contributes |
|---|---|
| Agent Platform | Platform that serves the component — all PRD pages use it |
| Project Management System | First JSX PRD — PRDNavigation component already built there |
Decision: Move vs Config
Three options for the sidebar problem:
| Option | Effort | Maintenance | Risk |
|---|---|---|---|
Move priorities/ → docs/ | High (all links break) | Zero (auto-sidebar) | High |
Custom sidebars.js config | Low (one file) | Medium (update on PRD add) | Low |
React PRDSidebar component | Medium (new component) | Low (data-driven) | Low |
Recommended: sidebars.js custom config for now. Migrate to docs/ if PRD count exceeds 40 and maintenance cost becomes real.
Context
- Priorities Index — The surface this fixes
- Agent Platform — Platform that hosts the components
- Venture ProposalNavigation — Reference implementation
Questions
If the sidebar can show PRD children, does the ## Layers block become redundant?
- Should the tab strip show all possible layers (deck · maps · spec · plan) with greyed-out tabs for layers that don't exist — or only show layers that exist?
- At what PRD count does a custom sidebar config become unmaintainable — and what's the trigger to migrate
priorities/todocs/? - If the breadcrumb shows the path, does the blockquote nav header at the top of sub-pages become redundant?