$craft:capability-groom

Usage:

• $craft:capability-groom <capability name or id> grooms one capability.
• $craft:capability-groom <capability> --shape-only stops after the proposals, for a review
  before selection.

Scope: one capability, from definition to a selected shape and architecture. Not in scope:
splitting it into tasks, writing code, or recording entities through sdlc (the wrapper does
that).

Inputs: the capability's name or id, the product it belongs to, and the drivers behind it if
known. Output: a groomed capability (definition, boundary, selected shape, architecture, and
the rejected shapes with reasons), plus a decision ready to record.

Steps

1. Define. Write the capability in one sentence as something the product can do. Name the
   product, the drivers it serves, and what it explicitly is not. If a sibling capability
   already covers it, stop and extend that one.
2. Bound. List the surfaces it touches (CLI, TUI, desktop, skills, config), the entities it
   reads and writes, and the component or planning root that will own it.
3. Research. Run $craft:research on the open questions: prior art in the repo first
   (decisions, standards, references, existing code), then outside, time-boxed. Record each source
   and what it rules in or out.
   Note the standards and principles that constrain the shape.
4. Propose. Write two or three shapes. For each: the contract it exposes, where it lives,
   the implementation architecture in a short paragraph, what it costs, and what it forecloses.
   One shape should be the smallest that meets the drivers.
5. Select. State the criteria before comparing. Pick one shape, say why the others lost,
   and name what would reopen the choice.
6. Hand off. Fill the capability entry's sections: Statement (the step 1 sentence), What
   it provides, Inputs and Outputs (from step 2), Hook points, Underlying implementation (the
   selected shape and its architecture), and set state. Send the rejected shapes and their
   reasons to the decision's Options considered, and draft the decision with
   $craft:decision-make in the same terms: context, options, choice, consequences.

Grading

• The definition is one sentence, names a product, and has an "is not" line.
• Every source in the research is cited and says what it changed.
• There are at least two shapes, and the smallest one is among them.
• The criteria are written before the comparison, and the losing shapes have reasons.
• The capability entry and the decision use the same names for the same things.

Test environment

A scratch corpus with one product, one driver, and one standard that constrains the shape.
Run the skill on a capability that has an obvious sibling, and confirm step 1 stops. Run it on
a fresh one and compare the entry and the decision with the grading checks.