Map Orphaned Identifiers

Map Orphaned Identifiers

Build an evidence-backed map of opaque identifiers before deciding whether to keep, explain, replace, or escalate them. This skill inventories and records findings; it does not authorize cleanup edits.

Establish Scope

1. Read every applicable repository instruction and locate current canonical documents, terminology maps, and ownership contracts.
2. Use the user-specified scope. Otherwise inspect maintained prose, comments, test names, help text, and filenames where opaque labels can affect readers. Exclude generated, vendored, cache, and AI-tool-private working artifacts unless repository instructions make them authoritative.
3. Reuse an existing identifier map when one exists. Otherwise prefer docs/notes/orphaned-identifier-map.md, adapting to the repository's established documentation layout.
4. Treat the map as a current decision aid, not a changelog, policy source, or historical archive. Git remains the record of removed rows and completed migrations.

Do not create a commit unless requested. Do not rename machine values or rewrite identifier occurrences as part of mapping unless the user separately requests cleanup.

Discover Candidates

Search with rg for identifier families visible in the scoped corpus, then inspect nearby prose before accepting a match. Candidate shapes include requirement, acceptance, gate, phase, story, and step labels such as US-001, AC-6b, G007, and A1b.

Do not treat every uppercase token, number, test ID, or hyphenated word as a candidate. Exclude ordinary acronyms and well-known domain names. Track occurrences rather than assuming one token has one global meaning: the same spelling can represent different facts in different files or domains.

Record the search boundaries and exclusions so the map does not imply repository-wide completeness when only a subset was inspected.

Recover Meaning

Resolve each candidate from strongest current evidence to historical evidence:

1. Read its current paragraph, section, referenced contract, implementation, and tests.
2. Search all current occurrences and group them by meaning or domain.
3. Use path-specific git blame, git log -S<identifier>, git log -G<pattern>, and git show to recover the introducing requirement and subsequent semantic changes.
4. State the present-day fact as a component, action, invariant, precondition, failure mode, decision, or expected result. Do not merely expand the initials.
5. Cite compact evidence in the map: current file paths and, when history supplied meaning, the relevant commit hash or historical path.

If evidence supports multiple incompatible meanings, split the token into context-specific rows and mark the collision. If a specific occurrence still cannot be resolved, classify it as ambiguous rather than guessing.

Classify Occurrences

Assign an occurrence status and a proposed disposition separately:

• Orphaned: a current reader cannot understand the identifier from the same paragraph or a current canonical source.
• Explained: current prose introduces the meaning locally or points clearly to a maintained definition.
• Machine-consumed: the spelling is a schema value, API or CLI token, artifact field, evidence path segment, externally governed ID, or tested compatibility surface.
• Ambiguous: current and historical evidence cannot select one meaning, or a collision cannot be safely separated.
• Historical-only: the identifier is absent from maintained scope and appears only in Git history or excluded archival material. Do not add historical-only rows unless the user requested historical coverage.

Use one proposed disposition:

• Replace for orphaned prose, headings, comments, docstrings, or help text whose meaning is recoverable.
• Replace + test when the readable identifier is also embedded in assertions, test names, snapshots, or fixtures that must change with it.
• Keep + explain when a current human-facing label remains useful but needs its meaning stated nearby.
• Keep exact for machine-consumed or externally governed spellings. Human-facing prose may still need an adjacent explanation.
• Escalate when ambiguity would make a proposed change unsafe.

Classify per occurrence or domain, not per token. A token may be Keep exact in an evidence path and Replace as an adjective in prose.

Save or Update the Map

Include the following near the top:

• status: inventory only, not policy or a changelog;
• inspected scope and explicit exclusions;
• date or revision inspected;
• definitions of statuses and dispositions.

Use a compact table with these fields, splitting it by identifier family or domain when that improves readability:

For each row:

• make Present-day fact understandable without the identifier;
• list the exact context when the token collides;
• make suggested wording concise and use current repository vocabulary;
• distinguish current surfaces from historical evidence;
• avoid copying whole historical requirements into the map.

When updating an existing map, refresh current occurrences and evidence. Remove rows whose migration is complete unless a current occurrence still needs classification. Do not preserve resolved rows as a completion ledger or add an archive section. Remove the map itself when no actionable or intentionally retained rows remain and no current contract requires it.

Verify and Report

Rescan the declared scope and confirm that every included occurrence is represented by the right context-specific row. Check paths and commit references, review the diff for accidental policy or cleanup edits, and run repository documentation checks when relevant.

Report the saved map path, scope, identifier families, collisions, unresolved ambiguity, and validation performed. State explicitly when the inventory is scoped rather than exhaustive.