Add adornment-pass handoff brief (17JUL26-B)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

17JUL26-B.md

@@ -0,0 +1,114 @@
+# Session Handoff Brief — July 17, 2026 (Session B: The Adornment Pass)
+
+**Read this with:** `17JUL26.md` (the v0.83 release brief, same day, earlier session) and
+`docs/maintenance/2026-07-17-adornment-and-docs-plan.md` (the four-plan working doc this session
+executed — its checkboxes are the authoritative status).
+
+---
+
+## What this session shipped (3 commits on main)
+
+v0.83 shipped its 14 suite skills bare — `SKILL.md` only. This session ran a four-plan program;
+**Plans 1-3 are complete, Plan 4 is queued.**
+
+| Commit | What |
+|---|---|
+| `eb7a51e` | Plan 1+3a: templates + dual-domain examples across 15 skills |
+| `dbc8ebd` | Plan 2+3b: README/docs surfacing + the authoring standard |
+| `283499c` | dist/ regeneration (adorned ZIPs + new pack) |
+
+### Plan 1 — Adornment (done)
+Every market-intelligence suite skill + `company-intel` now has `template.md` (the skill's own
+diffable schema extracted into a copy/paste fill-in, closing with "quality checks before you call
+it done") and worked examples. Templates were **extracted, not invented** — if you edit a skill's
+schema, edit its template in the same commit.
+
+### Plan 2 — Docs surfacing (done)
+The suite was invisible outside `skills/`. Fixed: README nav block ("Market and competitive
+intelligence"), the previously **missing v0.83 What's New entry**, the stale "52 Skills" header →
+70 with tier counts 19/27/24, `docs/Market Intelligence Suite Summary.md` (mirrors the Finance
+Suite Summary), a v0.83 entry in `docs/CHANGELOG.md`, and `06-market-intel-pack.zip` (16 skills).
+
+### Plan 3 — Dual-domain examples + standard (done)
+Every adorned skill has examples from **two business domains**, and the standard is written into
+the repo's own instructions (see "The new standard" below).
+
+---
+
+## The two fictional universes (load-bearing — reuse, don't reinvent)
+
+All example companies are fictional per the anonymization protocol. Two established universes now
+exist, and **new examples should reuse them**:
+
+**SaaS — FSM software for mid-market trades:**
+- **Fieldlight** = "us" (scheduling tool expanding into FSM)
+- **Wrenchline** (legacy incumbent), **DispatchCrow** (fast startup), **Vantiga / Vantiga FSM** (enterprise suite)
+- The chain examples *feed each other*: scan names the players → snapshot analyzes them → watch
+  diffs the snapshot (and confirms one of its filed Assumptions) → battle card rebuilds from the
+  watch's update flags. Timeline: Jun-Jul 2026.
+
+**Industrial — retrofit automation for mid-size manufacturers:**
+- **Northfield Automation** = "us" (software-led automation vendor)
+- **Helix Motion Systems** (component incumbent; "Foresight" aftermarket program), **Corvid
+  Industrial** (post-split), **Meridian Freight Systems** (warehouse-robotics platform, staging a
+  plant-floor entry — already fictional in the disciplines compendium), plus **Brightwater
+  Biologics** (unused reserve). Timeline: Aug-Nov 2026.
+- **The universes interlock:** the industrial watch example reads the same Helix Foresight
+  re-scoping (Q3 2026) that `company-intel/examples/executive-signal-refresh.md` documents from
+  the inside. Keep new fiction consistent with both timelines.
+
+**Sibling design principle:** each SaaS/industrial pair teaches what the other can't (forces
+invert in Porter's; Ansoff's diversification quadrant is empty in SaaS, populated-and-rejected in
+industrial; VoC shows thin-voice honesty; pricing tracker shows the fully-opaque case; the
+industrial investigation run shows the conflict clause; disciplines lets MASINT star).
+
+## The new standard ("Fully adorned")
+
+New skills optimally ship: **`template.md` + a SaaS example + an industrial/non-SaaS example.**
+Quality bar, not hard gate. Exemptions are judgment calls: definitionally-SaaS skills (the SaaS
+metrics pair, most finance advisors) and domain-agnostic career skills. Interactive skills
+substitute per-domain conversation-flow examples.
+
+Written into: `CLAUDE.md` Quality Checklist, `CONTRIBUTING.md` checklist (with the why),
+`AGENTS.md`, `docs/Building PM Skills.md`, both authoring meta-skills
+(`skill-authoring-workflow`, `pm-skill-creator`), and `scripts/build-a-skill.sh` prompts.
+
+**Decisions made (don't relitigate):**
+- File naming: existing example files keep their names; added domain examples get a suffix
+  (`sample-industrial.md`, `executive-signal-refresh-saas.md`).
+- **No validator/smoke rule** for dual-domain — the exemptions need judgment a script can't
+  apply. Enforcement lives in the checklists.
+
+## Gotchas discovered this session
+
+- `scripts/build-dist.sh` **hardcodes the pack list twice** (copy loop + generated dist README
+  table). A new pack silently vanishes from `dist/packages/` unless added in both places. Same
+  hazard in `build-claude-desktop-packs.sh` (pack definitions live there).
+- `docs/CHANGELOG.md` and README "What's New" are **separate hand-maintained surfaces** — v0.83
+  was missing from both until this session. A release isn't documented until both are updated.
+- `company-intel/examples/` had existed as an **empty committed directory** — `ls` the examples
+  dir, don't trust its existence.
+- Python `str.partition` misuse truncated the plan doc once mid-session (caught, rewritten). For
+  checkbox flips in that doc, prefer targeted `replace()` with verification greps.
+
+## What's next (priority order)
+
+1. **Plan 4 — back-catalog dual-domain backfill** (~28-30 skills). Full scope, carve-outs, and
+   batching plan live in `docs/maintenance/2026-07-17-adornment-and-docs-plan.md` § Plan 4. Batch
+   by theme, one commit per batch, smoke-tested; reuse the two universes; final dist regen at the
+   end. The carve-outs are named in the doc — don't "fix" the SaaS metrics skills with a factory
+   example.
+2. **Consider tagging v0.84** — the adornment pass + suite surfacing is arguably release-worthy
+   on its own (packs changed, dist changed). Dean decides; nothing tagged this session.
+3. Pre-existing queue unchanged: theme backfill (36 skills), v0.80 AI Product Builder brief
+   decision, "Invoking skills with arguments" docs subsection, Phase 6 remainder — see
+   `04JUL26.md` and `MEMORY.md`.
+
+## Validation state at handoff
+
+- `test-library.sh`: all green; the single trigger warning (`incoming-request-advisor` missing
+  literal "Use when") is **pre-existing and unrelated**.
+- All 17 touched skills pass `test-a-skill.sh --smoke` with zero warnings.
+- Anonymization sweeps clean (checked real FSM *and* industrial vendor names).
+- Drift check: 70 skills, marketplace and doc links in sync. No marketplace edits were needed
+  (no new skills — adornment only).