check-refs

When to use

Use this skill when:

• A skill, rule, command, guideline, or context has been renamed or deleted
• Linking a newly added artifact from elsewhere in src/
• Preparing a PR that touches cross-references between agent artifacts
• CI's check-refs job failed and the broken reference needs to be located

Do NOT use when:

• Only the body of a single file changed and no names or paths were touched
• Checking frontmatter shape or required sections — use lint-skills instead
• Verifying condensed vs uncondensed pairs — use bash scripts/condense.sh --check instead

Procedure

1. Inspect the scope of recent changes

Identify whether any artifact was renamed, moved, or removed since the last clean run. Cross-reference checks are relevant only when names or paths shift; pure body edits cannot break references.

2. Dispatch via the runtime layer

Invoke the skill through the runtime dispatcher so the execution: block in this skill's frontmatter governs the call:

./scripts-run src/scripts/runtime_dispatcher run --skill check-refs

The dispatcher resolves the request, the shell handler runs ./scripts-run src/scripts/check_references, captures stdout/stderr, and returns a typed ExecutionResult.

3. Verify the result

Check the returned ExecutionResult:

• exit_code: 0 → all cross-references resolve
• exit_code: 1 → at least one broken reference — read stdout for file, line, and the offending ref, then fix the source or update the target
• status: timeout → the checker exceeded timeout_seconds — investigate
• status: error → runner or script missing — confirm ./scripts-run and src/scripts/check_references.ts are available at the repository root

Output format

1. One-line summary: success | failure | timeout | error, exit code, duration in milliseconds
2. Count of broken references found, if any
3. First 10 broken references with file:line → missing-target
4. Next action: fix references, re-run the skill, or surface stdout for review

Gotchas

• The checker is read-only — it never rewrites references, so a clean run after a fix must be produced by re-invoking the skill, not by assumption
• Running outside the agent-config repo root makes the checker inspect zero files and report a false pass
• Relative links inside comments or fenced code blocks may still be parsed as references depending on the checker's current rules; do not suppress a broken ref without confirming it is a genuine false positive

Do NOT

• Do NOT invoke src/scripts/check_references.ts directly when the intent is to verify the runtime path — always go through the dispatcher so the ExecutionResult is produced and inspectable
• Do NOT raise timeout_seconds to mask a slowdown — investigate which part of the tree grew large enough to push past 60 seconds
• Do NOT add piping or redirection to command — the handler uses shell=False and will refuse anything outside pure argv form