feat: add reconcile-references skill to sync CLAUDE.md imports

[gsdevme]

Summary

Adds a project skill at .claude/skills/reconcile-references/SKILL.md, invocable as /reconcile-references from a Claude Code session inside this repo. It reconciles the repo's topic files with the @import lines in ~/.claude/CLAUDE.md:

• Topic files are root-level *.md excluding README.md and CLAUDE.md (repo docs, never imported).
• Missing imports are appended to the existing import block using literal absolute paths (@-imports don't expand ~/$HOME). Adding is treated as always safe.
• Stale imports are investigated via git before anything is touched: a file that exists on another branch is reported as branch drift and left alone; a file gone from every branch has its import removal proposed, but only applied after user confirmation — never silently.
• Out-of-scope imports (anything not pointing into this repo, e.g. an @RTK.md alongside the block) are never added, edited, or removed.

The README's "Adding a new topic" section now points at the skill, since forgetting step 2 (adding the import line) is exactly the drift it exists to catch.

Motivation

The docs require every topic file to be @-imported from ~/.claude/CLAUDE.md, but nothing enforced it — new topic files can silently never load, and imports can dangle after renames, deletions, or when a topic only exists on a feature branch.

Test plan

Tested against a sandboxed fixture (fake $HOME with its own git repo) containing all five cases: two unimported topic files, an import for a file existing only on a side branch, an import for a file deleted from every branch, and an unrelated non-repo import.

• Baseline agent without the skill silently removed the stale import and self-reported uncertainty about whether repo docs count as topics.
• With the skill, the agent added exactly the two missing imports (absolute paths, block preserved), identified the branch-drift import and named the branch, deferred the true-deletion removal for confirmation, and left the non-repo import and repo docs untouched.

🤖 Generated with Claude Code