refactor(skills): shrink bundled workflows to progressive domain guidance

[ScriptedAlchemy]

Scope

Deletion-oriented review of the 15 shared bundled skills on current master at b9204dcf7de8faac4ef05af367a546aa29c32e9f.

This issue owns skill-body scope, overlap, and progressive disclosure. #890 owns removal of global bootstrap forcing. #891 owns managed-skill writer/router validation. #888 owns duplicate/prose-shape test cleanup.

Current shape

The shared plugin/skills/ catalog currently contains 15 model-invocable skills. Several are useful and reasonably partitioned, but many bodies have expanded into tool manuals, transport manuals, generic process scripts, and cross-skill routing tables.

Concrete examples:

using-the-cli

The skill contains a complete CLI manual: three argument encodings, heredoc examples, discovery, dry-run behavior, reserved flags, response-handle retrieval, failure modes, corrective errors, transport fallback conditions, and another deferred/MCP-failure section. Much of this is already discoverable from the live CLI's --help output and belongs in a reference loaded only when needed.

code-health

One skill currently owns several weakly related jobs:

• quality scorecards;
• architecture maps;
• before/after session health deltas;
• project/store/index identity and status;
• project registry/cross-project context;
• config queries, TODOs, runtime CPU/RAM, and dashboard launch.

Its description therefore matches a large fraction of repo introspection tasks and the body is effectively a catalog of tools rather than one workflow-specific mental model.

editing-safely

The body combines duplicate discovery, rename/signature/field recon, every anchored mutation primitive, structural rewrites, symbol moves, code-porting workflow, verification handoff, transport fallback, and a mandatory deliverable. The underlying safety concepts are valuable, but many argument/tool details duplicate live tool descriptions.

reviewing-changes, assessing-impact, tracing-functions, exploring-code

These have clearer individual intents, but they repeat common ceremony and transport boilerplate:

• Announce: "Using tracedecay:...";
• categorical NO ... banners;
• large tool-selection tables;
• repeated If tools are deferred or MCP fails blocks;
• mandatory final deliverable templates;
• routing links between the same neighboring skills.

Problem

A model loads skill bodies for domain guidance, not another copy of tool schemas and generic agent process.

Repeated catalog/manual material has several costs:

• more tokens after skill selection;
• stale duplicated tool names/arguments when product surfaces change;
• harder distinction between neighboring skills;
• more tests needed to keep prose synchronized;
• model attention spent following ceremony rather than the user's task;
• cross-skill cycles where each skill tells the model to invoke another routing skill.

The description should do routing. The body should add high-value TraceDecay-specific knowledge that cannot be obtained more cheaply from tool descriptions, CLI help, or general model competence. Detailed examples/reference material should be progressively loaded only when required.

Required simplification

Audit every bundled skill with this deletion test:

If this paragraph disappeared, would the model lose TraceDecay-specific domain knowledge, a real safety invariant, or a non-obvious decision rule?

If not, delete it or move genuinely useful reference material behind references/.

Specific directions:

• Remove per-skill announcement/checklist ceremony; refactor(skills): remove mandatory bootstrap forcing from using-tracedecay #890 removes the global form as well.
• Deduplicate MCP/CLI failure instructions. Keep a concise transport-fallback pointer where needed and put detailed CLI mechanics in one progressively loaded reference or live --help.
• Do not restate full tool schemas/argument catalogs inside skill bodies when the registered tool/CLI already owns them.
• Keep command examples only for non-obvious hazards or shapes that materially improve success.
• Narrow code-health to a coherent workflow. Project/store discovery, generic config/status lookup, and dashboard launch should not make a health skill match unrelated tasks merely because the tool exists there.
• Reduce using-the-cli to the transport decision and non-obvious parity/safety rules; move the argument/manual material to references or rely on generated --help.
• Keep exploring-code, tracing-functions, assessing-impact, reviewing-changes, and editing-safely separate only where behavioral routing can distinguish their moments. Merge/archive when neutral prompts repeatedly confuse them; do not merge just to hit an arbitrary skill count.
• Evaluate whether using-tracedecay should disappear into discovering-tracedecay as part of refactor(skills): remove mandatory bootstrap forcing from using-tracedecay #890 rather than leave two top-level routing skills.
• Preserve truly domain-specific constraints: graph-vs-text semantics, structural coverage caveats, external-public-user caveats, mutation atomicity, exact identity, transport parity, and other facts that the model cannot infer safely.

Do not replace one huge skill with a huge shared meta-skill.

Progressive-disclosure target

A surviving skill should normally look like:

1. concise discriminative description — enough to choose it;
2. short body — goal, TraceDecay-specific mental model, key decision points, hard pitfalls;
3. optional references/scripts — detailed catalogs/examples only when needed;
4. live tool/CLI metadata — canonical parameter and capability authority.

There is no line-count quota; deletion must improve task behavior, not optimize Markdown size mechanically.

Acceptance

• Publish a before/after inventory of bundled skill body tokens/lines and reference material moved/deleted. The primary proof is deletion, not relocation into another always-loaded document.
• For each surviving skill, document the unique domain knowledge it contributes beyond tool descriptions and generic reasoning.
• Add/update neutral routing scenarios covering neighboring skills and no-skill cases. Measure correct selection, unnecessary skill invocations, task outcome, and tool-call efficiency.
• A tool parameter rename should normally require changing the tool authority/help, not multiple SKILL.md manuals and prose tests.
• A harmless prose rewrite must not break acceptance unless that literal text is an external contract.
• Existing safety/failure journeys must remain falsifiable.

No live agent evals or token measurements were run during this source audit.

[ScriptedAlchemy]

Status (2026-09-05): already implemented on Codex's unpushed branch codex/astra-takeover-sept5 (worktree /home/zack/.codex/worktrees/48a7/tracedecay), not on any pushed ref yet. Not duplicating on #707's branch. Close when that branch lands; residuals noted by the review lane: #888 removed the only 'every MCP tool taught by a skill' gate (deferred to #891), #890/#892 leave plugin/README.md 'Announce:' paragraph and shared_skill_contract_test MIN_DESCRIPTION_CHARS gate stale until #888 lands.