perf(planning): trim skill descriptions; keep extractor triggers (part of #4657)

plugins/planning/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "planning",
-  "version": "0.44.9",
+  "version": "0.44.10",
   "userConfig": {
     "surface": {
       "type": "string",

plugins/planning/CHANGELOG.md

@@ -3,6 +3,18 @@
 All notable changes to the `planning` plugin are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning.
 
+## [0.44.10] - 2026-09-28
+
+### Changed
+
+- **Skill descriptions trimmed to 500 characters or fewer (part of #4657).** Eight of the 12
+  skills ran over 500. Each now leads with its use case, keeps its quoted trigger phrases, and
+  names its nearest sibling. What the bodies already carry is cut: step lists, artifact names,
+  mode details, and restated scope. `check-listing-budget.sh plugins/planning/skills` goes from
+  7,738 to 5,454 characters. `interview` stays at 969: its whole frontmatter is digest-pinned by
+  `tests/interview-defenses.test.sh`, and recomputing that pin is left to an attended change. No
+  skill is renamed or merged, and invocation modes are unchanged.
+
 ## [0.44.9] - 2026-09-28
 
 ### Fixed

plugins/planning/skills/audit-answers/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: "Adversarially validate a completed /planning:interview's answers with independent fresh-context agents. Runs over any filled decision ledger, hand-answered or auto-accepted. Validators re-examine each answer with its rationale withheld and return a per-answer verdict (confirmed / challenged / reclassified-to-human), so only doubtful answers come back as real questions; open branches are filled with the recommended answers first, holding the never-auto floor. Use when: 'audit my interview answers', 'validate the interview answers', 'have agents check the answers', 'accept all and have agents check them', 'agent-validated interview', 'have subagents second-guess the recommendations', 'auto-answer then verify the ledger'. Not for stress-testing a plan artifact (that is '/planning:devils-advocate') or asking the human the first time ('/planning:interview'); needs a filled interview ledger."
+description: "Adversarially validate the answers in a completed '/planning:interview' ledger: fresh-context agents re-examine each answer with its rationale withheld, so only doubtful ones return as questions. Use when: 'audit my interview answers', 'validate the interview answers', 'have agents check the answers', 'accept all and have agents check them', 'agent-validated interview', 'have subagents second-guess the recommendations', 'auto-answer then verify the ledger'. Plans are '/planning:devils-advocate'."
 argument-hint: "[topic] (no args reads the current topic's interview ledger)"
 user-invocable: true
 disable-model-invocation: false

plugins/planning/skills/design-handoff/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: "Gate and package a finished design for /planning:plan: binary check that every thread in design-threads.md is RESOLVED, directional, or TAGGED-DEFERRED, then an advisory six-dimension coverage table, then emit the plan-ready summary and resume prompt. Use when: 'design handoff', 'hand off the design', 'is the design ready', 'plan-ready summary', 'design gate', /planning:design discussion rounds stop surfacing gaps, or entering /planning:plan from a completed design session. FAILs on any thread that is unresolved AND untagged. Names it and routes back to /planning:design. Skip when: still exploring the design space. Use /planning:design; mid-session save-point to clear and resume later. Use a session-handoff capability."
+description: "Gate and package a finished design for /planning:plan: every thread in design-threads.md must be RESOLVED, directional, or TAGGED-DEFERRED, then an advisory coverage table, a plan-ready summary, and a resume prompt. Use when: 'design handoff', 'hand off the design', 'is the design ready', 'plan-ready summary', 'design gate', design rounds stop surfacing gaps, or entering /planning:plan from a design session. Still exploring is /planning:design."
 argument-hint: "(no args; reads the design-threads artifact in the topic's contract slice)"
 user-invocable: true
 disable-model-invocation: false

plugins/planning/skills/design/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: "Explore and resolve design decisions. Types, contracts, package topology, module boundaries. Through collaborative discussion rounds before /planning:plan plans implementation, producing capability-matrix / type-inventory / design-threads / topology artifacts. Use when: 'design this', 'type modeling', 'figure out the abstractions', 'model this domain', 'what should the types look like', 'how should I structure this', 'where do the module boundaries go', or entering /planning:plan without exploring the design space first; scales from a single-file early-exit to a multi-session design effort."
+description: "Explore and resolve design decisions (types, contracts, package topology, module boundaries) in collaborative rounds before /planning:plan, producing design artifacts. Use when: 'design this', 'type modeling', 'figure out the abstractions', 'model this domain', 'what should the types look like', 'how should I structure this', 'where do the module boundaries go', or entering /planning:plan without exploring the design space first."
 argument-hint: "[scope] [action] (e.g., /planning:design library, /planning:design module, /planning:design status, /planning:design discuss, /planning:design handoff)"
 user-invocable: true
 disable-model-invocation: false

plugins/planning/skills/devils-advocate/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: "Stress-test plans and proposals via systematic adversarial review. Assumption extraction, evidence check, failure scenarios, operational gotchas. Before implementation begins. Use when: asked to attack a plan or proposal ('devil's advocate', 'stress test', 'poke holes', 'what could go wrong'), or before implementation on new dependencies, infrastructure/CI/build changes, or any architecture decision with cross-module blast radius. An `incumbent` mode turns the same adversarial lens on the status quo ('is there a better way now', 'should we still use X'), surveying alternatives before a plan commits to keeping an existing tool or approach. Not for code correctness bugs or pre-PR verification."
+description: "Stress-test plans and proposals by adversarial review: assumptions, evidence, failure scenarios, operational gotchas, before implementation. Use when: 'devil's advocate', 'stress test', 'poke holes', 'what could go wrong', or before new dependencies, CI/build changes, or cross-module architecture decisions. An incumbent mode tests the status quo: 'is there a better way now', 'should we still use X'. Not for code bugs or pre-PR verification."
 argument-hint: "[incumbent [target]] or [plan text or file path]. An optional leading deep/shallow sets research depth; works from conversation context if no argument given"
 user-invocable: true
 disable-model-invocation: false

plugins/planning/skills/draft-goal-condition/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: "Routes the repetition-lever choice across /goal, /loop, routines and /schedule, a dynamic workflow, a Stop hook, and a one-shot prompt, then crafts a paste-ready /goal completion condition when /goal is the fit. The autonomous-goal / keep-working-toward-a-goal field Claude Code evaluates after every turn. Reads the current official docs live for the condition shape and character limit (never hardcodes either), drafts a transcript-demonstrable condition, and proves it fits the limit with a deterministic character counter instead of model guesswork, including a branch for goals no metric can measure. Use when: choosing between /goal, /loop, routines, a workflow, a Stop hook, or a one-shot prompt ('which loop should I use', 'pick the right autonomy lever'); writing or tightening a /goal condition ('craft a /goal', 'make Claude keep working until X'); or a goal has no honest metric or runs over the character limit ('my goal is not measurable', 'my /goal is too long')."
+description: "Pick the repetition lever (/goal, /loop, routines, /schedule, a workflow, a Stop hook, a one-shot prompt), then draft a paste-ready /goal condition checked against the character limit in the live docs. Use when: 'which loop should I use', 'pick the right autonomy lever', 'craft a /goal', 'make Claude keep working until X', 'my goal is not measurable', 'my /goal is too long'."
 argument-hint: "[intent]"
 user-invocable: true
 disable-model-invocation: false

plugins/planning/skills/prd/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: "Produce a Product Requirements Document that locks product intent. Problem, users, success metrics. Before any engineering plan, with tiers (one-pager / consumer-feature / b2b-internal), a synthesize path, and a review mode. Use when: 'write a PRD', 'spec out a feature', 'product brief', 'product requirements doc', 'define the requirements', 'what are we actually building', 'acceptance criteria', 'how will we know it worked', or any user-facing business-driven change needing written alignment; skip for refactors, infra, bug fixes, and engineering-internal work (route to /planning:interview or /planning:plan)."
+description: "Produce a Product Requirements Document that locks product intent (problem, users, success metrics) before any engineering plan, in three tiers with a review mode. Use when: 'write a PRD', 'spec out a feature', 'product brief', 'product requirements doc', 'define the requirements', 'what are we actually building', 'acceptance criteria', 'how will we know it worked', or a user-facing change needs written alignment. Engineering-internal work is /planning:interview."
 argument-hint: "[tier] [task description] (e.g., /planning:prd, /planning:prd one-pager add gig calendar, /planning:prd review)"
 user-invocable: true
 disable-model-invocation: false

plugins/planning/skills/questionnaire/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: "Turn a decision another person holds into a Markdown questionnaire handed off async. Interviews the user only about the send (who it goes to, what they need back), never about the subject the recipient holds, then writes a discovery questionnaire aimed at the gap. Use when: 'make a questionnaire for X', 'I need to ask my DBA/the client/legal about this', 'turn this into a doc someone else fills in', 'I don't know, that's the client's call', 'send this to someone else to answer', 'write up questions for our security team', or when an interview branch defers to a person-arbiter; skip when the user can answer themselves (run /planning:interview) or when the answer is agent-lookupable."
+description: "Turn a decision another person holds into an async Markdown questionnaire: asks the user only about the send, never the subject. Use when: 'make a questionnaire for X', 'I need to ask my DBA/the client/legal about this', 'turn this into a doc someone else fills in', 'I don't know, that's the client's call', 'send this to someone else to answer', 'write up questions for our security team', or an interview branch defers to a person. Self-answerable is /planning:interview."
 argument-hint: "[topic]"
 user-invocable: true
 disable-model-invocation: false

plugins/planning/skills/wayfind/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: "Chart a too-big, still-foggy effort as a shared decision map on the work-item tracker, then work its frontier one decision at a time, routing each resolved decision to the right skill until the map graduates to a Brief / PRD / PLAN. Use when a task is too big to hold at once AND parts are still too fuzzy to phrase as sharp tickets ('this is a huge foggy effort', 'I don't even know the questions yet', 'map this out', 'chart this program', 'plan-the-plan'); skip when the work is already a set of sharp, answerable tickets (use /planning:interview or /work-items) or small enough to just do."
+description: "Chart a too-big, still-foggy effort as a decision map on the work-item tracker, then work its frontier one decision at a time until it graduates to a Brief, PRD, or PLAN. Use when: 'this is a huge foggy effort', 'I don't even know the questions yet', 'map this out', 'chart this program', 'plan-the-plan'. Sharp, answerable tickets go to /planning:interview or /work-items."
 argument-hint: "[chart|work] [topic] (e.g., /planning:wayfind chart <topic>, /planning:wayfind work)"
 user-invocable: true
 disable-model-invocation: false