# Map Orphaned Identifiers > Inventory opaque temporary identifiers such as G007, US-001, AC-6b, gate and phase codes, or short labels such as A1b; recover their present-day meanings from the working tree and Git history; classify orphaned, explained, machine-consumed, ambiguous, and historical-only occurrences; and save or update a repository-local meaning map. Use when identifiers need evidence-backed clarification before documentation cleanup or migration. Do not use for the cleanup itself when the requested outcome is to delete or rewrite stale guidance. - Skill: `iyoda/map-orphaned-identifiers` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add iyoda/map-orphaned-identifiers` - Raw SKILL.md: https://api.skillmd.com/api/skills/iyoda/map-orphaned-identifiers/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: iyoda (https://skillmd.com/u/iyoda) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/iyoda/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`, `git log -G`, 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: | Identifier / context | Present-day fact | Status | Disposition | Suggested semantic wording | Evidence and current surfaces | | --- | --- | --- | --- | --- | --- | 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.