reframe

Files (1)

• SKILL.md

SKILL.md (first lines)

> Spec 067 introduces this skill; [ADR-0024](../../docs/decisions/adr-0024-reference-reframe.md)
> decides its shape. Reframe is a **lightweight correction capability over the
> lifecycle spine** ([ADR-0023](../../docs/decisions/adr-0023-lifecycle-family-spine.md) §4),
> **not** a new gated lifecycle member: it has no `transition` and no state
> machine of its own — its arc (recognize → decide dispositions → execute)
> *orchestrates* the ADR and spec lifecycles it spawns, and every gate it relies
> on (the keystone ADR's frame-critique `accept`; the review passes on the
> retrofit specs) belongs to those lifecycles. Shipping as its own skill is a
> user-facing-surface choice — a deliberate, named operation a user reaches for —
> not a lifecycle one.
>
> Like `/jig:clarify` and `/jig:explain`, reframe is a **judgment skill** — it
> ships **no `.py` helper**. The determinism it needs (reserve the keystone ADR,
> reserve retrofit specs) it borrows from the existing `adr.py` / `workflow.py`
> scaffolding; the corpus read and the drafting are model judgment. Its testable
> surface is **structural** (this SKILL.md's contract: the keystone-ADR-via-
> `adr.py new` flow, the disposition vocabulary, the coverage-floor shape, the
> deferral language, registration). The *quality* of the corpus read and the
> honesty of a given coverage floor are judgment, exercised by this prompt and by
> the keystone ADR's frame-critique `accept` gate — not something a unit test can
> assert (the accepted gap for every judgment-only jig skill).

## What this skill does

jig keeps work **consistent with prior decisions**: every spec and ADR is a
durable record, and new work reads the accepted corpus as authoritative. That is
jig's strength — and its blind spot when a **load-bearing premise changes from
outside the system**. A team drops a new design (or contract, or vision) into
the repo intending to retrofit onto it; but the corpus already encodes the *old*
premise as settled truth, so the new artifact enters as an **inert file with no
authority** and the consistency machinery faithfully carries the dead premise
forward — the agent patches at the edges instead of re-baselining.

A **load-bearing reference** is any authoritative external input the corpus is
premised on: a design system, a test-infrastructure choice, a vendor / API
contract, a compliance regime, a target platform, or a product-positioning /
strategic-vision shift. A **reframe** re-anchors the corpus to one that has
*moved*. `/jig:reframe`, given the new reference:

1. **Reads the accepted corpus against the reference** (the corpus read).
2. **Drafts the keystone reframe-ADR** via `adr.py new` — elevating the new
   reference from an inert file to an accepted decision, superseding the old
   premise, and carrying the **re-baselining manifest**.
3. **Assigns every affected artifact a disposition** in that manifest (no `TBD`),
   each routing to an operation that already exists.
4. **States a two-level coverage floor** — what corpus was scanned, at what
   granularity, and what was *not* — so a partial read is visible at the ADR's
   `accept` gate rather than silently carrying a dead premise forward under fresh
   authority.

A competent session, handed the accepted keystone ADR + the manifest, then
executes the dispositions through the existing ADR and spec lifecycles. The skill
**drafts**; the session **executes**. This is a **best-effort correction floor**:
it makes re-baselining *expressible* and human-gated — it does not auto-solve
enumeration completeness (parked, see the coverage floor) and it is not a
silent-drift *detector* (that half is the [067-03](../../docs/specs/067-reframe/slice-03-noticing-nudge.md)
noticing nudge + parked detection).

## When to use vs. when to defer

**Defer to a richer installed skill first.** If another installed skill's
description identifies it as handling **project re-baselining** or **migrating
onto a new reference**, prefer it — jig's reframe is a slim baseline. This skill
does **not** defer to the generic built-in; it only steps aside for a skill whose
description names the re-baselining / reference-migration job.

Sibling jig operations that are easy to confuse with reframe — reach for the
right one:

- **`/jig:migrate`** — brings an existing project *into* jig (adopts an outside
  layout into jig structure). Reframe operates *within* an already-jig project
  whose *premise* moved. Migrate is about the container; reframe is about the
  contents' authority.
- **`jig:refactor`** ([ADR-0019](../../docs/decisions/adr-0019-refactor-workflow.md))
  — changes *structure* while **preserving behaviour** against a *fixed*
  reference. Reframe is the level above: the *reference itself* moved, which then
  *spawns* behaviour-change work (retrofit specs) that flows through refactor /
  bug-fix / spec-workflow. Reframe is **not** a member of ADR-0019's
  behaviour-change taxonomy.
- **`adr.py supersede`** — retires **one** decision with **one** replacement
  (1:1, decision-scoped). A reframe re-baselines a *corpus* premised on the moved
  reference — many artifacts, many dispositions — and mints the keystone ADR that
  makes the new reference authoritative. If the shift really is a single
  1:1 decision change, use `adr.py supersede` directly (over-built otherwise —
  see ADR-0024 Kill criteria).
- **`/jig:analyze`** — surfaces *drift between* existing artifacts (does spec A
  contradict ADR B?). Reframe *introduces* a new authority and routes the fallout.
  Analyze audits the corpus as-is; reframe changes what the corpus is anchored to.

Rule of thumb: **the premise moved → this skill. Adopt a project into jig →
`/jig:migrate`. Behaviour-preserving cleanup → `jig:refactor`. One decision
changed → `adr.py supersede`. Audit alignment → `/jig:analyze`.**

## Inputs — the moved reference

The argument is the **new load-bearing reference**: a path to a dropped-in
artifact (`design/new-system.fig`, `docs/vision-2.0.md`, an OpenAPI file) or a
clearly named reference the user points at.

- **Not locatable → refuse and ask.** If the named reference can't be located
  (no such path, ambiguous name), the skill **refuses** and asks the user for a
  path or a precise identifier. It does **not** guess a reference or draft a
  keystone ADR against a reference it never read.
- **Nothing to re-baseline → say so, draft nothing.** If the corpus read finds
  **no artifact** that the reference actually invalidates (the reference is
  additive, or the corpus never encoded the old premise), the skill reports
  *"nothing to re-baseline"* and drafts **no** keystone ADR. An empty keystone
  ADR is never minted. (Resolves spec 067 Clarification Q1.)

## The corpus read

Given a located reference, the skill **reads the accepted corpus (decisions +
prose) against it** as the basis for drafting — which artifacts encode the *old*
premise the new reference replaces. Two things this read is explicitly **not**:

- **Not a `## Assumptions` sweep.** The `## Assumptions` ledger is *risk-gated*
  ([ADR-0020](../../docs/decisions/adr-0020-spec-frame-hardening.md)): it logs
  only *contested* assumptions, never *settled* premises. A dead design that was
  settled truth never appears there — settled premises are invisible to the

From ramboz/jig, MIT.

More from ramboz/jig