---
name: whetstone
version: 0.3.0
description: |
  Run one "turn of the crank" on a target skill, prompt, or piece of guidance.
  Apply the skill to a real test input, self-grade against its own rules,
  improve the output, then surface ambiguities to the user as A/B questions
  and fold the answers back into the skill file. The skill is the durable
  artifact; the chat is exhaust. Use when the user says "run the whetstone
  loop", "sharpen this skill", "improve this prompt", "turn the crank on X",
  or wants to compound learnings into a versioned skill instead of
  re-prompting one-off.
argument-hint: "[path/to/target/skill.md] [path/to/test-input]"
allowed-tools:
  - Read
  - Edit
  - Write
  - Bash
  - Glob
  - Grep
---

# Whetstone

You are running the Whetstone Loop: building a skill that sharpens itself. The skill file is the asset. The conversation is throwaway. Your job is to drive one turn of the crank — **Load → Run → Grade → Ask → Fold → Report** — without skipping steps.

## Goal

Drive a single iteration on a target skill so that running it again on the same input would produce a better result with fewer questions. Leave the skill in a strictly-better state, with at least one open question seeded for the next turn.

## Inputs you must identify before running

1. **Target skill file.** A `skill.md` (or equivalent guidance file) the user is iterating on. If none exists, your first job is to distill the prior conversation into one before continuing.
2. **Test input.** A real task the skill should handle. Refuse to start the loop without one — ask the user to paste a real example.
3. **Turn budget.** How many self-grade/improve cycles before stopping. Default: 2. Hard cap: 3.

## Hard rules

- **Never** edit the target skill file before **Fold**. Self-improvement during **Grade** happens in output drafts only; the skill file changes only after the user answers the **Ask** questions.
- **Never** ask the user open-ended questions like "what should I change?" Constrain to A/B/C or yes/no. Each question must name the trade-off explicitly, including the consequence of each option.
- **Never** mark the skill "done." Always leave at least one entry under `Open questions` so the next turn has somewhere to push.
- **Always** announce each step in one sentence *when running interactively* so the user can interrupt before you commit to a path. When the run is captured as a written artifact (a turn doc), step headers replace the inline announcement — do not duplicate.
- **Always** show a diff (or quoted before/after) when editing the skill in **Fold**.
- **Ask questions target the target skill only.** Surface ambiguities the *target* skill did not specify. If you notice gaps in Whetstone itself while running, hold them — they only get raised when Whetstone is explicitly the target of a meta-run.

## Soft rules

- Prefer 3 sharp questions over 8 vague ones in **Ask**.
- Prefer rewriting an existing rule with reasoning attached over adding a new rule with no `why`.
- Default to keeping the skill under 200 lines. If it grows past that, surface a split-vs-refactor question.
- Default test input picks: something small enough to fully grade in under a minute.

## The loop

Execute these steps in order. Do not skip.

### 1. Load — locate or distill the skill

If a target `skill.md` exists, read it. If not, read the recent conversation and distill it into a draft `skill.md` using the structure: `Goal` / `Hard rules` / `Soft rules` / `The loop` (or process) / `Examples` / `Edge cases` / `Open questions`. Save it before continuing.

### 2. Run — apply the skill cold

Apply the skill to the test input exactly as written. Produce output. Show it to the user verbatim. Do not silently improve it here — **Run** is the cold-start baseline.

### 3. Grade — self-grade and improve

List every rule from `Hard rules` and `Soft rules`. For each, mark the **Run** output `pass` or `fail` and quote the offending span. Rewrite the output to address every `fail`. Re-grade. **Stop the moment every rule passes** — do not keep polishing for vague "quality." If the rule-passing output still feels weak, that is signal the rules are too loose; capture the felt-weakness as an **Ask** question instead. Halt also when the turn budget is exhausted. Show the final output and the final grade.

### 4. Ask — surface ambiguities as A/B questions

Identify 2–4 decisions you made during **Grade** that the skill did not fully specify. For each, write a question with named options and consequences:

```
Q1: <what was ambiguous>
A) <option A> — <consequence>
B) <option B> — <consequence>
```

Stop and wait for the user to answer. Do not proceed to **Fold** without answers.

### 5. Fold — bake answers into the skill

Edit the target `skill.md` so that re-running it on the same input would produce the user-preferred output without further questions. Update `Hard rules`, `Soft rules`, `Examples`, and `Open questions` as appropriate. Show the diff. Do not edit anything outside the skill file.

### 6. Report — summarize and stop

Do not start another turn unless the user asks. Print a short report: turns taken, rules added, rules changed, open questions remaining, suggested next test input.

## Examples

### Example: improving a `pr-title` skill

User has `pr-title.md`. They give you a diff as the test input.

- **Run** output: `Updated the auth middleware to handle expired tokens`
- **Grade**:
  - Rule "imperative mood" — `Updated` **fail** (past tense). Rewrite: `Update`.
  - Rule "≤50 chars" — line is 52 chars **fail**. Rewrite tightens to 43.
  - Final: `Update auth middleware for expired tokens` — all rules pass.
- **Ask** questions:
  - `Q1: Refactors with no behavior change — prefix with "refactor:" or use a plain verb? A) refactor: prefix — clearer signal in changelogs. B) plain verb — shorter, matches existing repo style.`
  - `Q2: PRs touching two unrelated areas — name both or pick the dominant? A) name both — accurate but long. B) dominant area only — punchy but loses information.`
- **Fold**: user picks A, B. Add `Hard rule: Refactors use refactor: prefix.` Add `Hard rule: For mixed-concern PRs, use the dominant area only; mention the secondary in the body.` Remove these from `Open questions`. Add a new `Open question: How to title revert PRs.`

## Edge cases

- **Skill conflicts with itself.** Two rules disagree on the same input. Surface the conflict as an **Ask** question; do not silently pick one.
- **User gives no test input.** Refuse to start. Suggest the user paste a real example. Do not invent test inputs.
- **Grade plateau on turn 1.** If the first output passes every rule cold, the skill is too loose. Force an **Ask** question targeting whatever felt arbitrary while you were producing the output. **During Fold, the answer parks under `Open questions`; do not promote it directly to a Hard/Soft rule.** Promote to a rule only after the same ambiguity surfaces on a second or third test input — one sighting is anecdote, two is pattern, three is rule.
- **Skill grows unwieldy.** If the skill exceeds ~200 lines or has overlapping rule clusters, ask the user: split into multiple skills (A) or refactor in place (B)?
- **User pushes back on a Fold edit.** Treat their pushback as a fresh **Ask** answer; revise the diff before applying it.

## Open questions

- How to handle conflicting reasoning when the user wants both options preserved — branching rules inside one skill, or fork into two skills?
- How to make a skill discoverable and usable across a team without becoming bureaucratic.
- When to retire a skill versus keep iterating on it.
- How to detect "skill rot" — when accumulated rules contradict each other and the skill needs a rewrite, not a tweak.
- **Promotion threshold.** Q3 (v0.2.0) set the policy "park first, promote after 2–3 sightings." Threshold is fuzzy — exactly how many sightings, and does the model track them automatically across turns, or does the human decide?
- **Boundary between target-skill gaps and Whetstone-skill gaps.** Q2 (v0.2.0) ruled "target only" during normal runs, but the model still has to classify ambiguities at the moment they arise. Heuristic for that classification not yet specified.