Feature Docs Navigator

ShipIt has feature docs in docs/NNN-feature-name/plan.md. Each describes how a feature was designed and implemented. Most tasks don't need these — the architecture skills cover cross-cutting patterns. Load a feature doc only when you need implementation details for a specific feature.

How to use

1. Run the index script to get the current list of docs with their status and title:

   bash .agents/skills/docs-navigator/index.sh

2. Find the relevant doc(s) from the output
3. Read its plan.md for design details
4. Check checklist.md if it exists — it tracks remaining work

Status key

• done — implemented and shipped
• in-progress — actively being worked on
• planned — designed but not yet started
• paused — designed but not currently scheduled

Filtering

The index script accepts an optional filter argument to narrow results:

# Show only planned/in-progress docs
bash .agents/skills/docs-navigator/index.sh active

# Show only docs matching a keyword
bash .agents/skills/docs-navigator/index.sh git
bash .agents/skills/docs-navigator/index.sh deploy

Writing docs: folder layout

docs/
  NNN-feature-name/
    requirements.md — What the feature must do, in the human's terms (required for new features)
    plan.md        — How the feature works, key files, patterns
    checklist.md   — Remaining work items or tracking notes
    mockup.html    — Optional UI prototype committed as reference (or mockup.svg / mocks/)

Features are numbered by creation order. Create docs/NNN-new-feature/ for a new one.

docs/NNN-feature/ is this repo's convention, not the docs list's filter. The scan (markdown.ts → findMarkdownFiles) walks the whole workspace and surfaces every .md file — README.md, RELEASING.md, src/server/shipit-docs/*.md, anything nested. The NNN- prefix and the presence of plan.md / checklist.md / an issue: pointer only decide Tracked-vs-Other grouping and newest-first ordering. So treat any markdown you write as user-visible; don't leave scratch notes in .md.

A 100%-complete checklist.md folds its doc into the collapsed Done group; otherwise it shows under Active.

Frontmatter

All three fields are optional; a doc with no frontmatter still appears in the list.

---
issue: planning#306
title: Optional display title
description: One sentence, rendered under the title. No multi-line YAML scalars.
---

issue: resolves against the trackers declared in shipit.yaml. Write the name form (roadmap#SHI-304, planning#42) — it survives a declaration being re-pointed at another repo or team, and it's the form ShipIt itself emits. A backend address also resolves as long as it identifies a declared tracker: a full Linear URL without the title slug (a bare TRACKER-28 is rejected), owner/repo#123, or a GitHub issue URL.

A doc carries exactly one issue: self-pointer. Committed docs may name sibling issue IDs inline as stable identifiers ("blocked on planning#81") but must not record their priority or status — that drifts, and lives in the tracker.

Committed prototypes

When a doc describes UI whose layout is load-bearing (filters, tables, breakpoints), commit the prototype beside plan.md — mockup.html, mockup.svg, or a mocks/ subdir — as a self-contained static artifact: inline CSS/SVG, no build step, diffable. A .png is a supplement, not the source of truth. Link it from plan.md. The present tool's tab is ephemeral; committed mocks are reviewable in PRs.