# Web source recovery prompt

Repair `[web:NNN]` tag ↔ mapping consistency when lint fails or the mapping file is incomplete.

ADR: [docs/adr/0011-web-source-tags-with-central-mapping.md](../../docs/adr/0011-web-source-tags-with-central-mapping.md).
Rules: [rules/15-web-source-tags.md](../../rules/15-web-source-tags.md).

## When to run

- `python scripts/check_web_source_tags.py` reports **unmapped tags**
- Mapping file was lost, corrupted, or partially edited
- CI `workflow-docs:contract` failed on web source tag check

Do **not** use this task to bulk-convert legacy inline URLs in Accepted ADRs (soft adoption).

## Hard rules

1. **Propose only** — add entries under `## Proposed (recovery)` in `docs/web-source-mapping.md`; never commit without human confirmation.
2. **Do not invent tags** — only recover tags already present in scoped docs.
3. **Canonical first** — first URL bullet is canonical; alternates are optional.
4. **Preserve tag IDs** — use the existing `web:NNN` from the doc; do not renumber.
5. **Re-run lint** after moving proposals into editorial sections and before commit.

## Steps

1. Run `python scripts/check_web_source_tags.py` and capture unmapped tag IDs and file locations.
2. For each unmapped `[web:NNN]`:
   - Open the citing file; read the surrounding paragraph (±3 lines or enclosing section).
   - Draft a human-readable label from context.
   - Search the web for the canonical URL (prefer official docs, specs, primary vendor pages).
   - Add under `## Proposed (recovery)`:

     ```markdown
     ### web:NNN — Proposed label (recovery — verify)
     - https://canonical.example/primary
     ```

3. Summarize proposals for the operator: tag, label, URL, citing files, confidence (high/medium/low).
4. Wait for confirmation. On approval:
   - Move entries into the appropriate editorial section (remove `(recovery — verify)` suffix from label).
   - Delete empty `## Proposed (recovery)` section if no entries remain.
   - Re-run `python scripts/check_web_source_tags.py`.
5. Commit mapping fixes with `docs(web-sources): Recover mapping for [web:NNN]` (or batch message).

## Orphan entries

If lint reports **orphan mapping entries** (mapped but unused), recovery does not auto-fix these. Either:

- add the tag to the appropriate doc, or
- remove the unused mapping entry after confirming it is obsolete.

## Out of scope

- HTTP link health checks (404 probing) — separate follow-up
- Automatic commit or CI auto-repair without human review
- `[paper:*]` / `[book:*]` recovery — future ADR