chore: epic — worth-it DO-now queue (face pass, pre-pr-review skills, docs reconcile)

[MSIH]

Problem

A 2026-07-24 worth-it triage of all 15 open issues produced three DO-now verdicts (activation / standing-preference / docs-correctness classes); the other 12 are DEFER/SKIP with recorded triggers (labeled worth-it:DEFER/worth-it:SKIP). This epic tracks the DO-now three so the queue is visible and executed in order.

Implementation Plan (ordered)

1. chore(photo-exif): tag people in the photo library (face pass) #217 — face-enrichment pass (activation class; ops run, not a PR)

   • Install face deps in connectors/photo-exif/ (@vladmandic/face-api, @tensorflow/tfjs-node, canvas) + download ssdMobilenetv1/faceLandmark68Net/faceRecognitionNet weights into FACE_MODELS_PATH.
   • Confirm scan drained + caption pass complete (129k captioned, 0 faces_detected as of 2026-07-23), then run node face-worker.js kill-safe in a bounded window; export-thumbnails → suggest-labels → label <id> "<name>" for recognized clusters.
   • Respect wave order scan → caption → face.

2. /pre-pr-review should always recommend new/updated skills + scripts from the change's lessons #257 — /pre-pr-review + /pre-doc-review skills/scripts section (S effort, doc-tooling)

   • Add a required final "Skills & scripts" section (new skill? / update existing? / save script? / none — grounded in the change under review) to .claude/commands/pre-pr-review.md and .claude/commands/pre-doc-review.md.

3. docs: reconcile 03-ob2-design & 05-roadmap with shipped code #122 + docs: document proposed-entities/Candidates surface + fill README & doc-09 interface gaps #222 — docs reconciliation (one docs-only pass, verify-against-code first)

   • docs: reconcile 03-ob2-design & 05-roadmap with shipped code #122: docs/03-ob2-design.md + docs/05-roadmap.md — mark shipped items (OCR, photos, org+worksAt, consolidation, merge_entities), fix stale /ui path + §2.2 schema blocks.
   • docs: document proposed-entities/Candidates surface + fill README & doc-09 interface gaps #222: README.md (proposed-entity tools/endpoints, place/event kinds), docs/09-contacts-ui.md (proposed-entity surface), docs/08-preparing-contacts.md (photos preserved, not dropped).
   • Each child ships as its own issue/branch/PR (this epic only sequences them); /pre-doc-review for the doc PRs, /pre-pr-review for /pre-pr-review should always recommend new/updated skills + scripts from the change's lessons #257.

Acceptance Criteria

• chore(photo-exif): tag people in the photo library (face pass) #217 closed: face pass run, faces_detected populated, ≥1 labeled cluster surfaces in about_entity/search.
• /pre-pr-review should always recommend new/updated skills + scripts from the change's lessons #257 closed: both review skills emit a grounded "Skills & scripts" section.
• docs: reconcile 03-ob2-design & 05-roadmap with shipped code #122 and docs: document proposed-entities/Candidates surface + fill README & doc-09 interface gaps #222 closed: no shipped feature reads as backlog; every named surface verified against code; /pre-doc-review passes.
• Store→recall smoke test green throughout (no runtime/server change from /pre-pr-review should always recommend new/updated skills + scripts from the change's lessons #257/docs: reconcile 03-ob2-design & 05-roadmap with shipped code #122/docs: document proposed-entities/Candidates surface + fill README & doc-09 interface gaps #222).

Out of Scope

• The 12 DEFER/SKIP issues (triggers recorded on each).
• Each child's implementation detail beyond sequencing (each has its own issue body).

---

Worth-it triage 2026-07-24. Children: #217, #257, #122, #222.

[MSIH]

Outcome (2026-07-24)

DO-now queue resolved:

• /pre-pr-review should always recommend new/updated skills + scripts from the change's lessons #257 — merged (PR feat(tooling): require a Skills & scripts section in review skills #265): both review skills now emit a required "Skills & scripts" section.
• docs: reconcile 03-ob2-design & 05-roadmap with shipped code #122 + docs: document proposed-entities/Candidates surface + fill README & doc-09 interface gaps #222 — merged (PR docs: reconcile 03/05/README/08/09 with shipped code #266): docs reconciled with shipped code across README + docs/03/05/08/09.
• chore(photo-exif): tag people in the photo library (face pass) #217 (face pass) — could not activate: @tensorflow/tfjs-node won't build on this box (Node v26 / no VS C++ workload), and the "captions done" premise was false (0 photos captioned=true). Parked worth-it:DEFER; the durable fix is feat(photo-exif): swap face stack from tfjs-node to onnxruntime-node #268 (swap face stack to onnxruntime-node), after which chore(photo-exif): tag people in the photo library (face pass) #217 reactivates once the caption pass has actually run.

Follow-up filed from the work: #267 — pre-pr-review-gate now honors the /pre-doc-review marker (merged PR #269).

Closing the epic — the queue is done; remaining face work lives on #268 → #217.