adoption-readout

name

adoption-readout

description

Generate a client's L2 "adoption readout" — the Ladder (DEC-0052's wedge). From a provisioned client's served OKF, run the deterministic 4-axis scorer over their process/workflow atoms, then narrate a sequenced Now/Next/Later transformation roadmap and emit it as a sovereign OKF `artifact` in the CLIENT's own repo. Use after a client is ingested + served (KNOWLEDGE-BRIEF generated) to produce the post-diagnostic readout that lands the wedge ("we'll take you to where we already are") and opens the Agency conversation. Human-curated authoring; reads the client's OWN OKF, never perturbs Dossier's KB.

Generate a Client Adoption Readout (the Ladder, L2)

Author one adoption readout — a transformation roadmap, sequenced by initiative, computed from a client's own OKF Company Brain — and emit it as a sovereign OKF artifact in the client's own repo. This is DEC-0052's third face (the Ladder), the wedge: "we'll take you to where we already are." The seed is the per-client KNOWLEDGE-BRIEF.md; this is the shippable L2 readout.

This is a Claude Code skill — humans curate, agents extend (DEC-0004). The scorer computes; you narrate. You MUST NOT invent or recompute any score — the numbers come from the deterministic scorer, and your job is the prose around them.

The contract (read first — it is the cage)

• The scorer is deterministic and authoritative. packages/okf-view/src/adoption-readout.ts (scoreAdoptionReadout) computes every number. Run it via scripts/adoption-readout.mjs; never re-derive a score by hand. The spec (the four axes, their OKF-signal derivations, the 2×2) is DEC-0067.
• Output is a sovereign OKF artifact in the CLIENT repo (DEC-0001) — never a Dossier-held report, never a new top-level concept type (it is an artifact, not a readout type).
• Links, never copies. The readout relates_to every initiative it scored and [[wiki-links]] them in prose; it never copies an atom's body (single source of truth).
• Confidence is propagated, never inflated. The artifact's confidence = the scorer's meta.confidenceFloor (the lowest among scored atoms). A freshly-scraped client is all inferred; the readout says so.
• No fabricated numbers. No dollars, no percentages, no KPIs not present in an atom. ROI is the ordinal value axis, never a currency (DEC-0067 non-goal #1).

Inputs

1. The client's OKF repo path + tenant manifest clients/<id>/tenants/<t>/dossier.tenant.json (clientId, vertical, okfDir), e.g. RBA → clients/rba/tenants/rba-consulting/okf.
2. The client's KNOWLEDGE-BRIEF.md (the served-OKF summary) — the seed framing for the "what we read" section.
3. (optional) clients/<id>/src/_manifest.json for brand/voice notes (same convention as generate-landing).

Procedure

1. Run the scorer (deterministic ledger). For a provisioned tenant, prefer the control-plane front door — dossier-runtime readout --root <tenants-root> --client <id> (resolves the tenant by id; needs the built runtime). Or, for a raw OKF dir, node scripts/adoption-readout.mjs <client-okf-dir> (needs pnpm -F @dossier/okf-view build once). Either way, capture the ledger JSON from stdout — it is the deterministic input you narrate — and read the stderr summary for the at-a-glance shape.
2. Read the client (for vocabulary, not numbers). Read the tenant manifest, KNOWLEDGE-BRIEF.md, and — for any initiative you describe — its atom via the tenant-scoped @dossier/mcp tools (search_concepts → get_concept → get_related), so every claim has a provenance trail. Use the client's own words.
3. Narrate the six sections (below) around the ledger. Each score you mention MUST be the scorer's, and each NOW/NEXT item MUST cite the evidence string behind its axis scores (the appendix). Where the floor is inferred, say so plainly — the honesty IS the credibility.
4. Name the wedge. The ledger's wedge (= now[0]) is the #1 initiative. In "Start here", name it and the exact first unit of work an Agency team would dispatch against it (this is the land-and-expand hinge into DEC-0052's Agency face).
5. Emit the OKF artifact into the client repo (below), linking every scored atom. Validate it.

The readout — six sections (DEC-0067 §4)

1. Where you are on the ladder — the L1→L14 framing; place the org honestly (a freshly-ingested, all-inferred client sits ~L1–L3: "you've just completed your AI audit; here's the readout"). Set up "we'll take you to where we already are."
2. What we read — meta: N initiatives scored, M atoms, K typed edges, the confidence mix. Honest ("all inferred from your public site — confirming these is step one").
3. The priority map (the 2×2) — Now / Next / Later / Watch, by initiative (the buyer's center of gravity).
4. Your roadmap — Now / Next / Later — the sequenced timeline; each NOW/NEXT item shows its payoff + ease and a one-line rationale (NEXT items get "what would unblock it" — usually raise readiness: confirm/extend the memory, which is the Agency's job).
5. Start here (the wedge) — the wedge initiative, named, with the exact first Agency unit of work.
6. Appendix — the score ledger (provenance) — a per-initiative table: the four 1–5 axis scores and the evidence string behind each, plus the [[atom]] link. No black-box numbers — this is what makes it trustable, not optional.

Rules

• Scorer computes, you narrate (hard line). Never invent, round, or "adjust" a score. If a number feels wrong, fix the scorer (DEC-0067) or the atom — never the narration.
• Provenance discipline. Every initiative claim traces to its atom; every score to its evidence string. No invented names, metrics, customers, or pricing. No $/% figures.
• Sovereignty. Read the client's OWN OKF; write ONLY into the client repo. Dossier's knowledge/ is never touched (same isolation as generate-landing).
• Links, not copies. relates_to + [[wiki-links]]; never paste an atom body.
• Confidence floor. confidence: <meta.confidenceFloor>; never claim more certainty than the inputs.

Output

• Canonical: one OKF artifact atom in the client's own repo — clients/<id>/readouts/adoption-readout.md (sovereignty, DEC-0001). Frontmatter: type: artifact, id: <client>-adoption-readout, title, confidence: <floor>, source: scripts/adoption-readout.mjs + KNOWLEDGE-BRIEF, relates_to: [<every scored initiative id>], timestamp. Body = the six sections.
• A summary: the wedge initiative + its path/confidence, the Now/Next/Later counts, and the confidence floor.

Verify (build-proven — never claim it works without these passing)

1. Deterministic — re-running scripts/adoption-readout.mjs on the unchanged OKF yields a byte-identical ledger (the scorer is pure; placement + order are stable).
2. Validates — the emitted artifact passes @dossier/okf parse() as type: artifact (run it through pnpm kb:check against the client KB, or parse() directly).
3. Links resolve — every relates_to / [[link]] target is a real atom id in the client's OKF (no dangling links); grep finds zero copied atom bodies.
4. Honest — grep the artifact for $ / % / fabricated KPIs → none; confidence equals the ledger's meta.confidenceFloor; any NOW item resting on inferred evidence is labeled "confirm first".
5. Isolation — Dossier's own knowledge/ is unchanged after the run; only clients/<id>/... was written.
6. Wedge fitness — the readout names a concrete #1 NOW initiative and the exact first Agency unit of work; a reviewer can say "I could open the Agency conversation from this page."

Does NOT

Build any server/DB/hosted-runtime code, and never mints a new OKF concept type. The readout is an artifact; the scorer is the SSOT for the numbers. The hosted control plane is a separate future build, untouched.