docs/ Taxonomy Proposal — 2026-06-10

Date: 2026-06-10 UTC Author: software-architect Parent card: #2438 Status: proposal — operator review required before any file moves

1. Problem statement

The docs/ tree has 44 top-level directories and ~1,321 files. Many directories are near-synonyms (docs/sprint/, docs/sprint-plans/, docs/sprints/) or satellites that predate the canonical location (docs/runbooks/ vs docs/ops/runbooks/). There is no front-door landing page. Design artifacts (docs/design/, docs/ux/, docs/ux-mockups/) are split across three trees that serve the same author (ux-polisher). Business-legal research lives in two separate directories (docs/business/, docs/business-legal/).

The goal of this taxonomy is a structure a new agent or contractor can navigate in under 60 seconds.

2. Proposed top-level structure

docs/
├── README.md                    ← front-door landing page (new)
├── architecture/                ← unchanged; this is working
│   ├── adr/                     ← ADR number collision fix needed (see §6)
│   └── ...
├── design/                      ← merged ux/ + ux-mockups/ + current design/ 
│   └── (all ux-polisher artifacts)
├── ops/                         ← unchanged; canonical ops home
│   ├── runbooks/                ← absorbs docs/runbooks/ orphans
│   └── ...
├── security/                    ← unchanged; absorbs docs/secrets/ content
├── business/                    ← merged docs/business/ + docs/business-legal/
│   ├── legal/                   ← existing subdir
│   ├── finance/                 ← absorbs docs/finance/, docs/dev/chart-of-accounts.md
│   └── ...
├── customer/                    ← unchanged; public docs source
├── legal/                       ← unchanged; GDPR/compliance/DPA artifacts
├── data-science/                ← unchanged
├── detections/                  ← unchanged; detection rule catalogue
├── agents/                      ← unchanged; agent runbook docs
├── templates/                   ← unchanged
├── sdlc/                        ← expanded to absorb docs/dev/ (minus chart-of-accounts)
├── qa/                          ← unchanged
├── research/                    ← unchanged
├── release_notes/               ← unchanged; absorbs root-level release note dupes
├── marketing/                   ← unchanged
├── incidents/                   ← CONSOLIDATED from docs/incidents/ + docs/ops/incidents/
│                                   (pick one; ops/incidents/ is canonical)
└── _drafts/                     ← new: personal-scratch, WIP, and orphaned docs

Directories removed by consolidation:

3. Front-door landing page

Create docs/README.md with:

1. What lives here — one paragraph.
2. Quick navigation table — each top-level directory, one-line description, link to its own README.
3. Surface map — link to docs/architecture/cloudflare-pages-projects.md for the CF Pages surface inventory.
4. Runbook index — link to docs/ops/runbooks/README.md.
5. ADR index — link to docs/architecture/adr/ and note the number-collision repair status.

4. Personal-scratch / WIP docs

All of the following go into docs/_drafts/:

• Agent context dumps (business/memory/project_sentiment_roadmap_shape123.md)
• Single-day morning briefs (morning-brief/2026-06-02.md)
• Stale sprint dispatch plans older than 90 days
• claude_research_prompt.md
• SUMMARY.md (if it proves to be a gitbook artifact)
• Groomer pass logs older than 60 days

Retention policy for _drafts/: No file moves from _drafts/ to a permanent location without operator acknowledgment. Files in _drafts/ are excluded from the internal-docs.raxx.app build and from any search index.

5. Naming conventions

Date prefixes

• Architecture design docs (docs/architecture/*.md): no date prefix unless the doc is an in-flight triage/analysis artifact. Canonical designs are timeless; date them only when they represent a point-in-time snapshot.
• Ops artifacts (QA reports, SRE reports, retros, triage): always date-prefixed, YYYY-MM-DD-slug.md.
• Business docs: date-prefix when the doc records a time-specific action or outreach; no prefix for evergreen references (entity-structure.md, ein-and-tax-ids.md).
• Design artifacts: follow ux-polisher convention (topic-slug with date if a snapshot).

Slug conventions

• Lowercase, hyphen-separated.
• Service names use their codenames: raptor, antlers, queue, velvet.
• No underscores in filenames (existing release_notes/ and release_notes_template.md are grandfathered).

ADR numbering

ADR numbers MUST be globally unique across docs/architecture/adr/. The current state has 13 collisions. Fix: the second file at each duplicate number is renumbered to the next available slot. A docs/architecture/adr/INDEX.md is added listing all ADRs in numerical order with one-line summaries. See §6.

6. ADR number collision repair plan

13 pairs of ADRs share a number. The correct fix is to assign the second file at each collision to the next unused number, then update all internal cross-references. This is a discrete sub-card (not part of the taxonomy rename pass) because it requires a grep pass across all files that reference these ADRs by number.

Missing ADR numbers in the current sequence (gaps): 0090, 0092, 0097. The 13 colliding second-files should be renumbered starting from the next available number above 0114 (current highest is 0114).

7. internal-docs.raxx.app build scope

The scripts/build-internal-docs.py builder (or its successor) should have an explicit allowlist of directories to include in the site build, not an exclusion list. Proposed allowlist:

docs/architecture/
docs/ops/
docs/security/
docs/agents/
docs/templates/
docs/sdlc/
docs/data-science/
docs/detections/
docs/customer/         # public content, included for internal cross-reference

Excluded from build:

docs/business/         # business-confidential
docs/legal/            # legal-confidential
docs/design/           # static assets, not prose
docs/_drafts/          # explicitly excluded
docs/release_notes/    # served from GitHub Releases, not internal docs

This allowlist should be a YAML config file (scripts/build-internal-docs.yaml) rather than hardcoded in the builder, so adding a new directory is a one-line edit without touching the builder.

8. Open questions for operator decision

Before any file moves are executed, the following need a decision:

1. docs/design/ vs docs/ux/ — The ux-polisher has been creating artifacts in both docs/design/ (older) and docs/ux/ (newer). Which name wins? Recommendation: keep docs/design/; it has far more content and a clearer name.

2. docs/business-legal/ content — These 18 files predate docs/business/ being the canonical location. Are they safe to move into docs/business/? Operator confirmation needed since they include formation records and attorney correspondence.

3. internal-docs.raxx.app build tool — The current builder is a custom Python script. ADR-0088 deferred a Docusaurus migration. Should the taxonomy cleanup be coupled with a builder upgrade, or separate? Recommendation: separate — taxonomy first, tooling later.

4. docs/data-science/ scope — This directory has notebooks, reference implementations, and strategy briefs. Should reference-impl Python files live in docs/ or move to a dedicated research/ tree outside docs? No strong recommendation; flagged for operator.