Frame Change

Frame Change

Turn a raw idea into an agreed shape ready for spec work, through dialogue — not code.

Where this sits: frame-change → (specify-behavior → design-solution → plan-tasks) → build-in-waves. You are at frame-change — the first stage. Which later stages run is decided by the tier in step 5 (tier 0 skips straight to test-first; tier 1 stops at a mini-spec in specify-behavior; only tier 2 walks the full triad). Each of those stages owns its own todo list and creates it when invoked — do not pre-load their steps into this skill's list.

Shaping a new feature or project (nothing spec'd yet) is this skill. A small in-scope change to an already-shipped, spec'd feature is amend-feature instead — it reads the existing spec and routes the change to the light lane, escalating back here only when the change is genuinely new scope. If you were handed such a change, hand it to amend-feature.

"Too simple to need a design" is the trap

Small requests are exactly where unexamined assumptions burn the most work, because nobody bothered to check them. The output can be tiny — a tier decision and three sentences — but the process runs every time.

Red flags — stop and return to the checklist if you notice yourself: opening an editor to "just try something"; running a generator/scaffolder; answering your own open question instead of asking; presenting one approach as the only option; drifting from interviewing into implementing; running a reverse-track / catalog-staleness check, or inventing a reconcile-features call — catalog currency is /map-features, which the user runs; pasting the full catalog into context because it “might be useful.”; narrating step 1 before the six-step list is visible.

Checklist

Todos first — GATE. The very first action of every frame-change — before you read CONTEXT.md, dispatch a scan, or ask a single question — is to put this skill's six steps on a visible list, one item per checklist step (1–6):

• The harness exposes a todo / task-list tool → create the list there.
• It does not → write the six steps as a checklist in your first reply, and restate it with each item's status at every step boundary.

The gate closes on the same observable either way: the list exists and the user can see it. A harness without a todo tool is a rendering difference, never a reason to carry the six steps in your head. This fires for EVERY request, no matter how simple it looks — the HARD-GATE above is what you must NOT do; this is what you MUST do first. The list holds this skill's six steps only; do not add downstream stages (specify-behavior, design-solution, plan-tasks) — each creates its own list on handoff. Do not proceed until the list is visible, then complete the items in order, checking each off only when its Done when is met.

Right-size with an early tier read. Once step 1 gives you the context, make a provisional tier call:

• Plainly tier 0 — a typo, recolor, label, or copy edit, with no behavior change, no unconfirmed assumption, and nothing to guard → brief step 2, skip steps 3–4, then step 5.
• Anything else — a behavior change, an unknown, or a real design choice → the full path.

Provisional means provisional: if step 2 surfaces any of those, it was never tier 0 — escalate to the full path.

1. Explore project context

Read CONTEXT.md (use its vocabulary from here on).

Do not paste docs/specs/INDEX.md into context — even when the file is open or “only” dozens of rows. Load load-subgraph’s catalog-query.md and run it as the one home (mode, query recipe, context caps, exact CODE lookup), including any active OBS already indexed. Read the Project posture in docs/agents/project.md when present — it right-sizes the whole interview. WHEN Project posture or ## Team is present in that file, read project-posture.md beside this file and follow it exactly for how Delivery intent, Compat obligation, and Team band/packaging are derived. When the posture section is absent, do not assume one — proceed without right-sizing; nested clarify-decisions coverage stays OFF until written Production and Cut Released/Scaling/Maintenance (plus its surface latch). Empty roster + blank override, or missing Team: do not invent a team and do not hard-fail. Band never changes tier rules or Iron Laws. When docs/product/vision.md exists, read it too and — once you grasp the idea — state whether it falls inside the stated product scope (an out-of-scope idea is worth surfacing before any spec work); if it does not exist, skip this, the layer is optional.

Product context docs (optional)

WHEN the idea touches users, success criteria, or product principles, read product-context.md beside this file and follow it exactly (paths, validators, and the consult-recipe's authority / no-op / suggest rules).

For anything heavier — code, docs, and recent commits near this idea — dispatch a scan subagent that writes a findings digest (what exists near the idea, the files and seams it touches, applicable constraints — findings, not file dumps) to .skills/<CODE>/scan.md (or .skills/_pending-<slug>/scan.md before CODE), returning only that path; work from the digest, not raw files. No subagents here? Read the few relevant files directly. If docs/agents/project.md or these files are missing, say so, suggest configure-repo, and continue with what you have.

The scan digest (or your direct read) MUST include a Blindspot section: territory-specific traps, historical constraints, and questions a newcomer would not know to ask — grounded in this repo, not generic advice. When the user signals low familiarity with the module or domain, surface that Blindspot list to them before the first preference question in step 2.

Guarantee check — REQUIRED before a safety word reaches the user, and a word already in their ask counts. Safe, atomic, idempotent, exactly-once, never double-, ordered, unique — inheriting one from the request as settled is the same claim, made silently. For each: name the failure it must survive and the file:line that makes it survive; take the failure this code path makes observable (a timeout, a crash mid-write, a retry, a second caller) and call the others untested. No line → say unverified as you state it, and log a known unknown. Describing a mechanism is not checking it — "the catch block releases the key on failure, so retries are safe" is true about what the code does and false about what it survives. Three runs quoted idem.release(key) from that block, called it "the template", and promised "never double-refunds" — while a PSP timeout takes the branch, drops the key, and charges again.

Then check whether the idea already exists. REQUIRED SUB-SKILL: use load-subgraph with the idea's key terms and any scan candidate paths (query subgraph or neighbors as fits) so P0 term seeds and P1 path-derived structure both contribute. Present neighbor cards from schema 1.1 fields (path_evidence, term_evidence, via_traces); surface owns_coverage. Grounded claims (one home): follow skills/execution/load-subgraph/references/grounded-claims.md for every conclusion from the package. Hold a valid retrieval package for nested clarify-decisions reuse. Done when: neighbor cards plus OWNS coverage are stated, or an explicit "no overlap" (or no specs) with emptiness/coverage stated per grounded-claims.md.

Knowns inventory (REQUIRED before step 2). Write four short bullets the rest of the chain can reuse (chat is fine; optional .skills/<CODE>/knowns.md (or .skills/_pending-/knowns.md before CODE)):

• Known knowns / locks — hard constraints and outcomes that are settled (must-keep behaviors, posture constraints, explicit non-negotiables).
• Known unknowns — open questions that need research, run-spike, or a user decision.
• Unknown knowns — taste or standards the user can recognize but not yet specify (route via run-spike or references, not more prose questions alone).
• Assumptions (not locks) — solution shape the user proposed that is still a hypothesis until checked against territory (codebase, APIs, history). Never promote an assumption into a requirement SHALL until it is chosen as a lock.

Pathfind knowns (when present). WHERE the user points at a pathfind knowns package (.skills/pathfind/**/knowns.md) or an open pathfind map, seed this inventory from that package's locks and known unknowns. Do not re-open closed pathfind decisions unless the user reopens the ticket. Pathfind knowns do not replace Blindspot or a brownfield territory scan — still require Blindspot awareness on brownfield work.

Done when: you can state in one paragraph what the project is, what already exists near this idea, and which glossary terms apply — and you have stated which existing features share this idea's surface and how the new idea differs (citing feature codes), or that no existing feature shares its surface — and the Knowns inventory and Blindspot list exist.

2. Interview

This remains frame-change step 2 — not a stage write-handoff and not a new skill session. Apply the clarify-decisions protocol for the single question channel; keep this skill's todo list live; do not open a competing list or re-announce that you are "switching to clarify-decisions."

Protocol (always): apply clarify-decisions for this step. Do not invent a thinner interview here — card recipe, stop rule, and Production coverage gate live only there.

REQUIRED SUB-SKILL: use clarify-decisions (channel, open-set, cards, coverage gate + optional production-coverage.md, close package, team-band, no-enact, nested todos). Load once when this step starts if not already in context; stay on this checklist.

(Provisional tier 0? Mark the nested interview brief / tier-0 so coverage stays OFF. Confirm problem, one constraint, and must-keep-working in a question or two — not a full tree — then step 5 if nothing new surfaces.)

Keep define-domain active as a passive side effect for the whole interview: record a term to CONTEXT.md the instant it settles and cross-reference the code — but it does not open a second question channel. A term that needs the user (a challenge, a disambiguation, an edge-case probe) becomes the next question in the interview's one-at-a-time stream, never a competing interruption (REQUIRED SUB-SKILL: use define-domain).

Before drilling into details, check scope: if the request spans multiple independent subsystems, stop refining and decompose first (step 5).

Done when: the open set is empty of high-blast judgment calls and the clarify-decisions close package is confirmed.

3. Detour when a question needs evidence, not opinion

Full-path only; tier 0 skips this.

Some questions can't be answered by preference. When the honest answer is "we'd have to check":

• Facts about external systems, APIs, libraries, or standards → REQUIRED SUB-SKILL: use research (primary sources, cited note — it reaches for the Context7 MCP for current, version-accurate library facts rather than training-cutoff memory).
• "Does this model/flow actually feel right?" → REQUIRED SUB-SKILL: use run-spike (runnable throwaway answer).

Return to the interview with the evidence and put the decision back to the user.

Done when: no pending question is being answered by guesswork.

4. Propose approaches

Full-path only; tier 0 skips this.

Present 2–3 genuinely different approaches with trade-offs. Lead with your recommendation and why. YAGNI-prune every option. The user picks.

Done when: the user has chosen an approach (possibly a hybrid).

5. Decide the ceremony tier — out loud

State the tier explicitly and why:

If the work spans multiple independent subsystems, decompose it here: name the sub-features, their relationships, and build order. Each sub-feature gets its own full spec cycle.

Two or more sub-features means the decomposition gets written down before you go any further. REQUIRED SUB-SKILL: use plan-milestones to persist every sub-feature as a ROAD-N item — appending to docs/roadmap/INDEX.md when it already exists, authoring it when it does not. A sub-feature you are not building first is deferred to a later milestone, not declined: an Out-of-Scope line or an ADR records a rejection, and a decomposition is not a rejection. Then continue with the first item only.

Done when: you have said "This is tier N because ..." and, if decomposed, every sub-feature exists as a ROAD-N in docs/roadmap/INDEX.md and you have named which one goes first.

6. Terminal state

• Tier ≥ 1: REQUIRED SUB-SKILL: use specify-behavior. This is the ONLY exit. Do not write code, do not scaffold, do not invoke any implementation or design skill directly — requirements come first and carry their own approval gate.
• Tier 0: state the tier, then REQUIRED SUB-SKILL: use test-first.

Done when: specify-behavior has been invoked (tier ≥1) or the tier-0 write-handoff is stated.