templates/examples/onboarding-mapping.md

# Akinator onboarding mapping - Nimbus

> Filled example of `templates/onboarding-mapping.md`, written for the fictional
> Nimbus product described in `templates/examples/README.md`. Paths here are
> illustrative and do not exist in this repository.

- **Onboarded:** 2026-08-19
- **Mode:** brownfield (existing knowledge system detected)

## What already existed

| What | Where | Convention observed |
|---|---|---|
| Routers | `CLAUDE.md` (root only) | No per-module routers. No `AGENTS.md`, though two engineers use Codex |
| Rules | `docs/standards/*.md` | Unnumbered, kebab-case filenames, no enforcement sections. Referenced from code comments as `see docs/standards/naming.md` |
| Skills / runbooks | `ops/playbooks/*.md` | No frontmatter. Titles are imperative ("Restart the worker"). Indexed in `ops/README.md` |
| Context maps | none | Structural facts live inside `docs/architecture.md` as prose and are visibly out of date |
| Memory | none | Decisions live in Slack and in commit messages |
| Docs | `docs/`, grouped by owning team (`docs/platform/`, `docs/growth/`) | Not grouped by kind |
| Generated layer | `.ai/manifests/*.json` | Generated by `scripts/gen_manifests.py`, run in CI |
| Enforcement scripts | `scripts/lint_architecture.py` | Runs in CI. Currently enforces import boundaries only |
| Index convention | each directory has `README.md` with a bulleted list, one line each, description after a dash | Consistent across the repo |

## The mapping

| Akinator taxonomy | This repo's home | Adopted or created |
|---|---|---|
| Hard constraints | `docs/standards/` | **adopted** - keeping unnumbered kebab-case names; adding an Enforcement section to each existing file |
| Repeatable procedures | `ops/playbooks/` | **adopted** - adding YAML frontmatter (`name`, `description`) so they are discoverable by both tools; titles stay imperative |
| Structural facts | `context/` | **created** - no existing home. Placed at root to sit beside `docs/` and `ops/`, matching the repo's flat top level |
| Business logic | `docs/business/` | **created** - deliberately by-kind, not by-team, because quota rules are owned jointly and neither team's folder is the honest home |
| Product logic | `docs/product/` | **created** - same reasoning |
| Operational procedure | `ops/playbooks/` | **adopted** - runbooks and skills share a directory here, which works because the frontmatter distinguishes them |
| Decisions | `docs/adr/` | **created** - numbered `NNNN-slug.md`, the one place Akinator's numbering convention was introduced, because there was no prior art to adopt |
| Durable facts | `memory/` | **created** |
| Generated facts | `.ai/manifests/` | **adopted** - new extractors write here and register in `scripts/gen_manifests.py` |
| Agent entry points | `CLAUDE.md`, `AGENTS.md`, per-module routers | **extended** - `AGENTS.md` created (two engineers use Codex and were reading nothing); per-module routers created for the four workspaces |

## Deliberately not changed

- **Rules stay unnumbered.** Code comments reference them by filename
  (`see docs/standards/naming.md`). Renumbering would break roughly 60
  references for a cosmetic gain.
- **Rules stay in `docs/standards/`, not `rules/`.** Same reason. Akinator's
  `rules/` convention is a default, not a requirement, and the coverage checker
  is configured to look at `docs/standards/`.
- **Docs stay grouped by owning team** for `platform/` and `growth/`. That
  grouping is how people navigate; regrouping by kind would be a taxonomy win
  and a usability loss. Only the genuinely cross-team kinds - business, product,
  adr - are by-kind.
- **`ops/playbooks/` keeps runbooks and skills together.** Splitting them would
  break the existing index and the muscle memory of the on-call rotation.

## Gaps found

| Severity | Gap | Batch |
|---|---|---|
| critical | `docs/architecture.md` describes the `notifications` service, deleted in March. Three onboarding engineers have tried to find it | 1 |
| critical | 4 of 9 standards name no enforcement mechanism; 2 name a lint rule that was removed | 1 |
| high | Pricing and plan limits exist only in the payment provider dashboard and in `src/plans/`. No business-language document anywhere | 2 |
| high | Schema-migration procedure is tribal. The drop-and-rebuild requirement is written nowhere and has cost three incidents | 2 |
| high | No `AGENTS.md`. Codex users start every session with no context at all | 3 |
| medium | 12 of 19 playbooks are unreachable from `ops/README.md` | 3 |
| medium | Structural facts in `docs/architecture.md` cannot be regenerated; no extractors exist | 4 |
| low | No memory layer; decisions are in Slack | 4 |

## Newcomer test

The five most common change types in this repo, tested with a fresh-context
agent given only the knowledge layer.

| Change type | Before | After |
|---|---|---|
| Add an API endpoint | **fail** - no routing or permission convention documented anywhere | pass |
| Change a plan limit | **fail** - agent edited `src/plans/pro.ts` and did not know the dashboard also holds a value | pass |
| Add a database migration | **fail** - agent restarted containers instead of rebuilding; produced a confident, wrong diagnosis | pass |
| Debug a stuck export | **fail** - no runbook reachable; the relevant playbook existed but was unindexed | pass |
| Add a background job | partial - the playbook existed and was found, but retry semantics were undocumented | pass |

Re-run scheduled for 2026-11-19, or after any batch that touches the routers.

## Standing behavior

From 2026-08-19, every change in Nimbus runs the Akinator loop. Stations 6-11
use the homes in the mapping table above - `docs/standards/` for rules,
`ops/playbooks/` for skills and runbooks - **not** Akinator's defaults.