greprag 5.42.3 → 5.43.1

package/skill/mechanic/docs/skill-fix-conventions.md

@@ -0,0 +1,58 @@
+# Skill-Fix Conventions
+
+**Status:** SHIPPED leg of the skill-tuning reflex (`docs/mechanic-skill-tuning.md`). The portable recipe set the reflex applies when a skill exhibits friction. Ships **with greprag** (bundled into the mechanic skill package, mirrored to `~/.claude/skills/mechanic/docs/`) so the fixer works for any user — it does **not** depend on `/skill-optimize` being installed. `/skill-optimize` remains the richer interactive tool; this is the minimal portable subset the reflex carries.
+
+## What this is for
+
+The skill-tuning reflex injects a directive when a skill under break-in loads. The old directive said "watch your execution, emit a SELF-TUNING block, propose a fix" — vague (it pointed at the *run*, not the *skill*) and propose-only (no edit ever landed). This doc replaces that with **six locatable skill defects**, each mapped to one concrete edit. The reflex's loop is: **detect a defined friction → locate it in the skill's SKILL.md → apply the fix per the matching recipe → show the diff for one accept/revert.**
+
+A friction that doesn't match one of the six below is **not auto-fixable** — log it (`greprag fix log "<obs>" --scope skill:<name>`) and keep working. Do not invent edits outside these recipes.
+
+## The two edit primitives (skill-optimize vocabulary)
+
+Every fix below resolves to one of two inline forms:
+
+- **Convention A — one-liner + link.** Reference material (facts, recipes, paths). Inline: one sentence naming what the linked doc holds + the path.
+- **Convention B — loud trigger + inline rule + link.** A proactive-fire rule with no external trigger. Three parts: (1) interrogative intent-catch — `ABOUT TO <do X>?` names the *moment*, not the topic; (2) hard stop — `STOP —`; (3) the inline rule, complete enough to comply without opening the link. A flat `IMPORTANT: do Y` reads as wallpaper and gets skipped — the interrogative + hard stop is what catches the model mid-generation.
+
+## The six frictions → six fixes
+
+Each: **signature** (how it shows up in the run) · **location** (where it lives in SKILL.md) · **fix** (the exact edit).
+
+### 1. mis-route
+- **Signature:** the skill fired for a task outside its lane, OR you reached for it by an obvious phrase and it didn't trigger.
+- **Location:** the `description` / `Use when:` trigger list, or the `NOT for:` boundary.
+- **Fix:** add the missing trigger phrase to `Use when:` (verbatim, the phrase you'd actually type), OR add/sharpen a `NOT for:` line naming the lane it wrongly claimed. One phrase per defect — don't pad the list.
+
+### 2. wrong-altitude
+- **Signature:** the skill did work it should have delegated (implemented inline when it should hand to a chip; drafted when it should route to a leaf), or the reverse.
+- **Location:** the handoff / out-of-scope / "Related skills" section.
+- **Fix:** add a handoff line or out-of-scope row naming the correct delegate and the trigger to route there (`X → hand to /<delegate>`).
+
+### 3. flattened-relay
+- **Signature:** the skill made you summarize/paraphrase content that should pass through verbatim (or forced verbatim where a summary was wanted).
+- **Location:** the output-shape / relay rule.
+- **Fix:** add a Convention-B rule pinning relay fidelity — `ABOUT TO SUMMARIZE <X>? STOP — relay it verbatim; <why>.`
+
+### 4. wallpaper-rule
+- **Signature:** a real rule in the skill got skipped because it's a flat `IMPORTANT:`/prose imperative the model read as decoration.
+- **Location:** the rule's existing inline form.
+- **Fix:** rewrite that rule in place to Convention B (interrogative intent-catch + `STOP —` + the inline rule). Same content, fingerprint that catches the model in the act. Don't add a new rule — convert the existing one.
+
+### 5. stale-reference
+- **Signature:** a path, command, or name in the skill 404'd, errored, or pointed at a renamed/removed thing.
+- **Location:** the reference itself (a path, a command, a product/feature name).
+- **Fix:** repoint to the live path/name. Verify the new target exists before writing it (`test -f`, or confirm the rename in `docs/naming.md` for greprag surfaces). If the reference is wholly dead, remove it.
+
+### 6. missing-rule
+- **Signature:** you hit a gotcha mid-run that the skill should have warned about but doesn't.
+- **Location:** absent — a gap.
+- **Fix:** add a new Convention-B proactive-fire rule at the spot in SKILL.md where the agent would meet the gotcha. Keep it to the interrogative + hard stop + one-line rule; link a doc only if a full procedure exists.
+
+## Guardrails
+
+- **One friction, one edit.** If a run surfaced two defects, make two separate edits, each shown for its own accept/revert. Never batch.
+- **Apply + show diff.** Make the edit, then show the unified diff and stop for one accept/revert. (This is the operator-chosen gate; the Mechanic "always confirm" rule still holds.)
+- **Bundled skills:** if the target is a greprag bundled skill, author the edit at `packages/cli/skill/<name>/` — never the `~/.claude/skills/<name>/` install artifact (it's overwritten on the next `init`). See greprag `CLAUDE.md`.
+- **Line budget:** a fix must not grow SKILL.md without adding a real proactive-fire rule or per-task step. Converting wallpaper → Convention B is net-neutral or smaller; mis-route adds at most one line.
+- **Out of taxonomy → log, don't improvise.** Anything not matching the six is `greprag fix log`-only.