codebase-indexing

name	codebase-indexing
compatibility	polytoken
description	Use when models have changed significantly, after migrations, or when cross-app relationship data in docs/systems/MODEL_MAP.md seems stale. Also use when you can't find how systems connect and need to regenerate the model map.

Codebase Indexing

Overview

Regenerate the auto-generated model relationship map that prevents expensive codebase searches. The map lives at docs/systems/MODEL_MAP.md and contains FK relationships, reverse relations, and service function signatures for every Django app.

When to Regenerate

• After adding/removing models or foreign keys
• After running migrations that change relationships
• When MODEL_MAP.md data doesn't match what you find in source
• When a new app is added to the project

How to Regenerate

uv run python tools/introspect_models.py > docs/systems/MODEL_MAP.md

The script (tools/introspect_models.py) introspects all Django apps and outputs:

• Every model's foreign keys with target app.Model and type (FK/OneToOne/M2M)
• Reverse relations showing what other models point to each model
• Public service function signatures from each app's services.py

Adding New Apps

If a new Django app is created, add its label to the TARGET_APPS list in tools/introspect_models.py.

Resolving a Rebase/Merge Conflict in MODEL_MAP.md

docs/systems/MODEL_MAP.md is regenerated by many PRs, so it collides on nearly every rebase onto a moved main. Don't hand-merge the conflict markers, and don't try to regenerate while the file still has conflict markers (the tool won't cleanly overwrite a conflicted file).

Clean resolution: git checkout --theirs docs/systems/MODEL_MAP.md (in a rebase, --theirs = the commit being applied = your work) → git add → finish the rebase. Then, on the final clean tree, regenerate once more and git diff --stat it — a correct merge yields zero diff (your regen already matches the merged models). If it shows a diff, commit the fresh regen.

sync-with-main.sh's potentially_impacted_issues for MODEL_MAP are usually just "another open branch touched the same generated file" title-matches, not real semantic conflicts — don't comment on them.

Run the regen command from the worktree root, not cd src && uv run ... — the latter creates a stray src/.venv that breaks the shard-coverage pre-commit hook (see the running-tests skill).

Search Strategy

When looking for how systems connect:

1. First: Grep docs/systems/MODEL_MAP.md for the model or app name
2. Second: Check docs/systems/INDEX.md for concept-to-location mapping
3. Third: Check per-app CLAUDE.md for design rules and patterns
4. Last resort: Read source files directly