name	tracker-bridge-materials
description	Use when working in the tracker-bridge-materials repository on typed_ref canonicalization, tracker integration, issue_cache/entity_link/sync_event behavior, context rebuild flows, docs consistency, acceptance checks, or test updates. Trigger when the user mentions tracker-bridge-materials, this repo's README/BLUEPRINT/GUARDRAILS/RUNBOOK, or asks for review/fixes inside this repository.

Tracker Bridge Materials Skill

Treat this skill as the default operating guide for work inside the tracker-bridge-materials repository.

Start here

Confirm you are in the repository root.
- Look for README.md, README-human.md, BLUEPRINT.md, and pyproject.toml.
Read the repo's agent-first guide first: README.md.
Read BLUEPRINT.md and docs/kv-priority-roadmap/ before changing implementation.
Read GUARDRAILS.md before changing architecture, refs, or persistence behavior.

Operating rules

Preserve the execution order P1 -> P2 -> P3 -> P4.
Emit canonical typed_ref values in 4 segments only.
Allow legacy 3-segment refs only for read compatibility.
Keep tracker-bridge as a helper layer; do not make external trackers the source of truth.
Keep tracker connection boundaries intact. If a lookup can be ambiguous across connections, resolve by connection-specific metadata or fail explicitly.
Update docs when you change typed_ref, schema, sync semantics, or acceptance expectations.

Common task routing

Read references/repo-map.md when you need file-level guidance.

For typed_ref changes: inspect tracker_bridge/refs.py, tracker_bridge/models.py, tests/test_refs.py, and docs/kv-priority-roadmap/01-typed-ref-unification.md.
For tracker integration fixes: inspect tracker_bridge/services/tracker_integration_service.py, tracker_bridge/repositories/issue_cache.py, tracker_bridge/repositories/sync_event.py, tracker_bridge/services/issue_service.py, and the service/repository tests.
For context rebuild or resolver work: inspect tracker_bridge/services/context_rebuild_service.py, tracker_bridge/resolver/, tests/test_context_rebuild.py, and tests/test_resolver*.py.
For acceptance or inspection work: compare code and tests against docs/tracker-bridge-requirements.md, docs/tracker-bridge-sqlite-spec.md, BLUEPRINT.md, and EVALUATION.md.

Verification baseline

Run the standard checks after meaningful changes:

ruff check .
mypy tracker_bridge tests
pytest
pytest --cov

For review requests, prioritize concrete findings first: broken behavior, regression risk, missing tests, and requirement mismatches.

Tracker Bridge Materials Skill

Treat this skill as the default operating guide for work inside the tracker-bridge-materials repository.

Start here

Confirm you are in the repository root.

Look for README.md, README-human.md, BLUEPRINT.md, and pyproject.toml.

Read the repo's agent-first guide first: README.md.

Read BLUEPRINT.md and docs/kv-priority-roadmap/ before changing implementation.

Read GUARDRAILS.md before changing architecture, refs, or persistence behavior.

Operating rules

Preserve the execution order P1 -> P2 -> P3 -> P4.

Emit canonical typed_ref values in 4 segments only.

Allow legacy 3-segment refs only for read compatibility.

Keep tracker-bridge as a helper layer; do not make external trackers the source of truth.

Keep tracker connection boundaries intact. If a lookup can be ambiguous across connections, resolve by connection-specific metadata or fail explicitly.

Update docs when you change typed_ref, schema, sync semantics, or acceptance expectations.

Common task routing

Read references/repo-map.md when you need file-level guidance.

For typed_ref changes: inspect tracker_bridge/refs.py, tracker_bridge/models.py, tests/test_refs.py, and docs/kv-priority-roadmap/01-typed-ref-unification.md.

For tracker integration fixes: inspect tracker_bridge/services/tracker_integration_service.py, tracker_bridge/repositories/issue_cache.py, tracker_bridge/repositories/sync_event.py, tracker_bridge/services/issue_service.py, and the service/repository tests.

For context rebuild or resolver work: inspect tracker_bridge/services/context_rebuild_service.py, tracker_bridge/resolver/, tests/test_context_rebuild.py, and tests/test_resolver*.py.

For acceptance or inspection work: compare code and tests against docs/tracker-bridge-requirements.md, docs/tracker-bridge-sqlite-spec.md, BLUEPRINT.md, and EVALUATION.md.

Verification baseline

Run the standard checks after meaningful changes:

ruff check . mypy tracker_bridge tests pytest pytest --cov

For review requests, prioritize concrete findings first: broken behavior, regression risk, missing tests, and requirement mismatches.