docs(skill): rewrite ecp skill pack, A/B-validated on Haiku

docs/skills/ecp-onboard/SKILL.md

@@ -1,10 +1,8 @@
 ---
 name: ecp-onboard
-description: Personalized install + config wizard for egent-code-plexus. Walks the
-  user from "no ecp installed" → "ecp ready + indexed + agent integrated (native
-  else MCP) + next steps".
-when-to-use: User says "install ecp" / "set up egent-code-plexus" / "onboard me
-  to ecp", OR opened an ONBOARDING share link / pasted a bootstrap URL.
+description: Personalized install + config wizard for egent-code-plexus. Use when
+  the user asks to install, set up, or onboard ecp ("install ecp", "set up
+  egent-code-plexus"), opened an ONBOARDING share link, or pasted a bootstrap URL.
 ---
 
 # ecp-onboard

docs/skills/ecp/ECP.md

@@ -24,7 +24,7 @@ Fall back to grep or an Explore agent only when the target is non-code text, or
 
 ## Before any refactor / rename / signature change
 
-`ecp impact --target <symbol> --direction upstream` to see callers. HIGH/CRITICAL risk → confirm with user.
+`ecp impact --target <symbol> --direction upstream` to see callers. Many callers, or callers in core / widely-imported modules → confirm with user.
 
 ## Reading output — four tells
 

docs/skills/ecp/SKILL.md

@@ -1,29 +1,18 @@
 ---
 name: ecp
-description: When you want to explore code structure — where a symbol is defined, who calls it, a refactor's blast radius, routes/contracts, or to trace how code connects — reach here before grep or an Explore agent. Verb by question: where→find, who-calls/blast-radius→impact, full-context→inspect, where-a-filename-is-read-vs-written→impact --literal, routes/contracts→those, trace-flow→processes, graph-question-with-no-verb (orphans, all-impls)→cypher. Grep only for non-code text: config values, log strings, fs layout.
+description: Tracing who-calls-X or a data flow — mid-debug, not only before a refactor — or exploring code structure: where a symbol is defined, who calls it, blast radius, routes/contracts. Reach here before grep. Command by question: definition→`ecp find`, who-calls/blast-radius→`ecp impact`, full context→`ecp inspect`, filename-read-vs-written→`ecp impact --literal`, routes/contracts→`ecp routes`/`ecp contracts`, trace execution flow→`ecp processes`, graph question with no verb (orphans, all-impls)→`ecp cypher`. Grep only for non-code text: config values, log strings, fs layout.
 ---
 
 # EgentCodePlexus (ecp) — Structural Analysis Entry
 
----
-
-## 🧭 Core Principles
-
-### Directive 1: ecp-first reflex (full rule in @ECP.md §"The reflex")
-The moment you'd fan out to read files or grep for a symbol to understand structure, that's the ecp trigger — for any indexed repo, ecp's own included. Verb map is in the description above. Two traps weak models hit: (a) **"who calls X" → `ecp impact`, not `ecp find`** — find locates the definition + a caller *count*; impact returns the caller *list* you need before a refactor; (b) on an **ambiguous-name error** (`'handle' is ambiguous`), don't fall back to Read — re-run with `--file <f>` or `--kind function`.
-
-### Directive 2: Blast Radius before Refactor — and it's a lower bound
-Before modifying a function or class, run `ecp impact` for callers (HIGH / CRITICAL → confirm with user). The caller set is a **lower bound**: a bare call to a common name can be suppressed by the resolver's ambiguity cap. **Tell:** suspiciously low caller count → `grep` the call sites to cross-check.
-
-### Directive 3: `found:false` is two-valued — and a real miss means "report it, don't invent"
-`found:false` can mean "doesn't exist" OR "warm-attach, HEAD not indexed yet". **Tell:** a `result` caveat field (it states how far to trust the rows) or `l2.warm-attach` / `note:` on stderr → provisional; rerun or `ecp admin index --force --repo .`. Then `ecp find <fragment> --mode fuzzy` for a genuine miss. **If the symbol truly isn't there, say exactly that — never synthesize a blast radius / caller list for a symbol ecp couldn't find** (that's the fabrication ecp exists to prevent).
+## Core rules
 
-### Directive 4: Surprising output has a root cause; grep is right for text
-Before concluding "ecp is broken", verify against source (definition, fresh reindex, grep cross-check) — doc-comment inference ≠ verification. **Tell:** non-code text — string literals, error messages, config keys, vendored / generated code, fs layout — belongs to grep / Read; ecp parses code, not text.
+1. **ecp-first.** The moment you'd fan out to read files or grep a symbol to understand structure, that IS the ecp trigger — any indexed repo, ecp's own included. "Who calls X" → `ecp impact` (returns the caller *list*); `ecp find` only locates the definition.
+2. **Blast radius before refactor — and it's a lower bound.** Before changing a function or class, run `ecp impact <name>`; many callers, or callers in core / widely-imported modules → confirm with the user first. The resolver suppresses ambiguous bare calls to common names, so the caller set is a lower bound: a suspiciously low count for a common name → `grep` the call sites to cross-check.
+3. **Honest miss.** `found:false` carrying a `result` caveat field is provisional — do what the caveat says (rerun, or `ecp admin index --force --repo .`). `found:false` with no caveat is trustworthy: try `ecp find <fragment> --mode fuzzy` for name drift, then report "doesn't exist" — never synthesize a caller list or blast radius for a symbol ecp couldn't find.
+4. **Text → grep.** String literals, log messages, config keys, fs layout, vendored / generated code: grep / Read. ecp parses code, not text. For any other surprising output, find the root cause before calling it a bug: [`guides/troubleshooting.md`](./guides/troubleshooting.md).
 
----
-
-## ⚡ Quick Reference
+## Quick Reference
 
 ### Symbol lookup
 | Command | Use for |
@@ -75,11 +64,8 @@ Run in order `sync` → `contracts` → `impact`: `ecp group sync <name>` (cross
 ### Schema introspection (no graph load)
 `ecp schema blindspots` (per-lang BlindSpot coverage), `reltypes` (RelType edges + LLM-utility + heuristic flag), `node-kinds` (NodeKind variants + Struct-vs-Class etc.), `graph-version` (graph.bin format version).
 
----
-
-## 📚 On-Demand References
+## On-Demand References
 
 - [`guides/troubleshooting.md`](./guides/troubleshooting.md) — `found:false`, index staleness, resolver misses, output-trust tells.
 - `_shared/cli/` — Per-command flag references (`inspect`, `impact`, `cypher`, `group`, `processes`, …).
 - `_shared/refs/` — Cypher syntax, repo resolution.
-

scripts/skill/lint-skill.sh

@@ -9,15 +9,17 @@ ROOT="${1:-docs/skills/ecp-onboard}"
 
 fail() { echo "lint FAIL: $1" >&2; exit 1; }
 
-# --- Check 1: SKILL.md exists with valid frontmatter (name, description, when-to-use) ---
+# --- Check 1: SKILL.md exists with valid frontmatter (name, description) ---
+# when-to-use is NOT required: skill loaders surface only `description` to the
+# model, so trigger phrases must live there.
 skill="$ROOT/SKILL.md"
 [[ -f "$skill" ]] || fail "SKILL.md missing at $skill"
 
 # Extract frontmatter block (between leading --- and next ---). Tolerate CRLF.
 fm=$(awk '/^---\r?$/{c++; next} c==1' "$skill")
 [[ -n "$fm" ]] || fail "SKILL.md has no frontmatter"
 
-for key in name description when-to-use; do
+for key in name description; do
     grep -qE "^${key}:" <<<"$fm" || fail "SKILL.md frontmatter missing '$key'"
 done
 

skill_sample/codex/ecp/SKILL.md

@@ -1,50 +1,22 @@
 ---
 name: ecp
-description: Use for ecp command and workflow reference. Start here for command selection, help routing, and links into the detailed guides.
+description: Exploring code structure in an indexed repo — reach here before grep, and never guess `ecp` syntax from memory. Command by question: definition→`ecp find`, who-calls/blast-radius→`ecp impact`, full context→`ecp inspect`, routes/contracts→`ecp routes`/`ecp contracts`. Flags and admin subcommands: help routing inside.
 ---
 
 # ecp — Entry Point
 
-This is the **single entry point** for the Codex-facing `ecp` skill set.
+Single entry point for the Codex-facing `ecp` skill set. Identify the task category, then open the matching guide — guides and `--help` are ground truth, not memory.
 
-When you need to use `ecp`, do not guess from memory. First identify the task category, then open the matching guide.
+## Core directives
 
----
-
-## Layer 1: Core Directives
-
-These rules apply to every `ecp` task.
-
-### Directive 1: Use the actual help output
-`ecp --help` is the top-level command map.
-`ecp admin --help` is the admin subcommand map.
+1. **Help routing.** `ecp --help` = top-level command map; `ecp admin --help` = admin subcommand map; `ecp <command> --help` = per-command flags. `ecp admin` without a subcommand launches the interactive TUI — never run it just to see the reference.
+2. **Smallest command that fits.** If one subcommand's help page answers the task, use it before reading any broader reference.
 
-Do not treat `ecp admin` as a help command; it launches the interactive TUI by default.
-
-### Directive 2: Prefer the smallest command that fits
-If a task can be answered by the top-level help or a single subcommand help page, use that before reading any broader reference.
-
-### Directive 3: Keep task-specific workflows separate
-Command syntax, review workflows, and broader repository guidance should live in separate guides instead of one large doc.
-
----
+## Decision tree
 
-## Layer 2: Decision Tree
-
-| If you need... | Open guide |
+| If you need... | Open |
 |---|---|
 | Command names, flags, output formats, or admin subcommands | [`guides/command-reference.md`](./guides/command-reference.md) |
 | Change review workflow for changed files | [`../simplify/SKILL.md`](../simplify/SKILL.md) |
 
-> If you are unsure which command to use, start with `ecp --help`, then open the matching guide.
-
----
-
-## Layer 3: On-Demand References
-
-These are support files, not entry points.
-
-- `guides/` — detailed command and workflow references
-- `../simplify/SKILL.md` — graph-aware review workflow built on top of `ecp`
-
-If you find yourself reading every file under `skill_sample/codex/` for one task, you skipped Layer 2.
+Reading every file under `skill_sample/codex/` for one task means you skipped this table.

tests/skill/test-lint-frontmatter.sh

@@ -44,4 +44,16 @@ cat > "$tmp/docs/skills/ecp-onboard/guides/01-install.md" <<'EOF'
 EOF
 assert_exit 0 bash "$LINT" "$tmp/docs/skills/ecp-onboard"
 
+# Case 5: name + description only (no when-to-use) → passes; triggers live in
+# description because skill loaders never surface when-to-use to the model.
+cat > "$tmp/docs/skills/ecp-onboard/SKILL.md" <<'EOF2'
+---
+name: ecp-onboard
+description: Install wizard. Use when the user asks to install or set up ecp.
+---
+- Jump table:
+  - install → guides/01-install.md
+EOF2
+assert_exit 0 bash "$LINT" "$tmp/docs/skills/ecp-onboard"
+
 pass