.agents/skills/akinator/references/akinator-contextify.md

<!--
DO NOT EDIT BY HAND.
Installed from the Akinator plugin - a station reference of its one skill (akinator-contextify).
No generator is named by path: this file travels into repositories
that do not have one, where naming it would be a false claim.
To update: reinstall Akinator, or regenerate inside an Akinator
checkout. Local edits here are replaced either way.
-->
# Akinator Contextify - station 9

> **Station reference** of [the one Akinator skill](../SKILL.md). Load when: a change alters a structural fact about the system - ownership, module boundaries, routes, ports, events, permissions, environment variables, dependencies or data flow. Updates the structural map and, wherever the fact is extractable from the tree, builds the extractor so the map regenerates instead of drifting.

Structural facts are the ones that rot fastest and hurt most: the route list that
is missing three routes, the ownership map naming someone who left, the event
topology that predates the queue migration. They rot because they are written by
hand and changed by code.

The fix: **generated beats written.** If a fact can be extracted from the tree,
extract it. Hand-written maps are a fallback, and they carry a review trigger.

## When to use

The change altered any of:

- Module ownership or boundaries.
- Routes, endpoints, RPC methods, CLI commands.
- Ports, hosts, service topology.
- Events published or consumed; queues, topics, subscriptions.
- Permissions, roles, scopes, entitlement checks.
- Environment variables and configuration keys.
- Dependencies between services or packages.
- Data flow, storage locations, retention.

## When NOT to use

- For narrative or reasoning. That is `docs/`. Context maps are facts, not prose.
- For a fact that is already generated by an existing extractor - just regenerate.
- For a business rule. That is `docs/business/`, even if it looks tabular.

## Procedure

### 1. Decide: extractable or not

Ask whether the fact is derivable from the tree by a script. Most structural
facts are:

| Fact | Usually extractable from |
|---|---|
| Routes | the router definitions / decorators / framework manifest |
| Env vars | the config module, schema, or a grep of the accessor |
| Events | publish and subscribe call sites |
| Permissions | the permission constants and their guard call sites |
| Ports and services | compose files, manifests, deployment config |
| Dependencies | package manifests, import graph |
| Ownership | codeowners, directory conventions |

If it is extractable, go to step 2. If it genuinely is not - conceptual grouping,
"which of these is the source of truth", human ownership intent - go to step 3.

### 2. Build or update the extractor

- If an extractor exists, run it and commit the regenerated map.
- If none exists, **write one in this batch**. This is the single highest-leverage
  action available at this station: one extractor removes an entire category of
  future drift.

The extractor:
- Lives in the repo's scripts location, matching existing conventions.
- Writes a map with a **generated-file banner** warning against hand edits and
  saying how to get a correct copy. For a map that stays in this repository,
  that means naming the extractor by path, because the reader can run it. For an
  artifact that is **installed into other repositories**, name no file at all -
  give its origin and how to refresh it instead, because a path that resolves
  here is a false claim wherever the file lands.
- Is deterministic - same tree, byte-identical output - so drift is detectable by
  regenerate-and-diff.
- Is runnable in CI as a drift check: regenerate, diff, fail if different.

Machine-readable derived facts also go to `.ai/` manifests where the repo has
that layer. Those are generated only; a hand-edited `.ai/` file is a coverage
failure.

### 3. Hand-written maps: carry a review trigger

When a map cannot be generated, it states, at the top:

- **Scope** - what this map covers and what it does not.
- **Regenerate or review when** - the concrete event that makes it stale
  ("review when a service is added or removed", "review when a new permission
  constant is defined").
- **Last verified** - an absolute date and against what.

A hand-written map without a review trigger is a future critical finding.

### 4. Verify against the tree

For every map you touched, spot-check that what it asserts is true right now.
Generated maps are true by construction; hand-written ones must be checked.

### 5. Index and sync

Every map is reachable from the context index and reflected in the routers
(`akinator-index-sync`, `akinator-router-sync`).

## Failure modes and pitfalls

- **Writing the map by hand when an extractor was possible.** You have created
  the next stale doc. The extractor usually costs less than the map.
- **A non-deterministic extractor.** Unordered output, timestamps or absolute
  paths make every regeneration a diff, so the drift check gets disabled and the
  drift returns.
- **No generated-file banner.** Someone will hand-edit it, and the next
  regeneration will silently delete their work.
- **Hand-editing a generated file.** Fix the extractor, not its output.
- **Maps that duplicate prose docs.** The map holds the facts; the doc links to
  the map. Two copies fork.
- **Omitting the review trigger** on a hand-written map.

## Definition of done

- [ ] Every structural fact the change altered is reflected in a map.
- [ ] Extractable facts are extracted; where no extractor existed, one was built
      in this batch.
- [ ] Every generated map carries a banner naming its extractor.
- [ ] Extractors are deterministic and runnable as a CI drift check.
- [ ] Hand-written maps state scope, review trigger and last-verified date.
- [ ] No generated artifact was hand-edited.
- [ ] Every map is reachable from the context index.