reframe

name	reframe
description	Re-baseline a jig corpus onto a moved load-bearing reference by drafting a keystone ADR and an affected-artifact disposition manifest. Use when a vendor/API contract moved and specs and decisions must be re-anchored. Auto-triggers when you say reframe onto this, we changed direction, the design moved, or re-baseline the project; invoke explicitly as `/jig:reframe`. Defers to any other installed skill whose description identifies it as handling project re-baselining or migrating onto a new reference. Does not defer to the generic built-in. Do not use for adopting jig (use `/jig:migrate`), cleanup against a fixed reference (use `jig:refactor`), changing one decision (use `adr.py supersede`), or cross-artifact drift detection (use `/jig:analyze`).
user-invocable	true

Spec 067 introduces this skill; ADR-0024 decides its shape. Reframe is a lightweight correction capability over the lifecycle spine (ADR-0023 §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 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) — 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): it logs only contested assumptions, never settled premises. A dead design that was settled truth never appears there — settled premises are invisible to the ledger for the same reason they silently steer the model: they are unquestioned ground. Scanning the ledger would structurally miss the exact thing a reframe must catch.
• Not a built corpus-walker. There is no detection engine, no references: frontmatter tagging, no spec 024-02 corpus-walking helper. Those are parked behind triggers T1/T2/T3 (ADR-0024 §7). The read is the model's judgment over Read — its completeness is the binding risk the coverage floor surfaces (below).

The keystone reframe-ADR

Reserve and scaffold the keystone ADR through the real ADR lifecycle so it inherits the frame-critique accept gate:

python3 "${PLUGIN_ROOT}/skills/adr-workflow/adr.py" new reframe-onto-<slug>

Then author its body:

• Declare the new reference authoritative as of <date>.
• Supersede the old premise (name it; link the decisions/prose that encoded it).
• Carry the re-baselining manifest (below) and the coverage floor (below).

Because the keystone ADR rides adr.py, its Proposed→Accepted flip is frame-critique-gated (probed: adr.py's _gate_frame_critique() refuses accept without a passing verdict; new ADRs are stamped frame_review: true). This is load-bearing: the coverage floor is human-confirmed at that gate — the natural checkpoint for "did the read miss anything?"

The re-baselining manifest

A table of every affected artifact, each assigned a deliberate disposition — no TBD. retire-draft items are surfaced first (future-work drafts on the dead premise mint dead-premise work; kill them before anything builds on them).

Net-new forward work the reframe spawns — specs/ADRs the new reference reveals that did not exist before, distinct from fixing an existing artifact — is recorded in a separate ## Emergent work section, not forced into a disposition row (a disposition is the fate of an already-affected artifact; spawned work has no prior artifact to dispose of).

Disposition vocabulary

Each disposition routes to an operation that already exists (ADR-0024 §3):

Disposition	Meaning	Routes to
reaffirm	premise survives the new reference	refresh last_verified + note the reframe
amend	closed record, still valid, needs a pointer	## Amendments (ADR-0010)
supersede	decision now wrong	adr.py supersede / superseding spec
retire-draft	future-work on the dead premise	DEFERRED or discard — do first
retrofit	shipped code must change	a slice in a retrofit spec /jig:reframe mints via workflow.py new (see Retrofit spec drafts)
rewrite	live, non-record prose whose framing must change (not a closed record → not amend; not a decision → not supersede; not code → not retrofit)	rewrite in place, citing the keystone ADR

The two-level coverage floor

The manifest's coverage statement is not free text — a bare "here's what I scanned" note is checked against nothing, so a confident narration of a partial scan reads as complete. It is a two-level coverage floor (ADR-0024 §2–§3):

• Level 1 — whole corpus, class-level. Walk the corpus's deterministically-listable top-level artifact classes and mark each scanned or excused (reason):

  • docs/decisions/ (ADRs)
  • docs/specs/ (specs + slices)
  • live-prose docs under the docs root (product-vision.md, architecture.md, workflow.md, README-style guides, roadmap, glossary)
  • skills/*/SKILL.md
  • the root primer(s) (AGENTS.md / AGENTS.md)
  • README

  L1 covers the authority-bearing corpus — decisions, specs, and the prose / skill contracts that encode premises — not the code tree: shipped code that must change is dispositioned retrofit and handled by a retrofit spec, not scanned by the floor. L1 makes a whole class silently dropped impossible-to-hide: an omission requires actively writing skills/: not scanned, which is visible. (This is the miss that bit the n=2 servo reframe, whose read covered only docs/ + README and silently skipped skills/.)

• Level 2 — artifact-level, within touched classes. For each class the reference actually touches (the classes the keystone supersedes into), enumerate the artifacts within and state the method by which you decided which encode the dead premise — so the manifest's disposition rows are the output of an explicit within-class read, not a hand-waved "class scanned." L2 confronts the intra-class miss — the motivating Android-design failure, where dead-premise files lived inside docs/specs/ and docs/decisions/ entries a class-level floor would mark scanned.

State the overall method and the residual uncertainty. Say plainly that the floor reduces and surfaces the enumeration risk — it does not eliminate it. Genuinely-open residuals (own them, don't hide them):

• a class wrongly judged untouched gets only L1, so an intra-class miss there survives;
• even within a touched class the read can miss an artifact;
• a human can rubber-stamp a weak excused.

All three are backstopped by T1's two-pronged evidence (ADR-0024 §7): the accept-time floor or post-reframe discovery — a later session that finds a surviving dead-premise artifact inside a class the manifest marked scanned un-parks systematic detection. This is the honest fallback, not a completeness claim.

Maintenance note — the L1 class list is jig-corpus-shaped. The top-level classes above match jig's own corpus layout. If a downstream project grows a new top-level artifact class this list doesn't name (or uses a configurable docs root), extend the L1 walk to name it — otherwise that class is invisible to L1 (the whole-class-drop failure moved up one level, into the template). This is a foreseeable maintenance seam, adjacent to the T2 corpus-growth trigger; written down here rather than left silent, per this skill's own "omissions must be visible" ethos.

Retrofit spec drafts

For every retrofit disposition in the manifest, /jig:reframe also mints a retrofit spec draft — the shipped-code change the reference forces, queued in the spec lifecycle rather than left for the session to hand-author. For each retrofit row:

1. Reserve a spec via workflow.py new:

   python3 "${PLUGIN_ROOT}/skills/spec-workflow/workflow.py" new \
     retrofit-<artifact>-onto-<reference-slug>
   

   Slugify the substituted parts — lowercase, [a-z0-9-] only, no --; workflow.py new refuses a malformed slug.

2. Goal the draft on the reference. The draft's Overview / first-slice goal reads "bring <artifact/code> in line with <reference>", naming the moved reference explicitly — so the retrofit's purpose is unambiguous and measured against the new authority, not the dead premise.

3. Anchor ## Assumptions on the new reference. The retrofit spec's ## Assumptions cite the new reference as the authority the work is measured against, so a future frame-critique on that spec is anchored correctly (ADR-0024 §3) — not against the premise the reframe just retired.

4. Close the loop — no retrofit disposition silently dropped. Every retrofit row maps to a drafted spec or to an explicitly-recorded reason it was not drafted surfaced to the user (e.g. deferred — <why>). Update the keystone manifest to link each retrofit row to its drafted spec number, so the disposition→draft mapping is complete and visible — the same "omissions must be visible" ethos as the coverage floor.

The retrofit specs then ride the normal review-gated spec-workflow lifecycle: /jig:reframe drafts them, a competent session implements them. (This mirrors the keystone-ADR flow — reframe reserves + drafts through the real lifecycle so the spawned work inherits its gates for free.)

No .py helper

Like /jig:clarify and /jig:explain, this skill ships no helper script. The only determinism it needs runs through existing tooling:

• reserve the keystone ADR via adr.py new (frame-critique-gated accept);
• reserve retrofit specs via workflow.py new (one per retrofit disposition);
• corpus reading via the Read tool.

There is no reframe.py. The corpus read and the drafting are model judgment; the structural surface (this contract) is what tests assert.

Gotchas

• Draft, don't execute. The skill produces the keystone ADR + manifest + drafts; a competent session executes the dispositions through the existing lifecycles. No heavy auto-execution (ADR-0024 §6).
• No empty keystone ADR. If nothing in the corpus encodes the moved premise, report "nothing to re-baseline" and draft nothing (Q1). If the reference isn't locatable, refuse and ask.
• The coverage floor is the point, not a formality. A weak excused reason or a class you mark scanned without an L2 read reproduces the motivating failure under fresh keystone authority. Make the read honest; the frame-critique gate is where a human confronts it.
• retire-draft first. Dead-premise drafts mint dead-premise work — retire them before anything builds on them.
• Not the ## Assumptions ledger. Never detect the shift by sweeping ## Assumptions — it is risk-gated and blind to settled premises (the exact thing to catch).
• Capability, not a lifecycle member. Reframe adds no transition and no state machine; it orchestrates the ADR/spec lifecycles it spawns. Don't build a reframe.py state machine (ADR-0024 Option B — rejected at n=1).

Relationship to other skills

• adr-workflow (adr.py) — reframe reserves the keystone ADR via adr.py new and routes supersede dispositions through adr.py supersede. The keystone's frame-critique accept gate is where coverage is human-confirmed.
• spec-workflow (workflow.py) — retrofit dispositions become retrofit spec drafts via workflow.py new (slice 067-02); those specs then ride the normal review-gated lifecycle.
• jig:refactor / jig:bug-fix — the behaviour-change lifecycles a reframe spawns work into; reframe is explicitly not a member of their taxonomy.
• /jig:migrate — the sibling entry path (project into jig) that reframe is not; see "When to use vs. when to defer".
• /jig:analyze — audits drift between existing artifacts; reframe introduces a new authority and routes the fallout. Reuse of analyze is conceptual (its six-category model), not code.