@skhema/cli 0.4.4 → 0.4.6

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

@@ -0,0 +1,95 @@
+# Coherence
+
+Does the strategy agree with itself? You are hunting for three faults:
+**contradictions** (two parts that can't both be acted on), **unnamed tensions**
+(two parts that pull against each other and nobody said so), and **gaps** (a
+decision with no follow-through, or a goal with nothing aimed at it).
+
+Coherence is never automatic. A strategy is written in pieces, over time, by
+people in different moods. The pieces drift. Your job is to lay them side by side
+and find where they stop fitting.
+
+## Before you start
+
+Get the whole thing in front of you. Coherence can only be checked across the
+full set — a single element in isolation always looks fine. If they hand you one
+page, ask what it connects to: what decision it serves, what it depends on.
+
+## The moves
+
+Run these in order. Each pass looks for one fault type.
+
+### 1. List the commitments
+
+Read through and pull out every line that commits to something — a decision, a
+priority, a target, a "we will" or "we won't." Write them as a flat numbered
+list, in the person's own words. This list is your working surface; you check it
+against itself, not the prose.
+
+### 2. Hunt contradictions
+
+Go down the list and, for each commitment, ask: is there another commitment it
+can't coexist with? Watch for:
+
+- **Resource collisions.** "Move fast on A" and "move fast on B" when A and B
+  draw on the same one team. Two top priorities is zero priorities — say so.
+- **Direction collisions.** "Premium positioning" and "win on price." Both may
+  be written proudly, pages apart.
+- **Sequence collisions.** "B depends on A" but the plan does B first.
+
+For each hit, quote both lines and state the collision in one sentence. Do not
+resolve it yourself — that is the person's call. Surface it and ask which gives.
+
+### 3. Name the tensions
+
+A tension is softer than a contradiction: both parts can survive, but they pull
+opposite ways and the strain is unmanaged. "Serve enterprise and stay
+self-serve." Often fine — but only if named, because an unnamed tension gets
+resolved by accident, differently by each person, under pressure.
+
+For each tension: name it, say which two commitments create it, and ask the one
+question that matters — *is this a deliberate balance you're holding, or a
+choice you haven't made yet?* A named tension is a feature. An unnamed one is a
+future argument.
+
+### 4. Find the gaps
+
+Two directions:
+
+- **Decisions with no follow-through.** A commitment that nothing downstream
+  acts on. "We'll win on service" — then no line about staffing, training, or a
+  service metric. The decision is decoration until something carries it.
+- **Goals with nothing aimed at them.** An outcome or target that no initiative,
+  action, or resource points at. Ask: what in this plan actually moves that
+  number?
+
+Gaps hide because absence is invisible. You find them by walking each commitment
+forward ("what happens because of this?") and each goal backward ("what here
+causes this?") and noting where the trail goes cold.
+
+### 5. Spot the off-topic orphan
+
+Sometimes a piece shares no subject with the rest — it's about a different
+market, product, or problem entirely. It can't contradict, support, or gap
+anything, because it isn't part of this argument at all. That's not a coherence
+fault to resolve; it's a sign the element belongs to a *different strategy*.
+Flag it, say what it seems to be about, and recommend it move to its own
+workspace. Never delete it yourself — it may be someone else's live work,
+misfiled here.
+
+## Output
+
+A numbered list. Each item: the fault type (contradiction / tension / gap), the
+exact line(s) quoted, one sentence of what's wrong, and either the fix or the
+question that forces the fix. Group by type. If the set is coherent, say which
+tensions you checked and confirmed are named — that is a real finding too.
+
+## Failure modes to avoid
+
+- **Manufacturing contradictions from vague words.** If two lines only clash
+  because a word is fuzzy, that's a language problem, not a coherence one — route
+  it to `language.md`, don't dress it up as a contradiction.
+- **Resolving it for them.** You flag, they choose. Picking the winner yourself
+  skips the judgment that is theirs to make.
+- **Stopping at the first find.** Walk the whole list. The expensive
+  contradiction is usually not the obvious one.

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

@@ -0,0 +1,81 @@
+# Freshness
+
+A strategy is a set of judgments made at a moment, under conditions that were
+true then. Time passes. The conditions move. Some judgments that were right are
+now stale — not wrong when written, just overtaken. This check finds them before
+you keep building on ground that shifted.
+
+The move: for each judgment, recover the conditions it was made under, then ask
+*do those conditions still hold?* Where they don't, the judgment is up for
+re-decision. You are not attacking the old call. You are checking whether the
+world it assumed is still the world you're in.
+
+## Anchor the date
+
+Find out when the strategy — or the part you're checking — was written or last
+reviewed. If it isn't dated, that is itself a finding: an undated strategy can't
+be kept fresh, because nobody knows how old any judgment is. Establish a rough
+date before you go further, from the person or from context.
+
+## Surface the conditions behind each judgment
+
+Walk the load-bearing decisions and claims. For each, ask: *what had to be true
+about the world for this to be the right call?* Make the hidden conditions
+explicit. Examples:
+
+- "Build our own billing" assumed no good off-the-shelf option existed **then**.
+- "Don't invest in mobile" assumed usage was desktop-first **then**.
+- "Price at $X" assumed a competitor set at $Y and a cost base of $Z **then**.
+- "Win on being AI-native" assumed rivals weren't **then**.
+
+Most conditions are unstated. The judgment records the conclusion, not the world
+it depended on. Your value is reconstructing that world so you can check it.
+
+## Check what moved
+
+For each condition, ask what has changed since the anchor date. Sweep the usual
+sources of drift:
+
+- **Competitors** — new entrants, a rival that closed the gap, someone who
+  exited.
+- **The market** — demand shifted, a segment grew or died, buyer behaviour
+  changed.
+- **Technology** — a capability that was hard or impossible is now cheap and
+  routine (this one dates strategies fastest).
+- **Your own position** — you have people, money, data, or a product you didn't
+  have then. Constraints that shaped the old call may be gone.
+- **Regulation / platform / external rules** — a policy, a fee, a dependency
+  changed under you.
+
+Where a condition held then and doesn't now, flag the judgment that rode on it.
+
+## Rate the staleness
+
+Not every changed condition matters. Sort each flagged judgment:
+
+- **Stale and load-bearing** — the condition moved AND a lot rests on this
+  judgment. Re-decide now. This is the finding that justifies the whole check.
+- **Stale but minor** — overtaken, but little depends on it. Note it, move on.
+- **Still current** — conditions hold. Say so; confirmed-fresh is a real result
+  and stops needless churn.
+
+## Output
+
+A numbered list: the judgment quoted, the condition it rested on, what changed,
+and the verdict (re-decide now / note / still holds). Lead with the stale-and-
+load-bearing ones. If the strategy is undated, say that first — it's the root
+cause that makes everything else guesswork.
+
+## Failure modes to avoid
+
+- **Re-litigating good calls.** A judgment made under conditions that STILL hold
+  is not stale, even if it's old. Age alone is not the fault; a moved condition
+  is. Don't reopen settled decisions for the sake of it.
+- **Only checking the outside world.** The biggest change is often *your own*
+  position — new capability, new resources. A constraint that forced the old
+  call may simply be gone.
+- **Missing the tech shift.** "It was too expensive to build" ages fastest of
+  all. Always ask whether the hard thing got cheap.
+- **Confusing stale with wrong.** Freshness is about conditions changing, not
+  about the original call being a mistake. Frame it as "time overtook this", not
+  "this was bad" — that keeps the person willing to re-decide honestly.

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.