skills: apply the missing-manual checklist — noop pruning, leading words, sediment fix

Reviewed all 16 skills against a four-axis skill-writing checklist (trigger,
structure, steering, pruning):

- Deleted a generic 'write for [audience]. Be direct.' noop from 7
  Synthesis/consolidation roles that added nothing beyond the output
  template already below it; kept concrete stakeholder specs where present.
- Reinforced two under-used leading words past their intro: people-tool-selection's
  'constraints eliminate before capability ranks' now echoes at Role 3;
  general-idea-diagnostic's Friction-first/Tech-first now echoes at Roles 2 and 4.
- Shortened two long 'not to be confused with' disambiguation footnotes
  (70/20/10 in process-portfolio-observability, 88/25 in tech-data-deployment)
  — each colliding number is now self-disambiguating at first use.
- Trimmed one redundant example trigger phrase from the three longest
  descriptions, keeping every distinct phrasing.
- CLAUDE.md documents the deliberate model-invoked trigger choice; the
  template and CONTRIBUTING.md gain a noop-deletion-test and leading-words
  habit for new skills.
- Structure axis reviewed but not changed: three candidate branch-only
  blocks were each under 500 chars — not worth externalizing.

Verified: scripts/validate.py clean; scripts/run_golden_prompts.py --full
on all 8 skills with edited role content (verdict vocabulary intact) plus
--routing on all affected boundary pairs — 16/16 live passes.

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

Author: geledek

CHANGELOG.md

@@ -11,6 +11,14 @@ All notable changes to this plugin are documented here.
 ### Fixed
 - **`plugin.json` rejected by current Claude Code.** The manifest failed schema validation (`author` must be an object, not a string; `skills` paths must be `./`-prefixed), so `--plugin-dir` loads — and potentially fresh plugin-manager installs — silently dropped all 16 skills. Found by the first live run of the golden-prompt runner.
 
+### Changed
+- Applied a "missing manual" checklist pass (trigger design, structure, steering, pruning) across the skill suite:
+  - Removed a generic "write for [audience]. Be direct." sentence from 7 Synthesis/consolidation roles that added nothing beyond the output template already below it (kept concrete stakeholder specs where present, e.g. `tech-data-deployment`'s CISO/business-owner/DPO sign-off).
+  - Reinforced two under-used "leading words" so they survive past the intro: `people-tool-selection`'s "constraints eliminate before capability ranks" now echoes at Role 3; `general-idea-diagnostic`'s "Friction-first vs. Tech-first" now echoes at Roles 2 and 4.
+  - Shortened the two long "not to be confused with" disambiguation footnotes (70/20/10 in `process-portfolio-observability`, 88/25 in `tech-data-deployment`) — each colliding number is now self-disambiguating at first use, so the footnote no longer has to carry the whole burden.
+  - Trimmed one redundant example trigger phrase each from the three longest skill descriptions (`people-tool-selection`, `tech-data-deployment`, `people-frontline-engagement`), keeping every distinct phrasing.
+  - `CLAUDE.md` documents the deliberate model-invoked trigger choice for this plugin (and the context-load tradeoff), so it isn't "fixed" by a future contributor; `templates/SKILL.md.tmpl` and `CONTRIBUTING.md` gain a noop-deletion-test and leading-words habit for new skills.
+
 ## [0.5.0] — 2026-07-02
 
 ### Added

CLAUDE.md

@@ -13,7 +13,7 @@ markdown plus two JSON manifests.
 - `references/` — 200–500-word research extracts skills cite by bare filename.
   `references/_index.md` is the catalog; its consumer columns are validated
   against actual citations.
-- `.claude-plugin/plugin.json` + `marketplace.json` — both list all 15 skills
+- `.claude-plugin/plugin.json` + `marketplace.json` — both list all 16 skills
   and carry the version; they must stay in sync (CI checks this).
 - `templates/SKILL.md.tmpl` — starting point for new skills.
 - `docs/` — usage guide, demo scripts, effectiveness reports.
@@ -34,6 +34,15 @@ markdown plus two JSON manifests.
 - Commit style: `<skill-or-ref>: <what changed>`
   (e.g. `general-roi-gate: tighten Q3 measurement prompt`).
 - Notable changes go under `## [Unreleased]` in `CHANGELOG.md`.
+- All 16 skills are deliberately **model-invoked** — the frontmatter
+  `description` (and its trigger phrases) is designed to sit in the agent's
+  context every session so the right skill auto-fires on the right prompt.
+  This is a considered tradeoff, not an oversight: it costs per-session
+  context (16 descriptions ≈ 3K tokens), but a decision-gate plugin that
+  requires the user to remember and manually invoke 16 skill names defeats
+  its own purpose. Don't "fix" this by making skills user-invoked-only; do
+  keep descriptions tight, since that context cost is paid on every session
+  regardless of which skill fires.
 
 ## Before committing
 

CONTRIBUTING.md

@@ -41,6 +41,14 @@ case that inspired it, and that one counterfactual (a changed input) flips the
 verdict. `skills/people-tool-selection/` with its `cases/` file is the worked
 example of this process.
 
+Two habits keep a skill sharp as it grows:
+- **Noop deletion test.** For every sentence outside the output template, ask
+  "would deleting this change the output?" If not, cut it — generic framing
+  ("write for a board audience", "be direct") almost never survives this test.
+- **Leading words.** Pick one dense, well-known term that captures the
+  skill's core distinction, and echo it at the role where a weaker model is
+  most likely to drift from it — don't just define it once in the intro.
+
 ## What not to change in a fork
 
 - The structural role sequence — it's the methodology, not a style choice

skills/general-idea-diagnostic/SKILL.md

@@ -32,7 +32,7 @@ WHO FEELS THE PAIN | WHAT IT COSTS | FRICTION-FIRST OR TECH-FIRST | PAIN STATEME
 
 ## Role 2: Devil's Advocate (Q2 — Right Solution Mode?)
 
-Your job is to find where this breaks, not where it succeeds.
+Your job is to find where this breaks, not where it succeeds. If Role 1 classified this as tech-first, apply extra scrutiny below — a solution hunting for friction fails the reliability test more often than one born from a named pain.
 
 RELIABILITY TEST. "Would I be comfortable if this output reached the end consequence — the customer, the regulator, the judge — without human review?" Yes or no. Name the consequence of an error.
 
@@ -88,7 +88,7 @@ WHAT ACCUMULATES | THREE METRICS | MEASUREMENT GAP | OBJECTIVE MODE | MOAT TYPE
 
 ## Role 4: Realist (Q4 — Right Capability?)
 
-Your job is to identify the execution gaps that would prevent this idea from working in practice, regardless of how sound the concept is.
+Your job is to identify the execution gaps that would prevent this idea from working in practice, regardless of how sound the concept is. Tech-first ideas (Role 1) tend to surface more gaps here — the capability was chosen before the constraint was known.
 
 DATA. Is the data AI-ready? Does the organisation have confirmed legal rights to use it? Is it in a usable format and accessible via pipeline? (Consult `isg-data-foundation.md` — the binding-constraint finding.)
 
@@ -105,8 +105,6 @@ DATA | INTEGRATION | CHANGE MANAGEMENT | Q4 VERDICT (Pass / Gaps / Fail)
 
 Read the outputs of Roles 1–4. Produce the verdict. Do not introduce new assessment here.
 
-Write for a board audience. Be direct.
-
 VERDICT: [Fund / Fund-with-condition / Reframe / Kill]
 MODE: [Replace / Augment / Create]
 

skills/general-roi-gate/SKILL.md

@@ -94,7 +94,7 @@ Output:
 
 ## Role 4: Investment Verdict
 
-Synthesize Roles 1–3. Write for executive or board audience.
+Synthesize Roles 1–3.
 
 RECOMMENDATION: [Approve / Approve-with-conditions / Return-for-revision / Reject]
 

skills/people-frontline-engagement/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: people-frontline-engagement
-description: Use when frontline experts — clinicians, investigators, lawyers, engineers, customer agents — fear AI replacement, deskilling, or accountability shift, and the rollout is stalling on resistance rather than tech. Phrases like "clinicians are afraid AI will replace them", "how do I integrate AI into a high-stakes clinical workflow without revolt?", "the team thinks this is automation in disguise", "senior staff are blocking the AI pilot", "we need buy-in from the frontline before we deploy", all trigger this skill. Runs a five-role engagement protocol — empathic listening, jagged-frontier task split, co-design workshop, psychological-safety contract, tradecraft protection — that turns the threatened expert into the co-author of the augmentation. Outputs an Engagement Plan, an AI-leads/Human-leads/Hybrid/Off-limits task split, and a written Safety Contract.
+description: Use when frontline experts — clinicians, investigators, lawyers, engineers, customer agents — fear AI replacement, deskilling, or accountability shift, and the rollout is stalling on resistance rather than tech. Phrases like "clinicians are afraid AI will replace them", "the team thinks this is automation in disguise", "senior staff are blocking the AI pilot", "we need buy-in from the frontline before we deploy", all trigger this skill. Runs a five-role engagement protocol — empathic listening, jagged-frontier task split, co-design workshop, psychological-safety contract, tradecraft protection — that turns the threatened expert into the co-author of the augmentation. Outputs an Engagement Plan, an AI-leads/Human-leads/Hybrid/Off-limits task split, and a written Safety Contract.
 ---
 
 # People — Frontline Augmentation Engagement

skills/people-readiness-conversation/SKILL.md

@@ -110,7 +110,7 @@ JOB 1–5 STATUS (ACTIVE/PLANNED/ABSENT) | CRITICAL GAPS | SPECIFIC ACTIONS PER
 
 ## Synthesis: 4-Role Gap Report
 
-Consolidate Roles 1–4. Write for CEO or CHRO audience.
+Consolidate Roles 1–4. The reader is the CEO or CHRO who owns the fix.
 
 **OVERALL READINESS ASSESSMENT:**
 - People layer is: STRONG / DEVELOPING / CRITICAL-GAP

skills/people-tool-selection/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: people-tool-selection
-description: Use when choosing which AI tool to put in front of a specific user group — a training cohort, a team, a school, a department — or deciding whether to teach deeper prompting, extend existing tools with agent skills, or introduce a new tool. Phrases like "which AI tool should I teach this group?", "choosing an AI tool for our teachers / nurses / analysts", "what AI tool should we roll out to the team?", "should I teach advanced prompting or a new tool?" all trigger this skill. Runs six roles — Audience Profiler, Constraint Mapper (hard eliminators before any capability comparison), Intervention-Mode Selector (Deepen / Extend / Introduce), Capability-Delta Assessor, First-Win Realist, Synthesis. Outputs Adopt-now / Adopt-with-scaffolding / Pilot-with-subgroup / Skip plus a growth path. For build/buy/partner sourcing of an AI capability use tech-buy-vs-build; for enterprise-wide curriculum design use people-literacy-curriculum.
+description: Use when choosing which AI tool to put in front of a specific user group — a training cohort, a team, a school, a department — or deciding whether to teach deeper prompting, extend existing tools with agent skills, or introduce a new tool. Phrases like "which AI tool should I teach this group?", "choosing an AI tool for our teachers / nurses / analysts", "should I teach advanced prompting or a new tool?" all trigger this skill. Runs six roles — Audience Profiler, Constraint Mapper (hard eliminators before any capability comparison), Intervention-Mode Selector (Deepen / Extend / Introduce), Capability-Delta Assessor, First-Win Realist, Synthesis. Outputs Adopt-now / Adopt-with-scaffolding / Pilot-with-subgroup / Skip plus a growth path. For build/buy/partner sourcing of an AI capability use tech-buy-vs-build; for enterprise-wide curriculum design use people-literacy-curriculum.
 ---
 
 # People — AI Tool Selection
@@ -51,7 +51,7 @@ CANDIDATES | CONSTRAINT TABLE (pass/fail per filter) | SURVIVORS | ELIMINATED (e
 
 ## Role 3: Intervention-Mode Selector (Deepen / Extend / Introduce?)
 
-The real choice set is rarely just tools — it is three intervention modes. Pick the primary mode before ranking tools.
+Work only from Role 2's survivor set — constraints already eliminated the rest. The real choice set is rarely just tools — it is three intervention modes. Pick the primary mode before ranking tools.
 
 - **DEEPEN** — better use of tools the group already has (structured prompting frameworks, workflow habits). Right when the baseline is low, or current tools are underused relative to their ceiling.
 - **EXTEND** — add capability to existing tools (agent skills, custom GPTs/Projects, connectors, templates). Right when the baseline is solid AND someone in the group can own and maintain the extensions. *Consult `hiten-skill-library.md` — the skill-library strategy is the canonical Extend play.*

skills/process-pilot-design/SKILL.md

@@ -130,7 +130,7 @@ PILOT OWNER | SPONSOR | USER CHAMPION
 
 ## Role 7: Pilot Brief (Synthesis)
 
-Produce a one-page pilot brief from Roles 1–6. Write for sponsor approval. Be direct.
+Produce a one-page pilot brief from Roles 1–6, ready for sponsor sign-off.
 
 **PILOT BRIEF**
 

skills/process-portfolio-observability/SKILL.md

@@ -7,7 +7,7 @@ description: Use when an enterprise has shipped AI agents but cannot see usage,
 
 Most enterprises run AI like a black box: they ship agents, they pay tokens, they cannot answer "what did this earn us net of oversight?" PwC's 2026 ROI guidance is explicit — *gross* productivity is not the number; **net-of-oversight ROI** is. The european fintech case shows the trap: 40% deflection headline, 22% CSAT drop, net value negative. This skill builds the instrumentation that exposes that math before the board does.
 
-Anchor: PwC three-channel ROI (efficiency + growth + revenue) minus oversight cost; IMDA Dimension 4 structural controls; NIST RMF MANAGE function on continuous monitoring; 70/20/10 *portfolio mix* prior (70% core / 20% adjacent / 10% transformational — not to be confused with BCG's 10/20/70 *effort split* used in `general-use-case-discovery` and `general-peer-cases`, or `people-literacy-curriculum`'s 70-20-10 *training-budget* split).
+Anchor: PwC three-channel ROI (efficiency + growth + revenue) minus oversight cost; IMDA Dimension 4 structural controls; NIST RMF MANAGE function on continuous monitoring; 70/20/10 *portfolio mix* prior (70% core / 20% adjacent / 10% transformational). Distinct from BCG's *effort-split* and *training-budget* uses of the same digits elsewhere in this plugin — always read "70/20/10" here as portfolio mix.
 
 Verdict vocabulary (stable output contract): **Observable-and-governed / Partial-observability / Black-box**.