doc-routing

/doc-routing — Documentation Router

Purpose

The single authoritative skill for deciding "which information goes where" in project documentation. Prevents:

• Duplication between the PRD and feature docs
• Lost context (no designated home for important information)
• Drift between documents
• Ad-hoc decisions about doc structure

Other doc skills (e.g. doc-feature) delegate routing decisions to this skill.

This skill operates on the Source layer of the Source → Presentation model — see docs/DOCUMENTATION_STRATEGY.md (template ships in this repo: templates/DOCUMENTATION_STRATEGY.md.template). Derived/public docs sync from the files routed here.

When to Use

• The user says "document X"
• Before creating/updating any docs in docs/ or .claude/research/
• When reviewing existing documentation
• Whenever the question "where does this go?" comes up
• Automatically before doc-feature

Decision Tree

Information to document
             │
             ▼
    [What does it describe?]
             │
    ┌────────┼────────┬───────────┬──────────┬────────────┬──────────┬──────────┐
    ▼        ▼        ▼           ▼          ▼            ▼          ▼          ▼
 Product    Module   Cross-   External   Non-          Roadmap /  Decision  Glossary /
 (WHY)      (HOW)    module   service    functional    tracker    rationale terminology
    │        │        flow       │       (perf/sec/                  │          │
    ▼        ▼        │          ▼       a11y/i18n)                  ▼          ▼
   PRD    features/  ▼       integrations/  │                      ADR       GLOSSARY
          <module>.md journeys/<name>.md    ▼                    <NNN>.md
                                          NFR.md

Routing Rules

R1-R7: PRD vs Features boundary

#	Rule	File
R1	Module functionality change → update ONLY features/<X>.md	docs/features/<X>.md
R2	Product vision / strategy change → update ONLY the PRD	docs/requirements/product/PRD.md
R3	The PRD covers a module with overview + link only: "See features/<X>.md"	PRD + features
R4	Persona-to-module mapping (JTBD) → features/README.md	docs/features/README.md
R5	New module → FIRST features/<X>.md, THEN a row in the PRD module map	features → PRD
R6	Business rules → docs/requirements/BUSINESS_RULES.md	BUSINESS_RULES.md
R7	Glossary → docs/GLOSSARY.md, references everywhere else	GLOSSARY.md

J1-J5: Journeys (cross-module flows)

#	Rule
J1	A journey = a scenario crossing 2+ modules
J2	Per-module details are links to features/, not duplicates
J3	Journeys are for regularly recurring scenarios, not edge cases
J4	Persona + trigger + outcome are mandatory in frontmatter
J5	features/ do NOT link to journeys (features = blocks, journeys = composition)

J-Gap: when a journey becomes its own module

A journey graduates to a module when:

• It gets a dedicated UI surface (its own page/route)
• The scenario grows its own data model
• It requires persistent state / configuration

Until then — it stays in journeys/.

I1-I4: Integrations (external services)

#	Rule
I1	One external service = one file in docs/integrations/<service>.md
I2	Mandatory frontmatter: status, purpose, auth, used_by, cost_model
I3	Status values: Active, Planned, Deprecated
I4	New integration → create the file BEFORE starting work with the service

N1-N3: NFR (non-functional requirements)

#	Rule
N1	Cross-cutting qualities (perf / sec / a11y / i18n / SLA) → docs/NFR.md
N2	Per-feature NFR → the "Constraints" section of features/<X>.md
N3	Budgets and thresholds must be measurable (number + unit)

D1-D4: Deprecation

#	Rule
D1	Removing features, routes, components → follow docs/processes/deprecation.md
D2	Marking deprecated: frontmatter status: Deprecated, sunset_date: YYYY-MM-DD
D3	Archive the deprecated doc in docs/archive/<year>/<name>.md
D4	Announce in the changelog / user-facing release notes before removal

RT1-RT3: Roadmap traceability

#	Rule
RT1	Roadmap tasks carry columns: issue-tracker ID + Feature doc + Status
RT2	Feature doc frontmatter links to the roadmap via the tracker: issue: [TICKET-123]
RT3	When a tracker issue closes → update status in the roadmap AND in the feature doc

Full Documentation Map

The paths below align with this repo's shipped templates (templates/SSOT_MAPPING.md.template, templates/DOCUMENTATION_STRATEGY.md.template, templates/PITFALLS.md.template, templates/ADR-template.md). Replace/extend with your project's actual map — the tier structure is the durable part.

Tier 1 — Active (the core set)

Area	SSOT	Routing rule
Product vision, why, what	docs/requirements/product/PRD.md	R2
Module-level how	docs/features/<name>.md	R1
Cross-module flows	docs/journeys/<name>.md	J1-J5
External integrations	docs/integrations/<service>.md	I1-I4
Non-functional requirements	docs/NFR.md	N1-N3
Deprecation process	docs/processes/deprecation.md	D1-D4
Roadmap	docs/ROADMAP.md (or quarterly files)	RT1-RT3
API contracts	docs/api/	—
Known API traps	docs/PITFALLS.md	—
Business rules	docs/requirements/BUSINESS_RULES.md	R6
Architecture decisions	docs/architecture/decisions/ADR-NNN-*.md	—
Glossary	docs/GLOSSARY.md	R7
SSOT mapping (navigation)	docs/SSOT_MAPPING.md	—
Doc-layer rules	docs/DOCUMENTATION_STRATEGY.md	—

Tier 2 — Reserve (create when a real pain appears)

Area	Planned location	Creation trigger
Error/empty/loading states taxonomy	design-decisions doc section	When UX inconsistency appears
Testing strategy	docs/TESTING_STRATEGY.md	When coverage needs to grow
Cross-feature invariants	docs/requirements/invariants.md	When consistency rules appear
Data flow between modules	docs/architecture/data-flow.md	Before scaling / event-driven work

Tier 3 — Future (defer until needed)

Area	Planned location	Creation trigger
Monetization / tenancy	docs/product/monetization.md	When paid tiers appear
User-facing release notes	docs/CHANGELOG.md or a docs site	At first external users
Product analytics events	docs/analytics/events.md	When adopting an analytics platform
Customer support / FAQ	docs/support/	When a support function appears
Compliance / privacy audit	docs/compliance/	At legal requirements
A11y / i18n conventions	docs/NFR.md section or separate	When localizing beyond default language
Experiments / feature flags log	docs/experiments/	When adopting A/B tests
Incident runbooks	docs/runbooks/	After first production incidents

Workflow

Use Case 1: The user says "document X"

1. Classify X via the Decision Tree
2. Find the right home in the Tier 1 map
3. If there's a fit → delegate to the appropriate skill (doc-feature, etc.) or write directly
4. If no fit → check Tier 2/3
5. Still no fit → propose a new category (discuss with the user)

Use Case 2: An audit found missing documentation

1. Take the audit task (e.g. "Update PRD")
2. Check via this skill: does that information actually belong in the PRD?
3. Some of it may need to move to other files
4. File a tracker issue if a structural change is needed

Use Case 3: New feature / decision

1. Before writing → run it through the Decision Tree
2. Split: what goes in the feature doc, what in a journey, what in NFR, what in an ADR
3. Create all artifacts at once (atomically)

Integration with other skills

Skill	Relationship
doc-feature	Invoked AFTER doc-routing when the decision = feature doc
deep-research	Research reports land in .claude/research/ — outside this map

Output Format

When the user asks "where do I document X":

## Documentation Router Decision

**Input:** [what the user wants to document]

**Classification:** [Product vision / Module / Journey / Integration / NFR / etc.]

**Routing decision:**

- Target: `docs/<path>/<file>.md`
- Rule applied: [R1/J1/I1/etc.]
- Section within file: [which section]

**Rationale:** [1-2 sentences on why here]

**Related updates needed:**

- [ ] Update `docs/SSOT_MAPPING.md` if this is a new knowledge area
- [ ] Cross-link in related files
- [ ] Frontmatter updates

**Delegation:** [next skill — doc-feature, or direct write]

Maintenance

• Update this skill when:
  • The doc architecture changes
  • A category is promoted from Tier 2/3 to Tier 1
  • A new routing rule is added
• Periodically (e.g. quarterly) — verify the routing rules are still being followed