From 86020c6a4894ddd8b46addbdb8b6fb225d523e45 Mon Sep 17 00:00:00 2001 From: coseto6125 <80243681+coseto6125@users.noreply.github.com> Date: Thu, 23 Jul 2026 00:55:56 +0800 Subject: [PATCH] docs(skill): rewrite ecp skill pack, A/B-validated on Haiku MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - ecp SKILL.md: backtick real commands in the description map ("definition→`ecp find`") — the bare arrow form ("where→find", "trace-flow→processes") made Haiku invent verbs (ecp where, ecp trace-flow) in 2/9 trigger trials; 0/9 after. Collapse the four directives into Core rules: drop the ambiguous-name trap (the CLI error already instructs --file/--kind; no-skill control passed 3/3) and the warm-attach mechanics prose (the result caveat from PR #504 self-instructs; control passed 3/3). Remove stale HIGH/CRITICAL risk_level wording (feature removed in PR #592). Body -12%. - ecp ECP.md: same stale HIGH/CRITICAL fix. - ecp-onboard SKILL.md: merge when-to-use triggers into description — skill loaders surface only description, so the ONBOARDING-link trigger never fired (baseline 0/3 → 3/3 after). - lint-skill.sh: stop requiring when-to-use (it codified the invisible-field bug); regression case in test-lint-frontmatter.sh. - codex ecp SKILL.md: adopt the validated command-map description (who-calls trials 0/3 → 3/3); collapse the three layers. A/B method: claude -p --model haiku --setting-sources project from a clean dir, 11 scenarios x 3 arms (no-skill control / current / rewritten), n=3-6 per cell, flagged outputs read manually. --- docs/skills/ecp-onboard/SKILL.md | 8 ++--- docs/skills/ecp/ECP.md | 2 +- docs/skills/ecp/SKILL.md | 30 +++++-------------- scripts/skill/lint-skill.sh | 6 ++-- skill_sample/codex/ecp/SKILL.md | 44 +++++----------------------- tests/skill/test-lint-frontmatter.sh | 12 ++++++++ 6 files changed, 36 insertions(+), 66 deletions(-) diff --git a/docs/skills/ecp-onboard/SKILL.md b/docs/skills/ecp-onboard/SKILL.md index 798898be1..bba249c9e 100644 --- a/docs/skills/ecp-onboard/SKILL.md +++ b/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 diff --git a/docs/skills/ecp/ECP.md b/docs/skills/ecp/ECP.md index f9ee33663..abe3b45b8 100644 --- a/docs/skills/ecp/ECP.md +++ b/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 --direction upstream` to see callers. HIGH/CRITICAL risk → confirm with user. +`ecp impact --target --direction upstream` to see callers. Many callers, or callers in core / widely-imported modules → confirm with user. ## Reading output — four tells diff --git a/docs/skills/ecp/SKILL.md b/docs/skills/ecp/SKILL.md index 19204a248..7d7624dc5 100644 --- a/docs/skills/ecp/SKILL.md +++ b/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 ` 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 --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 `; 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 --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 ` (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. - diff --git a/scripts/skill/lint-skill.sh b/scripts/skill/lint-skill.sh index 2384d8cdc..00ab4a5f4 100755 --- a/scripts/skill/lint-skill.sh +++ b/scripts/skill/lint-skill.sh @@ -9,7 +9,9 @@ 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" @@ -17,7 +19,7 @@ skill="$ROOT/SKILL.md" 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 diff --git a/skill_sample/codex/ecp/SKILL.md b/skill_sample/codex/ecp/SKILL.md index bd74b7e54..e74692b48 100644 --- a/skill_sample/codex/ecp/SKILL.md +++ b/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 --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. diff --git a/tests/skill/test-lint-frontmatter.sh b/tests/skill/test-lint-frontmatter.sh index a4c7887c5..d0c385914 100755 --- a/tests/skill/test-lint-frontmatter.sh +++ b/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