@skhema/cli 0.4.4 → 0.4.5

package/skills/skhema-compose/references/metrics-tree.md

@@ -0,0 +1,101 @@
+# Metrics-tree — outcomes to measures to baselines
+
+Use this when the user has a goal or outcome they care about but no honest way to
+know if they're winning: "we want better retention", "grow the pipeline",
+"improve activation." An outcome you can't observe is a hope. This move connects
+each outcome to something you can actually watch, and to a starting number you
+can compare against — so movement is visible and arguable.
+
+The rule that makes it work: **every outcome needs a measure, and every measure
+needs a baseline.** No measure, and the outcome is unfalsifiable. No baseline,
+and the measure can't tell you if anything changed.
+
+## The three links in each chain
+
+1. **Outcome** — the *thing* you want to be true. State it as a noun phrase, not
+   a wish. "Activated accounts in week one." Not "improve activation" (that's a
+   command; the outcome is the state you're steering toward).
+2. **Measure** — the observable variable that stands in for the outcome. "% of
+   new accounts that complete first key action within 7 days." It must be
+   something you can currently read or start reading. If you can't observe it,
+   it's not a measure yet.
+3. **Baseline** — the starting value, dated. "22%, as of June." Without this,
+   "we hit 30%" means nothing — up from what?
+
+Chain them: **outcome → measure → baseline.**
+
+## The move
+
+### 1. Name the outcome as a state, not an action
+
+Push the user from verb to noun. "Improve onboarding" → "new users reaching
+first value." You're steering toward a state of the world; name that state.
+
+### 2. Ask "what would you watch to know this is happening?"
+
+For each outcome, get one measure — or a small handful. Pressure each candidate:
+
+- **Can you observe it now, or soon?** If it needs instrumentation you don't
+  have, that's a Support Structure task; note it and don't pretend the measure
+  exists yet.
+- **Does it move only when the outcome moves?** A measure that a dozen unrelated
+  things push around is a bad proxy. "Total signups" is a poor proxy for
+  activation — a marketing spike moves it without any activation change.
+- **Can it be gamed without the outcome improving?** If yes, expect it to be.
+  Prefer measures that are hard to move without actually delivering the outcome.
+
+### 3. Get the baseline — the real one, dated
+
+For each measure, ask for the current value and when it was taken. Three cases:
+
+- **Known** — write it with its date. Done.
+- **Knowable but not looked up** — send them to get it. A baseline you'll fill
+  in "later" is a baseline you don't have.
+- **Unknowable right now** — the honest answer is "we don't measure this yet."
+  Then the first initiative is to start measuring, and the baseline is the first
+  reading. Say so; don't invent a number.
+
+A guessed baseline is worse than none — it manufactures false movement.
+
+### 4. Add a leading measure where the outcome is slow
+
+Some outcomes only show up quarters later (retention, LTV). Watching only the
+lagging measure means you learn you failed far too late. Ask: "what moves early
+that predicts this?" Pair a **leading** measure (activation this week) with the
+**lagging** one (retention next quarter). The leading one steers; the lagging
+one confirms.
+
+### 5. Check the tree connects to real decisions
+
+For each measure ask: "if this number moved the wrong way next week, what would
+you do differently?" If the answer is "nothing," the measure is decoration —
+cut it. Every measure should be tied to an action you'd take when it moves.
+
+## What good output looks like
+
+A small set of chains, each complete, leading + lagging where relevant:
+
+> **Outcome:** new accounts reaching first value.
+> **Leading measure:** % completing first key action within 7 days.
+> **Baseline:** 22%, June.
+> **Lagging measure:** 90-day retention of those accounts.
+> **Baseline:** not currently measured → first initiative is to instrument it;
+> baseline = first reading.
+> **If it drops:** we pause feature work and audit the onboarding flow.
+
+Three chains like this beat a dashboard of twenty numbers nobody acts on.
+
+## Failure modes to catch
+
+- **Vanity measures.** Big, always-up-and-to-the-right numbers (total users,
+  cumulative signups) that can't go down and so can't inform anything. Reject.
+- **Outcome = measure confusion.** "Our goal is 30% activation" collapses the
+  outcome (users reaching value) into one measure. Keep them distinct so you can
+  swap a bad proxy without losing the goal.
+- **Missing baseline waved away.** "We'll figure out the baseline later" — no.
+  Either look it up now or make measuring it the first step. Don't proceed with a
+  hollow chain.
+- **Only lagging measures.** All the measures resolve in six months. You've built
+  a strategy you can't steer, only autopsy. Add leading measures.
+- **Measures with no action.** If nothing changes when the number moves, it's not
+  a measure, it's a decoration. Cut it.

package/skills/skhema-compose/references/options.md

@@ -0,0 +1,109 @@
+# Options — compare alternatives as typed judgments
+
+Use this when the user is stuck between paths: "should we build or buy?", "A or
+B or C?", "do we go upmarket or double down where we are?" The trap is that
+options get argued in prose — a paragraph for each, each written to sound good,
+none comparable. This move forces every option through the *same* criteria, so
+the comparison is real and the trade-offs are explicit instead of buried in
+adjectives.
+
+An option set is compared well when a reader can see, for each option, how it
+scores on every criterion, what it costs you, and what evidence backs the score —
+and could disagree with a specific cell rather than a vibe.
+
+## Why prose comparisons lie
+
+Written as paragraphs, each option gets described on the dimensions where it
+happens to look good and stays quiet on the rest. Option A's paragraph talks
+speed; Option B's talks robustness; they never meet on the same axis. The
+decision then goes to whoever wrote the most persuasive paragraph. Typing the
+comparison — same criteria for all, evidence per cell — kills that.
+
+## The move
+
+### 1. State each option as one committable sentence
+
+Each option is a **command** — a course of action you could actually choose.
+"Build our own billing system." "Buy Stripe Billing and integrate it." Make each
+one a single sentence the user would commit to, not a theme. If an "option" is
+vague ("improve billing somehow"), it's not an option yet — it's a goal; send it
+to decompose.
+
+### 2. Fix the criteria BEFORE looking at the options
+
+This is the discipline that makes the whole thing honest. Agree the criteria
+first, with the options out of view, so nobody tunes the criteria to favor a
+pre-chosen winner. Good criteria are:
+
+- **Decision-relevant** — something that would actually change the choice.
+- **Comparable across all options** — every option can be scored on it.
+- **Few** — four to six. More than that and you're hiding the real drivers in
+  noise.
+
+Typical: cost, time-to-value, reversibility, risk, fit with the strategy,
+capability required.
+
+### 3. Score every option on every criterion — same scale, evidence per cell
+
+Build the grid: options as rows, criteria as columns. For each cell, give a score
+(a number, or high/med/low) AND the evidence or reasoning behind it. A score with
+no evidence is a guess typed as a judgment — mark it explicitly as an assumption
+so its weight is visible. Fill every cell; a blank cell is usually the option's
+weakness hiding.
+
+### 4. Name the trade-off on each option out loud
+
+Every option buys something and pays for it somewhere. State both:
+"Build gives us full control and costs two quarters of engineering we'd take from
+the roadmap." "Buy ships next month and locks us to their pricing and limits."
+The point of options is not to find a free lunch; it's to choose which price you
+prefer to pay. If an option looks strictly best on every criterion, you've
+either found the obvious answer or your criteria are missing the dimension where
+it's weak — check the latter first.
+
+### 5. Separate reversible from one-way choices
+
+Flag whether each option is easy to undo or hard. A cheap, reversible option
+that scores second-best is often the right first move — you learn, then choose
+again. A one-way door demands more evidence before you walk through it. Weight
+the scores by this: on a reversible choice, bias toward acting and learning; on
+an irreversible one, bias toward resolving the load-bearing judgments first.
+
+### 6. Surface the load-bearing judgment under the choice
+
+Most option decisions actually hinge on one uncertain judgment about the world.
+"Build vs buy" often reduces to "will our needs outgrow the vendor's product?"
+Name that judgment. Sometimes resolving it decides the whole thing and the grid
+becomes unnecessary — that's a great outcome. Hand it to decompose if it needs
+breaking down.
+
+## What good output looks like
+
+A grid, then a recommendation with its trade-off named:
+
+| Criterion | A: Build | B: Buy | C: Partner |
+|---|---|---|---|
+| Time to value | 2 qtrs *(eng estimate)* | 3 wks *(vendor docs)* | 6 wks *(assumption)* |
+| Cost | High *(2 eng, 2 qtrs)* | Med *(usage fee)* | Low upfront |
+| Reversibility | Low — sunk build | High — swap vendor | Med |
+| Strategy fit | High | Med | Low — off-mission |
+
+> **Recommendation:** B. It's reversible and ships this quarter, buying us the
+> learning to decide whether A is ever worth it. **Trade-off accepted:** vendor
+> pricing risk and a feature ceiling we may hit in a year.
+> **Load-bearing judgment:** will our billing needs outgrow the vendor within 18
+> months? If yes, revisit; if no, B stands. Currently a guess — worth resolving.
+
+## Failure modes to catch
+
+- **Criteria tuned to the winner.** If the criteria appeared *after* someone
+  fell for an option, they're rigged. Set criteria first, options hidden.
+- **Uneven scoring.** Option A judged on best case, Option B on worst. Use one
+  standard for all — same scale, same rigor per cell.
+- **Straw options.** Two real contenders and one obviously bad option added to
+  make a favorite look inevitable. Every listed option should be one someone
+  could honestly defend.
+- **Scores with no evidence.** A full grid of confident numbers, none backed by
+  anything, is prose in a table. Mark unbacked cells as assumptions.
+- **Ignoring reversibility.** Scoring a one-way, bet-the-company choice the same
+  way as a cheap experiment. Always flag which doors swing both ways.

package/skills/skhema-frame/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: skhema-frame
+description: "Use when someone starts a strategy process and can't yet say what it's about — a vague worry, an ambition, or a mandate that needs to become a workable strategic statement. Frames them back to the object they're actually trying to pin down: the challenge, the scope, the guiding policy, the outcome, or a single decision."
+---
+
+# Frame
+
+Someone comes to you with something they can't articulate yet. A worry
+("I think we're falling behind"). An ambition ("we should own this
+market"). A mandate ("the board wants a plan"). None of these is workable
+yet. Your job is not to answer them. Your job is to frame them back to the
+actual object they're trying to pin down, and to help them state it well
+enough that work can start.
+
+Framing is a strategic act, not a warm-up. The statement you settle on
+decides what everything downstream argues about. Get it wrong and every
+later step is precise about the wrong thing.
+
+## The first move: which mood?
+
+Before anything else, find out what KIND of thing they're trying to say.
+Ask, in plain words:
+
+> Are you trying to state something you believe is **true** (a judgment),
+> something you've decided to **do** (a command), or **name a thing**?
+
+Most stuck conversations are stuck because these are tangled — a worry
+that's secretly a decision, a goal that's secretly a complaint. Separating
+them is usually enough to unstick the person, and it tells you which
+capability to run.
+
+| They're framing… | Mood | Route to |
+|---|---|---|
+| The problem that actually exists — a claim about their world | judgment | `references/challenge.md` |
+| What's in and what's out of this piece of work | command | `references/scope.md` |
+| The direction they'll take, the approach they're committing to | command | `references/policy.md` |
+| What success looks like — the state they want to reach | thing | `references/outcome.md` |
+| One specific choice they're stuck on right now | (a choice, not yet made) | `references/decision.md` |
+
+## How to pick
+
+- They're anxious, overwhelmed, or describing symptoms ("sales are down",
+  "morale is bad") → **challenge**. They have a symptom, not a problem.
+  Frame the challenge underneath it.
+- They keep expanding — every conversation adds another thing the strategy
+  "should also cover" → **scope**. Force the in/out line.
+- They have a clear problem but keep restating the goal instead of saying
+  what they'll DO about it → **policy**. Push for a committed direction.
+- They say "success is when…" and it comes out fuzzy, or unmeasurable, or
+  actually a list of activities → **outcome**. Make it observable.
+- They're circling one fork — "should we build or buy", "do we hire now or
+  wait" — and can't move → **decision**. Frame the choice itself.
+
+If they need more than one, do them in this order: challenge first (it
+anchors the rest), then scope, then policy, then outcome. A decision can be
+framed at any point it blocks them.
+
+Don't do their thinking for them. Your questions surface THEIR answer. A
+frame you hand over gets nodded at and forgotten; a frame they arrived at
+under your questioning, they own.
+
+## What "framed" means
+
+A capability is done when the person can say the object in one sentence,
+out loud, without hedging, and a second person would read it the same way.
+Until then, keep probing. Each reference file tells you what good looks
+like for its object and the failure modes to catch.
+
+## Without a live respondent
+
+Run headless, with no one to answer? Don't invent their answers. Make the
+minimal reasonable assumption, mark it in the output as yours ("assumed: …"),
+and list the questions only the owner can settle — what's in scope, what a word
+means, whose dissent to record — at the end instead of papering over them. A
+marked assumption is honest work; a silent one is a guess you built on.
+
+## Sharpen with Skhema
+
+Every object you frame here maps to a typed element in the Skhema method,
+each with an expected grammatical mood — a judgment reads as an indicative
+claim, a command as an imperative, a thing as a noun phrase. If the mood of
+what they wrote doesn't match the object they claim to be framing, it's the
+wrong object. `npm i @skhema/method` gives you the typed vocabulary and a
+validator that flags the mismatch for you. You don't need it to run this
+skill — but it turns the "which mood?" question from a judgment call into a
+check.

package/skills/skhema-frame/references/challenge.md

@@ -0,0 +1,84 @@
+# Frame the challenge
+
+The challenge is the problem that actually exists — the honest, specific
+account of what's in the way. Mood: **judgment**. It's a claim about their
+world, so it must be true, or at least testable. Most people arrive with a
+symptom and mistake it for the challenge. Your job is to get under the
+symptom to the thing worth solving, and stop before it turns into a
+solution in disguise.
+
+## The moves
+
+Run these in order. Each is a question you ask and wait for.
+
+1. **Get the raw version.** "In one sentence, what's the problem?" Let them
+   ramble first, then ask for the sentence. Write it down verbatim.
+
+2. **Test whether it's a symptom.** Ask "why is that a problem?" — up to
+   three times. "Sales are down." Why does that matter? "We'll miss the
+   quarter." Why is that happening? "Our top competitor undercut us on
+   price and we had no answer." The third answer is usually closer to the
+   challenge than the first. Stop when the answer stops being a
+   consequence and starts being a cause you could act on.
+
+3. **Cut the solution out.** If their statement contains a verb of action
+   ("we need to hire a VP of Sales", "we should rebuild the app"), it's a
+   solution wearing a problem's clothes. Ask: "if that turned out to be the
+   wrong fix, what problem would still be sitting there?" Frame THAT.
+
+4. **Bound it.** A challenge you could spend ten years on isn't a
+   challenge, it's a condition. Ask "which part of this is ours to move in
+   the next [quarter / year]?" Narrow until it fits the time and the
+   authority they actually have.
+
+5. **Read it back.** State the framed challenge in one sentence and ask
+   "is that the problem — or did I just describe a symptom of it?" Let them
+   correct you. Iterate until they say "yes, that's it" without a caveat.
+
+## What good looks like
+
+A framed challenge is:
+
+- **Specific** — names the actual friction, not a category. Not "we have a
+  growth problem" but "we win trials but lose them at the paid-conversion
+  step".
+- **A problem, not a solution** — describes what's wrong, leaves the how
+  open. If only one action could possibly follow, you've framed a solution.
+- **Bounded** — scoped to something they can move in a stated timeframe
+  with the authority they have.
+- **Testable** — a claim about the world that evidence could confirm or
+  refute. "Customers don't trust us" is testable; "we lack synergy" is not.
+- **Owned** — they'd say it unprompted to their own boss.
+
+Worked example. Arrives as: "Our onboarding is broken and we need to
+redesign it." Under questioning: trials convert fine on the free step, but
+90% never reach the paid step, and the drop happens right after the team-
+invite screen. Framed challenge: *"New teams stall at the invite step and
+never reach the paid tier — we're losing 90% of otherwise-activated trials
+in one screen."* Notice: no solution (redesign might be wrong), specific
+(one screen, one number), testable, bounded.
+
+## Failure modes to catch
+
+- **Symptom mistaken for challenge.** "Revenue is flat" is a reading on the
+  dial, not the problem. Ask why until you reach something actionable.
+- **Solution smuggled in.** Any "we need to [do X]" framing. Extract the
+  problem X is meant to solve.
+- **Boiling the ocean.** "We need to transform the business." Too big to
+  act on. Force the next-move-sized slice.
+- **Two challenges in a trench coat.** If the sentence has an "and" joining
+  two different problems, split them and frame the one that matters most
+  first; note the other so it isn't lost.
+- **Consensus mush.** A challenge everyone instantly agrees with is usually
+  too vague to be wrong. If nobody could disagree, it isn't sharp yet.
+- **Blame dressed as diagnosis.** "The problem is that marketing won't
+  ship." That's an accusation, not a framed challenge. Reframe to the
+  situation, not the culprit.
+
+## When they're really framing something else
+
+- If, once the challenge is clear, they immediately know what to do about
+  it, they didn't need a challenge — they need to commit that direction.
+  Move to `policy.md`.
+- If the challenge keeps sprawling because they won't decide what's out of
+  bounds, move to `scope.md` first, then come back.

package/skills/skhema-frame/references/decision.md

@@ -0,0 +1,92 @@
+# Frame a single decision
+
+Sometimes the whole strategy is stuck behind one fork. Build or buy. This
+segment or that one. Hire now or wait. The person circles it and can't
+move. A decision isn't a mood-typed element the way a challenge or policy
+is — it's the choice you resolve BEFORE you can state the command. Your job
+is to frame the choice cleanly: the real question, the genuine options,
+what evidence would actually settle it, and whether it can be undone. A
+well-framed decision often answers itself.
+
+## The moves
+
+1. **Extract the real question.** People state decisions as a preferred
+   answer ("we should just build it"). Ask "what's the actual question
+   here?" and phrase it as a fork: "Do we build the integration ourselves
+   or buy an off-the-shelf one?" One question, not a bundle. If there are
+   three tangled questions, separate them and frame the one that blocks the
+   others.
+
+2. **Lay out the genuine options.** Ask "what are the real choices — two,
+   maybe three?" Kill fake options (the strawman nobody would pick) and
+   surface hidden ones (the "do nothing / not yet" option is almost always
+   real and almost always omitted). Each option should be one someone could
+   honestly argue for.
+
+3. **Name what would settle it.** For each option, ask "what would have to
+   be true for this to be the right call?" Then: "what evidence would tell
+   us whether it's true — and do we have it, or can we get it cheaply?"
+   This turns a values argument into a question of fact wherever possible.
+   If the deciding evidence is gettable in a day, get it before deciding.
+
+4. **Test reversibility.** Ask "if we pick this and we're wrong, how hard
+   is it to undo?" Sort the decision:
+   - **Reversible (a two-way door):** cheap to unwind. Don't agonise —
+     pick the most likely-right option fast, and treat it as a test. The
+     cost of deliberating exceeds the cost of being wrong.
+   - **Irreversible (a one-way door):** expensive or impossible to unwind.
+     Slow down, gather the settling evidence, widen the options. This is
+     where care pays.
+   Say which kind it is out loud — people routinely agonise over reversible
+   calls and rush irreversible ones.
+
+5. **State the frame back.** "The question is [fork]. The real options are
+   [A, B, do-nothing]. It turns on whether [X] is true, which we could
+   learn by [evidence]. It's [reversible / irreversible], so we should
+   [move fast and test / slow down and verify]." Often, at this point, the
+   answer is obvious and they decide on the spot.
+
+## What good looks like
+
+- **One question, as a fork** — not a bundle, not a pre-loaded answer.
+- **Genuine options** — each defensible; the do-nothing option included;
+  no strawmen.
+- **Evidence-anchored** — names what fact would settle it and whether
+  that fact is obtainable, separating "we disagree on facts" from "we
+  disagree on values."
+- **Reversibility called** — explicitly tagged one-way or two-way, with the
+  matching tempo (fast-and-testable vs slow-and-verified).
+- **Decidable** — after the frame, a reasonable person could make the call,
+  or knows exactly what to go learn first.
+
+Worked example. Stuck on: "we should build our own billing." Framed: *"The
+question is whether we build billing in-house or adopt a provider. Options:
+build, adopt a provider, or stay on the manual process one more quarter. It
+turns on whether our pricing is stable enough that off-the-shelf tiers
+fit — which we'll know from the pricing review already underway. Adopting a
+provider is largely reversible; building is not. So: don't build yet;
+adopt a provider now as the reversible move, and revisit only if the
+pricing review shows we're genuinely non-standard."*
+
+## Failure modes to catch
+
+- **Pre-loaded answer.** "Should we build it (yes)?" Not a decision, a
+  request for agreement. Force the honest fork.
+- **Missing the do-nothing option.** "Wait" / "not yet" is almost always
+  available and often best. Always surface it.
+- **Strawman options.** Two choices where one is obviously absurd. That's a
+  decision already made, dressed as deliberation.
+- **Values fight that's really a facts fight.** They're arguing preferences
+  when a cheap piece of evidence would settle it. Find the fact, get it.
+- **Agonising over a two-way door.** Slow, careful process on a decision
+  that's trivial to reverse. Name it reversible and move.
+- **Rushing a one-way door.** Fast call on something they can't undo. Name
+  it irreversible and slow down.
+
+## When they're really framing something else
+
+- If resolving this one fork wouldn't actually unblock them — there are
+  really many entangled choices — they may need `challenge.md` to reframe
+  the problem, or `scope.md` to bound what's even being decided this round.
+- Once decided, an irreversible directional choice usually becomes a
+  `policy.md`; capture it there so it guides what follows.

package/skills/skhema-frame/references/outcome.md

@@ -0,0 +1,82 @@
+# Frame the outcome
+
+An outcome is the state they want to reach — success, named as a thing.
+Mood: **noun phrase**. It's not a verb ("increase retention"), not an
+instruction, not a list of activities. It's the world as it will be when
+they've succeeded, stated so plainly that anyone could later look and say
+"yes, that happened" or "no, it didn't." Your job is to turn a fuzzy
+aspiration into something observable, attributable, and time-bound — and to
+keep it distinct from the measures that will track it.
+
+## The moves
+
+1. **Ask for the finished world, not the effort.** "When this has worked,
+   what's true that isn't true today?" If they answer with activities ("we'll
+   have shipped the new onboarding, run the campaign…"), stop them: those
+   are the work, not the outcome. Ask again for the resulting state.
+
+2. **Make it observable.** Ask "how would an outsider know this happened,
+   without you telling them?" Push until the outcome names something you
+   could point at — a behaviour, a rate, a position — not a feeling.
+
+3. **Make it attributable.** Ask "if this happens, will it be because of
+   what we did, or could it happen anyway?" An outcome you can't plausibly
+   claim credit for is a wish about the weather. Tie it to their own action.
+
+4. **Time-box it.** "By when is this true?" No date means no outcome —
+   "eventually" can never succeed or fail. Get a horizon they'll stand
+   behind.
+
+5. **Separate the outcome from its measures.** The outcome is the state
+   ("non-technical teams reach paid on their own"); the measure is the
+   dial you read to check ("self-serve paid-conversion rate"). Name the
+   outcome first, as a noun phrase. If they lead with a metric, ask "and
+   the metric moving would mean WHAT is now true?" — that answer is the
+   outcome. One outcome can have several measures; don't collapse them.
+
+6. **Read it back as a noun phrase.** "A world where [state], by [date],
+   as a result of our work." Confirm they'd recognise it as success and
+   could tell, later, whether it happened.
+
+## What good looks like
+
+- **A state, not an action** — reads as a noun phrase describing how things
+  are, not a verb telling someone what to do.
+- **Observable** — someone outside the room could confirm it happened.
+- **Attributable** — plausibly the result of their strategy, not ambient
+  luck or the market.
+- **Time-bound** — has a horizon by which it's true or it isn't.
+- **Distinct from its measures** — the outcome is the reality; measures are
+  the instruments. Keep them separate so you don't mistake a moving dial
+  for a changed world.
+
+Worked example. Aspiration: "we want better activation." Framed outcome:
+*"Self-serve teams reaching their first paid tier without human help,
+within their first week — the norm rather than the exception, by end of
+Q3."* It's a state (teams reaching paid on their own), observable,
+attributable (it's their onboarding), time-bound (end of Q3). Its measures
+— week-one self-serve conversion rate, support tickets per signup — are
+separate instruments, framed later.
+
+## Failure modes to catch
+
+- **Activity list masquerading as outcome.** "Ship X, launch Y, hire Z."
+  That's the plan. Ask what's TRUE once it's all done.
+- **Verb where a noun belongs.** "Improve retention." An instruction, not a
+  described state. Reframe to the state improved retention produces.
+- **Unobservable.** "Customers love us", "the team is aligned." No outside
+  test. Push to something pointable-at.
+- **Unattributable.** "Revenue grows 20%" — might happen from a market
+  tailwind regardless. Tie it to their move, or narrow it to the part they
+  drive.
+- **No horizon.** "Eventually we're the leader." Can't succeed or fail.
+  Demand a date.
+- **Measure-in-place-of-outcome.** They name a metric and stop. A metric is
+  a proxy; ask what reality it stands for, and frame that.
+
+## When they're really framing something else
+
+- If they can't say what success looks like because they haven't chosen a
+  direction, the missing piece is a `policy.md`, not an outcome.
+- If the "outcome" is really one all-or-nothing choice they're stuck on,
+  it's a `decision.md`.

package/skills/skhema-frame/references/policy.md

@@ -0,0 +1,82 @@
+# Frame the guiding policy
+
+A guiding policy is the direction they're committing to — the approach that
+will shape every later choice. Mood: **command**. It's an instruction to
+the organisation: "we will go THIS way." The trap is that people restate
+the goal and call it a policy. "Become the market leader" is a goal. "Win
+by being the only option that works out of the box for non-technical teams"
+is a policy — it commits to a road and rules out others. Your job is to
+force a real commitment, not another statement of the destination.
+
+## The moves
+
+1. **Check they have the challenge.** A policy answers a challenge. If they
+   can't state the problem in one sentence, stop and run `challenge.md`
+   first. A direction with no problem is a slogan.
+
+2. **Ask for the approach, not the aim.** "Given that problem, what's your
+   approach to overcoming it?" If the answer names a destination ("get to
+   $10M", "be number one"), push: "that's where you want to end up — how
+   are you going to get there in a way your competitors aren't?"
+
+3. **Force the trade-off.** A real policy rules something out. Ask: "what
+   does this approach mean we WON'T do?" If choosing it costs nothing —
+   rules out nothing, upsets no one — it isn't a policy, it's a platitude.
+   A direction everyone can agree to is a direction that doesn't direct.
+
+4. **Find the leverage.** Ask "why will this work when other approaches
+   wouldn't?" A guiding policy usually names a source of advantage — a
+   strength they have, a weakness in rivals, a change in the market they're
+   riding. Make the "why this beats the alternatives" explicit.
+
+5. **Test it against a real choice.** Take a live decision they face and
+   ask "does this policy tell you which way to go on that?" If the policy
+   doesn't change any actual decision, it isn't guiding anything. Sharpen
+   until it does.
+
+6. **State it as one committed instruction.** "We will [approach], by
+   [source of leverage], which means we won't [ruled-out path]." Get a yes
+   they'd defend to someone who preferred the ruled-out path.
+
+## What good looks like
+
+- **A direction, not a destination** — says how they'll travel, not just
+  where they'll arrive.
+- **Costs something** — rules out a plausible alternative. If nothing was
+  given up, nothing was chosen.
+- **Leverage-bearing** — names why this route wins, not just that it's
+  nice.
+- **Decision-changing** — a person holding this policy makes different calls
+  than a person without it.
+- **Committed** — stated as "we will", owned, defensible against the people
+  who wanted the other road.
+
+Worked example. Challenge: non-technical teams abandon the product at
+setup. Restated-goal trap: "become the easiest tool in the category."
+Framed policy: *"We win by being the only tool a non-technical team can get
+to first value with zero setup and no admin — which means we won't chase
+the power-user features our competitors compete on."* It commits, it rules
+out the power-user road, it names the leverage (their setup experience),
+and it decides real roadmap fights.
+
+## Failure modes to catch
+
+- **Goal restated as policy.** "Grow 3x", "be the leader." A destination,
+  not a route. Ask how, and how differently from rivals.
+- **The costless platitude.** "Delight customers", "focus on quality." Rules
+  nothing out; everyone nods. Force the trade-off.
+- **The wish-list.** Three approaches joined by "and" — because they
+  wouldn't choose. A policy that keeps every option isn't guiding. Make
+  them pick the primary one.
+- **Leverage-free direction.** A route with no reason it beats the
+  alternatives. Ask "why will this work when the obvious approach wouldn't?"
+- **Policy that changes no decision.** If every real choice comes out the
+  same with or without it, it's decoration. Test against a live call.
+
+## When they're really framing something else
+
+- If they can't commit to any direction because one specific fork is
+  blocking everything — build vs buy, this segment vs that — frame that
+  fork first with `decision.md`, then return to the overall policy.
+- If "success" itself is still fuzzy, they may need `outcome.md` before a
+  policy makes sense.