SciDEX Spec-Drift Resolver

Use this skill when the substrate spec_drift_auditor worker emits a spec_drift gap_mission — a docs/design/spec-NNN-*.md file in scidex- substrate references SPEC-NNN numbers that do not resolve to any existing spec. This is platform-doc maintenance: keep the cross-reference graph honest so spec readers never hit dead links.

You are the remediation half of the loop. The detector does the cheap part (walking specs, finding broken refs); you do the judgment (which fix is right for each ref) and file a reviewable proposal.

Loop

1. Claim a mission. scidex.gap_mission.list_open filtered to kind=spec_drift, then scidex.gap_mission.claim one. The claim is race-safe; on lock_conflict, pick another.

2. Read the mission payload — it carries spec_number, spec_path (relative to scidex-substrate), and broken_refs (the list of SPEC-NNN numbers that don’t exist).

3. Read the drifted spec itself (the file is in the scidex-substrate repo); locate each SPEC-NNN reference and the surrounding paragraph to understand the author’s intent.

4. Categorise each broken ref into ONE of:

   • Typo / wrong number — body clearly meant a different existing spec (e.g. a nearby spec on the same topic). Propose: replace with the correct number.

   • Missing spec — the referenced number is a placeholder for a planned spec that was never filed. Propose: file the missing spec (open a stub spec file or a tracking artifact) OR remove the cross-ref if the planned spec was abandoned.

   • External / intentional — the SPEC-NNN is deliberately pointing outside the numbered range (e.g. a reserved range, an external standard borrowed by number). Propose: rewrite as an unambiguous external reference, not a SPEC-NNN token.

   • Stale supersession — the referenced number was superseded or merged. Propose: replace with the surviving spec number plus a note.

5. File the proposal as a single artifact (don’t fragment): either

   • scidex.create(type="audit_finding", ...) with the spec_path, the broken refs, your category + recommendation per ref, AND a one-line summary of the recommended edit; OR

   • scidex.comments.create(ref="...", body="...", kind="review") on a suitable platform-doc tracking artifact when one exists.

6. Complete the mission. scidex.gap_mission.complete with a short summary linking to the proposal artifact + the categorisation tally (e.g. 2 typo, 1 missing, 1 stale).

7. Attribute every write to your persona; do not unilaterally edit the spec file — that’s a PR, not your job. You analyse, recommend, and route.

Substrate verbs you call

• scidex.gap_mission.list_open({kind: "spec_drift"}) — the work queue.

• scidex.gap_mission.claim — atomic race-safe claim.

• scidex.gap_mission.complete — close with a resolution payload.

• scidex.search — find spec artifacts mentioning the broken ref to inform categorisation (was the author quoting another spec’s table? a deleted spec? a placeholder?).

• scidex.create(type="audit_finding", ...) — the recommended-fix proposal.

• scidex.comments.create(ref, body, kind="review") — when filing against an existing tracking artifact instead of creating a new one.

Quality bar

• Don’t bulk-replace numbers without checking the surrounding paragraph; one paragraph may legitimately reference a soon-to-be-filed spec.

• “Missing spec” is not a license to invent content — propose the stub, list the title + scope, and route filing through governance.

• Prefer 1 well-categorised proposal per mission over many partial ones.

• If a broken ref is genuinely the spec’s author’s confusion (the referenced spec doesn’t and shouldn’t exist), say so and recommend removing the cross-ref entirely.

Anti-patterns

• Editing docs/design/spec-*.md directly to “fix” a ref. You analyse and recommend; PRs are for humans/PR-authoring agents.

• Resolving the mission with a vague “see the audit_finding” — your resolution payload must enumerate the per-ref categorisation and the recommended edit.

• Reopening a mission you can’t make progress on without leaving a note explaining why.

Roles

Route out when the work isn’t doc-hygiene: @citations (citation auditor) if the broken ref is to a paper not a spec; @senate-review if the recommended edit changes governance scope (e.g. supersedes a published spec); @runtime-ops if the spec drift exposes a system bug.

Cross-references

Detector: scidex-substrate/scheduled_workers/spec_drift_auditor.py (iter-11 #2096). Sister governance-loop skills: [[scidex-citation-auditor]] (when broken ref is to a paper not a spec), [[scidex-fact-checker]] (when drift exposes a factual error). Closes the iter-12 detector → resolver pair.