fix-with-spec

Files (2)

• SKILL.md
• trigger-eval.json · evals/

SKILL.md (first lines)

# /fix-with-spec — plan, approve, then keep OpenSpec specs consistent, fast

Your one job: make the fix and leave the capability's spec **consistent** with it, with
the **least ceremony that fits the risk** — and **never touch code or specs until the
user has approved a plan**. **Fix time matters — do not spawn OpenSpec ceremony you don't
need.** Most fixes need no spec change at all.

This skill is **repo-agnostic**: it does not assume a particular OpenSpec schema, area
layout, or sync script. It discovers all of that from the OpenSpec CLI at runtime
(`openspec schemas`, `openspec list --specs`, `openspec instructions …`). That is what
lets the same skill serve a project on the stock `spec-driven` schema and one on a
bespoke, area-aware schema with a custom sync helper.

The invariant that constrains you in **every** OpenSpec repo: the applied specs under
`openspec/specs/**` are a **generated mirror of change deltas** — never hand-edit them. A
spec changes only by putting a delta inside a *change* and running that schema's apply
step (plain `openspec archive`, or a schema-bundled sync helper + archive — the schema's
`openspec schemas` description tells you which; see below).

## Hard dependencies — invoke, don't rebuild

This skill orchestrates three skills. When the flow reaches their job, **invoke them**; do
not re-implement their logic inline.

- **`diagnosing-bugs`** — reproduce-and-locate for anything whose root cause isn't obvious.
  Ships in this same plugin, so it travels with `/fix-with-spec` wherever it's installed.
- **`tdd`** — the red→green discipline for the actual fix. Also bundled in this plugin.
- **`/opsx:propose`** — the OpenSpec project's own proposal workflow, for net-new
  capabilities or broad contract changes. This one is **not** bundled — it belongs to the
  OpenSpec-managed repo. When the spec-path decision lands here, you **stop and hand off**
  to it rather than treating the work as a fix.

If one of these isn't present in the session, say so in the plan instead of silently doing
its job by hand — a missing skill changes the risk picture the user is approving. (The
likely gap is `/opsx:propose`, since the bundled two travel with this skill.)

## The gate: plan before you touch code

**Every run passes through this gate before any edit — even a one-liner.** The plan is
lean (two lines), so a trivial fix costs one approval, not ceremony. The point is to get
sign-off on the skill's one real judgement call — the spec path — *before* anything
changes.

1. **Investigate read-only.** Plan mode forbids edits — lean into that. Reproduce or
   locate the bug (running existing tests is fine; reach for `diagnosing-bugs` if the
   cause is unclear), locate the capability (below), and make the spec-path decision
   (below). No test-*writing* yet — authoring a repro test is an edit, so it waits for
   approval.

2. **Present the lean plan and wait for approval.** Use plan mode's native approval gate:
   write the plan, then call `ExitPlanMode` (enter plan mode first with `EnterPlanMode` if
   you aren't already in it). Keep it to two lines:
   ```
   Fix:  <what changes + file>
   Spec: <No change | surgical delta on <active-change> | minimal/full new change via <schema>> → <area-or-cap>
   ```
   `ExitPlanMode` *is* the approval — don't ask "is this plan OK?" some other way.

3. **On approval, implement** (below). If the user redirects, fold it in and re-present
   the plan; don't start editing until they approve.

## The spec-path decision

This is what you settle in step 1 and what fills the plan's **Spec:** line. State your
answer + the capability; proceed unless it's genuinely ambiguous.

**Does this fix change what a spec SAYS** (a capability's documented behavior or contract)?

| Spec change? | Who owns the capability | Plan's Spec line → action |
|---|---|---|
| **No** | — | **No change** — most fixes land here; don't manufacture spec work. |
| **Yes** | an active change | **Surgical delta** — patch that change's delta + `tasks.md` in place; it carries itself forward (you don't archive it; its own apply implements). |
| **Yes** | archived only — fix is small / low-risk / obvious | **Minimal new change** *(default)* — scaffold a change on the right schema, author **only the delta**, apply, archive. |
| **Yes** | archived only — **+ an escalation trigger** | **Full new change** — run the schema's artifact flow to persist the audit trail (proportionately). |
| **Net-new capability / broad contract change** | — | **Stop → `/opsx:propose`** — that's not a fix; say so in the plan instead of editing. |

**Answer the spec-change question *before* the ownership question — and don't pollute an
unrelated active change.** The "active change → surgical delta" row assumes the active
change is the *natural home* for your fix. Often it isn't: a change can own a capability's
spec while being about something entirely different (an `increment/archive` change that
happens to own `pasture-management`), or the capability may have **no applied spec yet** —
it exists only as that in-flight change's delta. Before reaching for surgical-delta,
confirm your fix genuinely sits within that change's scope. If it doesn't, grafting your
scenario onto it pollutes someone's in-flight work — prefer **No change** (when no spec
actually asserts the behavior you're fixing), or defer a standalone change until the
in-flight one lands. The point of asking "does a spec *say* this?" first is exactly to
avoid being railroaded into editing the wrong change.

**Escalate minimal → full only if a trigger applies (otherwise stay minimal):**
- a real **bug / regression / incident** where persisting reproduce→test evidence + a
  named regression test matters (security, data integrity, a prod incident, a
  hard-to-reproduce flake);
- the fix needs a **migration or rollback** plan;
- it **spans multiple capabilities** or has non-obvious design trade-offs worth recording;
- **root cause is uncertain** and reproduce-before-fix discipline de-risks it.

Default is **minimal**. Escalating without a trigger re-introduces the ceremony cost this
skill exists to avoid; minimal still *proves* the fix (implement step 1) — it just
doesn't persist the proof as artifacts.

## Discovering schemas and locating the capability (quick, generic)

Don't assume schema names or a particular spec layout — ask the CLI:

- **Schemas available + the project default:** `openspec schemas` lists every schema with
  a description (which is bug-oriented, which is feature/behavior-oriented, which needs a
  bundled sync helper). The project default is the `schema:` key in
  `openspec/config.yaml` (used when you omit `--schema`).
- **Capabilities + their specs:** `openspec list --specs`, then `openspec spec show <id>`
  to read the applied spec. If the repo keeps an area map (e.g.
  `openspec/specs/README.md`), use it as a shortcut — but treat it as a hint, not a
  requirement; the CLI is the source of truth.
- **Active changes (ownership):** `openspec list` shows active changes. A change owns a
  capability if it carries a `specs/.../<cap>/spec.md` delta for it (read its
  `.openspec.yaml` for the schema); then it's the **surgical-delta** path. Otherwise only
  the archived mirror owns it → **new change** path.

**Routing a new change to a schema:** match the fix to the schema whose description fits —
a bug-oriented schema if the repo has one, otherwise the project default for an intended

From Kotivskyi/skills, MIT.

More from Kotivskyi/skills