@skhema/cli 0.4.3 → 0.4.5

package/skills/skhema-calibrate/references/language.md

@@ -0,0 +1,74 @@
+# Language
+
+Some words let two readers walk away believing different things. Everyone nods
+at the meeting; then they go and do different work, each sure they're following
+the plan. This check hunts those words down and forces one shared meaning.
+
+The move is simple and slightly adversarial toward the text: for each fuzzy
+word, ask *could two reasonable people read this and picture different things?*
+If yes, it's a leak. You plug it by making the person say exactly what they mean,
+then writing that back into the line.
+
+## The words to hunt
+
+Read the strategy slowly and stop on any word that sounds like agreement but
+carries no fixed meaning. The usual suspects:
+
+- **Scale words** — "scale", "grow", "significant", "meaningful". Grow to what,
+  by when, measured how?
+- **Quality words** — "best-in-class", "world-class", "seamless", "delightful",
+  "robust". By whose standard? Shown how?
+- **Direction words** — "leverage", "optimize", "streamline", "double down",
+  "focus on". These describe motion without saying the actual action.
+- **Boundary words** — "soon", "some", "most", "enterprise", "the market",
+  "power users". Which ones exactly? Where's the line?
+- **Weasel qualifiers** — "essentially", "basically", "kind of", "where
+  appropriate", "as needed". These smuggle in an escape hatch. Whose judgment
+  fills the blank, and when?
+
+A fast test: could you hold this word to account in six months? "We'll grow" —
+you can never be wrong. "We'll reach 500 paying teams by Q3" — you can. Words you
+can't be wrong about are words that aren't saying anything.
+
+## The move, per word
+
+1. **Point at it.** Quote the line, underline the word.
+2. **Ask the question that exposes the fork.** Not "what do you mean?" — too
+   open. Ask the specific one: "scale to how many?", "seamless compared to
+   what?", "which customers count as enterprise — draw me the line." Make them
+   commit to a number, a name, or a test.
+3. **Watch for the tell.** If they answer instantly and precisely, the word was
+   just shorthand — fine, tighten it and move on. If they pause, or two people
+   in the room answer differently, you found a real one. The disagreement in
+   the room IS the finding.
+4. **Rewrite the line** with the precise meaning in place. "Improve onboarding"
+   becomes "get a new user to their first saved element in under five minutes."
+   Now it can be built, and it can be checked.
+
+## A special catch: the same word, two meanings
+
+Worse than one vague word is one word used two ways in the same document.
+"Platform" meaning the tech in one section and the business model in another.
+"Customer" meaning the buyer here and the end-user there. Scan for repeated
+key terms and confirm each use points at the same thing. When it doesn't, either
+split the word into two, or pick one meaning and enforce it throughout.
+
+## Output
+
+A numbered list: the vague term, the line it's in, the fork (the two+ things it
+could mean), and the sharpened rewrite — or the question still open if the person
+needs to decide. End with any word-used-two-ways findings called out separately,
+since those cause the most expensive confusion.
+
+## Failure modes to avoid
+
+- **Sharpening words that don't carry weight.** Not every adjective needs a
+  ruler. Target the words that decisions and accountability hang on. Fuzz in a
+  throwaay line is fine; fuzz in the goal is not.
+- **Accepting a synonym as a definition.** "By seamless we mean frictionless" is
+  not a definition. Push until you get a test, a number, or a concrete example.
+- **Doing the deciding.** If "enterprise" has no line drawn, you don't draw it —
+  you make them draw it. The vagueness is often hiding a decision they haven't
+  made. Surface that; don't paper over it.
+- **Confusing this with coherence.** If the problem is two lines disagreeing,
+  that's `coherence.md`. Here the problem is one line meaning two things.

package/skills/skhema-communicate/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: skhema-communicate
+description: "Use when a strategy already exists and now has to move to people who didn't build it — a board, a team, a new hire, an investor. Packages the same strategy at the right resolution for each audience: a board update, a team brief, a one-page decision brief, or an adaptation pass across several audiences at once."
+---
+
+# Communicate
+
+The strategy exists. Now it has to move — to a board that oversees it, a
+team that executes it, a new hire who inherits it, an investor who funds
+it. Your job is not to re-decide the strategy or improve it. Your job is
+to make the same strategy land with people who will each do something
+different with it.
+
+There is one cardinal rule, and every capability here obeys it: **same
+strategy, different resolution — never a different strategy per audience.**
+A board sees less detail than a team, a new hire sees less than the board;
+none of them sees a version that contradicts another. The moment two
+audiences would disagree about what the strategy IS, you have stopped
+communicating and started spinning, and the credibility bill comes later.
+
+## The first move: who, and what must they DO with it?
+
+Before you write anything, answer two questions out loud:
+
+> **Who** is this for, and **what do they need to DO** with the strategy —
+> oversee it, execute it, sign off on one decision, or fund it?
+
+What they need to do decides what they see. An audience that oversees needs
+decisions, risks, and asks. An audience that executes needs to know what
+changes Monday morning. Someone signing off on one fork needs that one
+decision, not the whole strategy. Get the "what must they do" wrong and you
+hand a board a work plan or hand a team a governance report — both bounce.
+
+| The audience needs to… | Route to |
+|---|---|
+| Oversee and back the strategy — a board, a steering group, a governance body | `references/board-update.md` |
+| Execute it — the team or teams who will do the work | `references/team-brief.md` |
+| Sign off on, or record, one specific decision | `references/decision-brief.md` |
+| Several of the above at once, or you're unsure how much to show whom | `references/audience-adaptation.md` |
+
+## How to pick
+
+- They asked for "an update for the board / the investors / the leadership
+  group" — people who hold you accountable but don't do the work →
+  **board-update**. Decisions, evidence, risks, asks. No theatre.
+- They asked to "tell the team" or "roll this out" — the people who execute
+  → **team-brief**. What we're doing, what we're not, and what changes
+  Monday.
+- It's really about **one** choice — a build-or-buy, a hire, a shutdown —
+  that needs a yes and a paper trail → **decision-brief**. One decision,
+  one page.
+- There are multiple audiences, or the question is "how much do I tell
+  each of them" → **audience-adaptation** first. It sets the altitude for
+  each audience, then routes you into the others per audience.
+
+If you have several audiences, run **audience-adaptation** first — it keeps
+every downstream rendering coherent with the others. Then produce each
+artifact.
+
+## What "communicated" means
+
+A capability is done when the audience can act on the strategy without
+coming back to ask what it means — the board can vote on the asks, the team
+knows what to do Monday, the signer can say yes or no. And when you could
+read every version you produced aloud in one room without contradicting
+yourself. If a reader has to reconstruct the strategy from your words, you
+under-resolved. If two audiences would argue about what it says, you
+over-adapted. Each reference file gives you the shape for its audience 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
+
+Communicating well is really re-resolving typed judgments for an audience:
+a board wants the decisions (the commands) and the risks (the assumptions
+still open); a team wants the guiding policy (a command) turned into
+actions. If your strategy is written as typed elements, you already know
+which pieces each audience needs — you're filtering by type, not
+rewriting. `npm i @skhema/method` gives you that typed vocabulary, so
+"what does the board see versus the team" becomes a filter over the same
+elements instead of a fresh draft you have to keep in sync by hand. You
+don't need it to run this skill — but it is what stops the board version
+and the team version from silently drifting apart.
+
+Every capability here ends by saving its artifact as a **workspace
+document** (`skhema document create`) — the narrative stays tethered to the
+elements it cites instead of dying in a chat log.

package/skills/skhema-communicate/references/audience-adaptation.md

@@ -0,0 +1,103 @@
+# Audience adaptation
+
+You have one strategy and several audiences — a board, a team, a new hire,
+an investor. This capability decides how much each of them sees, and keeps
+every version honest against the others. Run it first, before you produce
+any single artifact, whenever more than one audience is in play.
+
+The one rule that governs everything here: **same strategy, different
+resolution — never a different strategy per audience.** A board sees the
+decisions and the risks; a team sees what changes Monday; a new hire sees
+the through-line and where they fit. Those are different zoom levels on one
+map. They are not different maps. The instant two versions would contradict
+each other, you have two strategies and a credibility failure waiting to
+surface.
+
+## The moves
+
+1. **List the audiences.** Everyone who has to receive this strategy.
+2. **For each, ask what they must DO with it.** Decide, execute, fund,
+   join, comply? This is the whole basis for adaptation — not seniority,
+   not politeness. What they do determines what they need to see.
+3. **Set the altitude from the job.** Give each audience exactly the
+   resolution their job requires — no more (detail they can't act on is
+   noise), no less (missing what they need forces them to guess).
+4. **Pick the format per audience.** Route each to the right artifact:
+   board → `board-update.md`, team → `team-brief.md`, a single sign-off →
+   `decision-brief.md`. A new hire or an investor may need a custom one-pager
+   built on the same principle.
+5. **Run the coherence check** (below). This is the step that separates
+   adaptation from spin. Do not skip it.
+
+## Altitude by job
+
+| Audience | What they must do | What they see (resolution) |
+|---|---|---|
+| Board / investors | Oversee, back, fund | The decisions, the evidence, the risks carried, the asks |
+| Team | Execute | The guiding policy, what's cut, what changes Monday, the why |
+| New hire | Join and orient | The through-line, why it's the direction, where they fit |
+| Signer of one call | Approve one decision | That decision, its evidence, its reversibility |
+| Regulator / partner | Comply / rely on | The commitments that bind us, no internal deliberation |
+
+Same strategy underneath every row. Only the resolution changes.
+
+## The coherence check
+
+Line up every version you've produced and test them against each other:
+
+- **Every claim in the short version must be true in the long version.**
+  The new-hire one-liner is a compression of the board's decisions, not a
+  softer or bolder claim than them.
+- **No version may contradict another.** If the board hears "steady
+  progress" and the team hears "urgent turnaround", those aren't two
+  altitudes, they're two stories. Pick the true one and resolve both from
+  it.
+- **Differences are resolution, not substance.** Detail dropped for a higher
+  audience must be detail, never a different decision, a different risk
+  posture, or a different level of confidence.
+
+The test in one sentence: **could you put every audience in one room and
+read all your versions aloud without contradicting yourself?** If yes, you
+adapted. If you'd have to hope they never compare notes, you spun, and the
+comparison always eventually happens.
+
+## What good looks like
+
+- Each audience gets the altitude their job needs and no other.
+- The versions nest cleanly: zoom out from the team brief and you land on
+  the board update; zoom out again and you land on the through-line.
+- You would be comfortable if any audience saw any other's version.
+
+## Failure modes to catch
+
+- **Two stories.** Optimism for the board, alarm for the team, or vice
+  versa. One true account, resolved differently. Never two.
+- **Different decision per audience.** Telling one group you'll build and
+  another you might buy. That's not adaptation — the strategy itself is
+  moving. Fix the strategy, then communicate it.
+- **Flat resolution.** Everyone gets the same altitude, so the board drowns
+  in execution detail and the team gets strategic fog. Set altitude per
+  job.
+- **Tone-only adaptation.** You changed the warmth and the vocabulary but
+  gave every audience the same depth. Adapt the resolution, not just the
+  register.
+- **Skipping the coherence check.** Each version was written well in
+  isolation and never lined up against the others. Line them up; that is
+  where the drift shows.
+
+## Save it as a workspace document
+
+In the Skhema environment, the artifact you just wrote has a home: save it
+as a workspace document so it stays versioned with the strategy and cites
+the elements it stands on.
+
+```sh
+echo '{"title":"<title>","docType":"<board_update|team_brief|decision_brief|custom>","content":"<the markdown you wrote>","elementRefs":["<element-id>", "…"]}' > doc.json
+skhema document create --workspace <workspace-id> --file doc.json
+```
+
+Put every element you drew on into `elementRefs` — that tether is what lets
+a later calibration pass tell the reader which briefs were built on a
+judgment that has since gone stale. Working outside the Skhema environment?
+The artifact is still complete as a file; save it wherever your team keeps
+decisions.

package/skills/skhema-communicate/references/board-update.md

@@ -0,0 +1,93 @@
+# Board update
+
+The audience oversees the strategy; they do not execute it. They carry
+accountability for it and hold resources you need. What they must DO with
+your update: satisfy themselves the strategy is still sound, decide on the
+asks you bring, and knowingly accept the risks that are being carried. Give
+them exactly what those three acts require, and nothing that only flatters.
+
+A board update is not a status report. Activity is not the unit; decisions,
+evidence, risk, and asks are. If a line doesn't help them govern, cut it.
+
+## The moves
+
+1. **Get the baseline.** Ask: what did the board last see, and when? A board
+   update is a delta. If there is no prior, state the strategy's through-line
+   in one paragraph so the rest has an anchor.
+2. **Ask what actually changed.** Since the last update: what did you decide,
+   what did you learn, what got riskier or safer? Everything below comes from
+   this, not from a calendar of what happened.
+3. **Draft the five sections** below, in this order.
+4. **Force every ask to have an owner and a default.** An ask with no
+   decision attached is theatre. See section 5.
+5. **Strip the theatre.** Read it back and delete anything that is there to
+   impress rather than to inform a governance decision.
+
+## The shape
+
+Five sections. One page if you can.
+
+1. **The through-line.** One short paragraph: what this strategy is and
+   whether it has changed. If it hasn't changed, say so in a sentence — that
+   itself is information the board needs.
+2. **Decisions made.** What you decided since last time, each with the
+   judgment behind it in one line — not just the outcome, the reason. The
+   board is accountable for the direction; they need the "why", not just the
+   "what".
+3. **Evidence moved.** What you learned that changed your confidence. A bet
+   that paid off or didn't, a number that came in, an assumption now
+   confirmed or killed. State which way it moved your confidence and what you
+   did about it.
+4. **Risks carried.** The live risks, each with an owner and a trigger —
+   "if X happens, we do Y". A risk with no owner and no trigger is a worry,
+   not a managed risk, and the board can't accept it.
+5. **Asks.** The specific decisions or resources you need FROM the board.
+   Each ask states: what you're asking for, the decision it unblocks, and
+   **the default if they don't act**. The default is what turns a discussion
+   into a decision.
+
+## What good looks like
+
+- A board member could vote on every ask without asking a clarifying
+  question first.
+- Every decision reported comes with its reason, so the board can challenge
+  the reasoning, not just the outcome.
+- Every risk has a name next to it and a stated trigger.
+- The asks are up top or clearly flagged, never buried in paragraph six.
+- It is shorter than they expected and they still know more.
+
+## Failure modes to catch
+
+- **Activity dump.** "Here's everything we did." The board governs
+  decisions and risk, not effort. Replace the timeline with the four
+  substantive sections.
+- **Buried ask.** The thing you actually need is in the last sentence. Move
+  it up; a board update exists to get the asks decided.
+- **Ownerless risk.** Risks listed with no owner and no trigger. The board
+  cannot knowingly accept a risk nobody owns. Add both or drop the line.
+- **Vanity metrics.** Numbers that go up and flatter but wouldn't change any
+  governance decision. If a metric wouldn't alter an ask or a risk, it
+  doesn't belong in a board update.
+- **No confidence direction.** Evidence reported without saying which way it
+  moved you. "We ran the pilot" is activity; "the pilot missed, so we've cut
+  our confidence in the channel and paused spend" is evidence moved.
+- **Reassurance in place of asks.** A whole update that reports comfort and
+  asks for nothing. If there is genuinely nothing to decide, that is a
+  one-line update, not a deck.
+
+## Save it as a workspace document
+
+In the Skhema environment, the artifact you just wrote has a home: save it
+as a workspace document so it stays versioned with the strategy and cites
+the elements it stands on.
+
+```sh
+echo '{"title":"<title>","docType":"board_update","content":"<the markdown you wrote>","elementRefs":["<element-id>", "…"]}' > doc.json
+skhema document create --workspace <workspace-id> --file doc.json
+```
+
+Put every element you drew on into `elementRefs` — that tether is what lets
+a later calibration pass tell the reader which briefs were built on a
+judgment that has since gone stale. Working outside the Skhema environment?
+The artifact is still complete as a file; save it wherever your team keeps
+decisions.

package/skills/skhema-communicate/references/decision-brief.md

@@ -0,0 +1,93 @@
+# Decision brief
+
+One decision. One page. The audience reads it to say yes or no, and to have
+a record of why later. What they must DO with it: judge the reasoning — not
+just receive the recommendation — and be able to reconstruct, months from
+now, what was known and what was merely believed when the call was made.
+
+The discipline that makes a decision brief work: **evidence before
+recommendation, and reversibility called out first.** A reader handed the
+recommendation first can only agree or disagree with you; a reader handed
+the evidence first can form their own view and then check yours against it.
+
+## The moves
+
+1. **State the decision as a command, in one sentence.** "We will build X in
+   house." Not "should we build or buy?" — a brief resolves a fork, it
+   doesn't host the debate.
+2. **Classify reversibility first.** One-way door or two-way door? Can we
+   undo this cheaply, or are we stuck with it? This sets how much rigour the
+   rest of the brief deserves — over-analysing a reversible call wastes
+   everyone; under-analysing an irreversible one is how disasters get
+   waved through.
+3. **Lay out the evidence before your recommendation.** Separate what is
+   known from what is assumed, and mark the confidence on each. The reader
+   should be able to reach the recommendation themselves from the evidence
+   you show.
+4. **Show the options you rejected, each as a claim, with why.** A decision
+   with only one option shown isn't a decision, it's an announcement.
+5. **Record the dissent.** Who disagreed, and their actual reason, in their
+   terms — not smoothed into consensus. Disagreement erased from the record
+   is disagreement you'll relitigate later with no memory of why.
+6. **State the revisit trigger.** What would make us reopen this — a number,
+   an event, a date.
+
+## The shape (one page)
+
+1. **The decision.** One sentence, imperative. What we will do.
+2. **Owner and date.** Who is accountable, and when it was decided.
+3. **Reversible or not.** Two-way door (undo cheaply) or one-way (committed).
+   Say which, and let it set the depth of everything below.
+4. **The evidence.** Facts first, each marked known or assumed, with
+   confidence. This comes before the recommendation, deliberately.
+5. **Options considered.** Each stated as a claim, each with why it was
+   rejected — including the option of doing nothing.
+6. **Recommendation.** The call, and the judgment that gets you from the
+   evidence to it.
+7. **Dissent.** Who disagreed and why, recorded straight.
+8. **Revisit trigger.** What would make us reopen this.
+
+## What good looks like
+
+- A reader could reach your recommendation from your evidence section
+  before they read your recommendation.
+- The reversibility call is explicit and the depth of analysis matches it.
+- Facts and assumptions are visibly separated; no assumption is dressed as
+  a fact.
+- The strongest objection is on the page in its own words.
+- A year later, someone can see exactly what was known and believed at
+  decision time.
+
+## Failure modes to catch
+
+- **Recommendation first.** The call leads and the evidence is arranged to
+  support it. The reader can only rubber-stamp. Put evidence first.
+- **No reversibility call.** The brief agonises over a two-way door, or
+  nods through a one-way one. Classify it and match the rigour.
+- **Assumptions as facts.** Beliefs stated in the confident voice of
+  evidence. Mark each one; a claim with no evidence behind it is an
+  assumption and gets labelled as one.
+- **Straw options.** Alternatives listed only to be knocked down. Show the
+  real case for each before the reason it lost.
+- **Sanded-off dissent.** "The team is aligned" when someone wasn't. Record
+  the objection; consensus theatre destroys the paper trail's whole value.
+- **No revisit trigger.** The decision is framed as permanent when it isn't.
+  State what would reopen it, so a changed world reopens it on purpose
+  rather than by crisis.
+
+## Save it as a workspace document
+
+In the Skhema environment, the artifact you just wrote has a home: save it
+as a workspace document so it stays versioned with the strategy and cites
+the elements it stands on.
+
+```sh
+echo '{"title":"<title>","docType":"decision_brief","content":"<the markdown you wrote>","elementRefs":["<element-id>", "…"]}' > doc.json
+skhema document create --workspace <workspace-id> --file doc.json
+```
+
+Put every element you drew on into `elementRefs` — that tether is what lets
+a later calibration pass tell the reader which briefs were built on a
+judgment that has since gone stale. Working outside the Skhema environment?
+The artifact is still complete as a file; save it wherever your team keeps
+decisions.

package/skills/skhema-communicate/references/team-brief.md

@@ -0,0 +1,91 @@
+# Team brief
+
+The audience executes the strategy. What they must DO with the brief: leave
+it knowing what to work on Monday, what to stop, and enough of the why to
+make good calls when you're not in the room. That last part is the whole
+game — a team that knows only the "what" freezes the moment reality differs
+from the plan; a team that knows the "why" adapts.
+
+A team brief is not a motivational speech and not the board update with the
+logo changed. It is a translation of the strategy into changed behaviour.
+
+## The moves
+
+1. **Get the guiding policy.** Ask for the one decision the strategy turns
+   on — the direction they're committing to — in plain words. Everything in
+   the brief serves this.
+2. **Ask what's being cut.** For every strategy that says "we're doing X",
+   there's a "which means we're no longer doing Y". Drag those out; they're
+   the half people miss.
+3. **Translate to Monday.** For each part of the strategy, ask: what does a
+   person actually do differently because of this? If the answer is
+   "nothing", it doesn't go in the brief.
+4. **Name what stays the same.** Stop the over-rotation. Teams hearing
+   "new strategy" often abandon things that were working. Say explicitly
+   what doesn't change.
+5. **Open a channel for pushback.** Decide how they raise disagreement and
+   say so in the brief. Dissent you don't invite doesn't vanish — it goes
+   underground and comes back as quiet non-compliance.
+
+## The shape
+
+1. **The one line.** What we're doing, in a sentence a team member could
+   repeat to a peer accurately. This is the guiding policy in plain words.
+2. **What that means we're NOT doing.** The cuts, named. Often the most
+   useful part of the whole brief — it's how people know where to stop
+   spending effort.
+3. **Why.** One short paragraph: the challenge underneath, the reason this
+   is the direction. Enough that they can improvise well, not a history
+   lesson.
+4. **What changes Monday.** Concrete: new priorities, work that stops, new
+   owners, new measures, anything a person will feel this week. Vague here
+   means nothing happens.
+5. **What stays the same.** So they don't throw out what works.
+6. **Where to push back.** The open questions, and how to raise concerns.
+   Name the channel.
+
+## What good looks like
+
+- A person in the room could tell a colleague who missed it what to do
+  differently Monday — accurately, from memory.
+- The "not doing" list is as clear as the "doing" list.
+- The why is short enough to remember and load-bearing enough to improvise
+  from.
+- Nobody leaves unsure whether their current work still matters.
+- Disagreement has a named place to go.
+
+## Failure modes to catch
+
+- **All doing, no cutting.** The brief announces new work but never says
+  what stops, so everything is now "also important" and nothing actually
+  changes. Force the cuts.
+- **Abstraction with no Monday.** Fine words, no concrete change to anyone's
+  week. If you can't name what someone does differently, you haven't briefed
+  them, you've addressed them.
+- **Missing why.** The team gets the "what" and none of the reason, so the
+  first time reality deviates they stall and wait for instruction. Put the
+  why in.
+- **Board update in disguise.** Risks, asks, governance framing — aimed at
+  overseers, handed to executors. Rewrite around what changes for them, not
+  what you're accountable for.
+- **No dissent channel.** The brief is broadcast-only, so disagreement goes
+  quiet and turns into drift. Name where pushback goes.
+- **Over-rotation left unaddressed.** Silence on what stays the same, so a
+  team torches working practices to prove they're on board. Say what holds.
+
+## Save it as a workspace document
+
+In the Skhema environment, the artifact you just wrote has a home: save it
+as a workspace document so it stays versioned with the strategy and cites
+the elements it stands on.
+
+```sh
+echo '{"title":"<title>","docType":"team_brief","content":"<the markdown you wrote>","elementRefs":["<element-id>", "…"]}' > doc.json
+skhema document create --workspace <workspace-id> --file doc.json
+```
+
+Put every element you drew on into `elementRefs` — that tether is what lets
+a later calibration pass tell the reader which briefs were built on a
+judgment that has since gone stale. Working outside the Skhema environment?
+The artifact is still complete as a file; save it wherever your team keeps
+decisions.

package/skills/skhema-compose/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: skhema-compose
+description: Use when a strategic question is too big to reason about in one go, or when you have a pile of notes, decisions, and facts that don't yet add up to a strategy. Break the big thing into small typed judgments; assemble the small judgments into a coherent structure.
+---
+
+# Compose
+
+Break it down, build it up.
+
+Strategy work fails in two opposite ways. Either the question is too big to
+hold in your head — "what should we do about the market shift?" — so nothing
+moves. Or you have a hundred fragments — meeting notes, a pricing decision, a
+competitor fact, three half-baked bets — and no way to see whether they form a
+strategy or just a heap.
+
+Both are the same problem: the wrong grain. This skill moves you between grains.
+Big questions come apart into small, decidable pieces. Small pieces snap
+together into a structure you can inspect, argue with, and revise.
+
+## The one distinction that makes this work
+
+Before you write anything down, sort it into one of three kinds. Ask: am I
+stating something I believe is **true**, something I've decided to **do**, or
+naming a **thing**?
+
+- A **judgment** — a claim about the world. "Enterprise buyers won't switch
+  mid-contract." "Our onboarding is the leak." These can be right or wrong;
+  they carry evidence and confidence.
+- A **command** — a decision to act. "Focus every release on time-to-first-value."
+  "Stop selling to solo users." These can be followed or ignored; they don't
+  have a truth value, they have consequences.
+- A **thing** — a named object. An outcome, a scope, a capability, an
+  initiative. "Self-serve activation." "The mid-market segment."
+
+Almost all strategy confusion is these three getting mixed. A "goal" that's
+secretly an untested assumption. A "decision" that's really just a hope. When
+you decompose or assemble, you are always sorting pieces into these three kinds
+first. The rest of the skill is what you do once they're sorted.
+
+## Capabilities
+
+| You need to… | Route to |
+|---|---|
+| Take one big strategic question and break it into the discrete judgments it actually depends on | `references/decompose.md` |
+| Take a pile of judgments and decisions and lay them into a strategy structure — see what belongs where, what's missing, what's premature | `references/assemble.md` |
+| Connect an outcome you want to a measure you can watch and a starting number to compare against | `references/metrics-tree.md` |
+| Compare two or more options honestly — same criteria, explicit trade-offs, evidence per option | `references/options.md` |
+
+## Routing
+
+- The user has a **question they can't get traction on** ("I don't even know
+  where to start with X") → **decompose**. Output: a dependency-ordered list of
+  smaller judgments.
+- The user has **material but no shape** — notes, prior decisions, a doc that
+  rambles → **assemble**. Output: pieces sorted into the five components, with
+  gaps and premature entries flagged.
+- The user has a **goal or outcome and no way to know if they're winning** →
+  **metrics-tree**. Output: outcome → measure → baseline chains.
+- The user is **stuck between paths** — "should we do A or B?" → **options**.
+  Output: options scored on shared criteria, trade-offs named.
+
+These chain. A messy question usually goes decompose → assemble; an assembled
+strategy usually exposes a missing measure (metrics-tree) or an unmade choice
+(options). Don't force the whole chain — run the one that unblocks the user, and
+name the next one.
+
+## The five components (used by assemble)
+
+A strategy, laid out, reads in this order. Each component answers a different
+question. Keep this order in your head whenever you assemble:
+
+1. **Diagnosis** — what's actually going on? The honest account of the situation
+   and the crux within it.
+2. **Method & Positioning** — the guiding approach. How we'll compete and win,
+   given the diagnosis.
+3. **Portfolio of Initiatives** — the coherent set of things we're actually
+   doing (and, just as loud, not doing).
+4. **Measures** — how we'll know it's working, and know early.
+5. **Support Structures** — the capabilities, systems, and resourcing that make
+   the above possible instead of aspirational.
+
+## 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
+
+Everything above works with pen and paper. If you want the three kinds
+(judgment / command / thing) checked for you rather than sorted by eye, the
+`@skhema/method` package types every strategy element with an expected
+grammatical *mood* — indicative for judgments, imperative for commands, noun
+phrase for things — and flags pieces that are typed against their mood. Install
+with `npm i @skhema/method` for the vocabulary and validators. The skill is
+fully usable without it.