--- name: docs-strategy-update description: Gate + apply changes to the strategy docs (lean-canvas, hypotheses, theory-of-change, definitions, progress) when strategy shifts — runs 8 anti-drift gates before writing. Owns the strategy-doc layer; /kdd owns decisions.md. when_to_use: "Before editing docs/lean-canvas.md, docs/hypotheses.md, docs/theory-of-change.md, docs/definitions.md, or docs/progress.md — especially after a strategic pivot in conversation. Sync mode (a described change) or audit mode (no arg). NOT for decisions.md (that's /kdd) or CLAUDE.md (that's /slava:maintain:claude-md)." version: 1.3.0 --- # /slava:maintain:docs-strategy-update Gate + apply changes to ClarityPledge's five **strategy docs** — `lean-canvas.md`, `hypotheses.md`, `theory-of-change.md`, `definitions.md`, `progress.md` — so a strategic shift gets written down without the recurring drift failures: premature-fact, reversal-churn, cross-doc contradiction, unpruned bloat, claim-without-disproof, fragile refs, competing single-valued directives. **Announce at start:** "Running /docs-strategy-update." This skill **owns the strategy-doc layer.** `/kdd` owns `decisions.md` + meta-reflection. `/slava:maintain:claude-md` owns CLAUDE.md and `.claude/rules/`. --- ## When to use this vs other skills | Situation | Skill | |---|---| | A strategic shift must land in lean-canvas / hypotheses / theory-of-change / definitions / progress | `/docs-strategy-update` ← here | | Capture a decision + run session meta-reflection | `/kdd` (writes decisions.md) | | Change CLAUDE.md or a `.claude/rules/` file | `/slava:maintain:claude-md` | | Output is a tracked feature, not a strategy-doc change | `/slava:build:create-spec` | --- ## Modes (auto-detected — no flags) - **Sync** (invoked with a described strategic shift): apply it across the relevant docs, running every gate. - **Audit** (invoked with no argument): scan the four docs for accumulated violations; produce a punch list. **No writes.** --- ## Workflow ### Step 0 — Resolve branch + load state + record base 1. **Resolve branch FIRST — before any write (Step 3 writes decisions.md).** Strategy docs *and* their decision entry land on `main` or a dedicated docs branch, **never** an unrelated feature/fix branch. Run `git branch --show-current`; if it is not `main` or a docs branch, switch first using the `.claude/rules/skills.md` Branch Guard wip-pattern. Doing this before Step 3 keeps the decision entry and the doc edits on the same correctly-placed branch. 2. Read all five docs in full: `lean-canvas.md`, `hypotheses.md`, `theory-of-change.md`, `definitions.md`, `progress.md`. - **Doc routing map:** `docs/CHARTER.md` — one fact, one home (the strategy docs are homes 4–8). Read it when unsure where a fact belongs; this skill references it rather than restating the 9-way tree. - **Launch/GTM posture source:** **`docs/goals.md`** is the public, git-versioned home of tactical GTM/funnel execution (CHARTER rule 7) — read it for the current posture. `.private/docs/gtm-launch-icp-worksheet.md` holds only the **named residue** (private — contains names; reference by name only, never copy into public docs). **`goals.md` is not a gated home** (ungated/tactical) — free-standing tactical edits to it are outside this skill entirely. **But when a sync you just applied *invalidates* `goals.md`** (a hypothesis you demoted is still framed there as active, a page-lead you moved is still copied there), reconcile it **in the same edit**, under **Gates 1 and 3 only** (no SINGLE-VALUE markers exist in `goals.md`, so Gate 8 does not apply). Detect-and-hand-off was the prior rule; it produced two recorded hand-offs and zero edits (see Step 6). 3. Read the most recent ~50 lines of `decisions.md` for live context — and **widen the read** if Gate 2's `git log -S` later surfaces an older relevant decision. 4. Record the base commit: `git rev-parse HEAD` — used in Step 4 to detect concurrent drift before applying. 5. Resolve mode: argument present → **Sync**; absent → **Audit**. ### Step 1 — State the delta (Sync) / scope the scan (Audit) - **Sync:** in 1–3 sentences, state the strategic change and exactly which docs + sections it touches. A pivot from conversation must be expressible as **"X was true; now Y, because <evidence>."** If you cannot name the evidence, stop — that is Gate 5/7 failing before you start. - **Audit:** skip to Step 2 against current doc contents. ### Step 2 — Run the 8 gates Run each gate against the proposed edit (Sync) or current docs (Audit). Produce a gate report (PASS / FIX / WARN per gate). **A FIX blocks the write until resolved.** Every gate that runs a grep or command must **quote its actual output** in the report (matched lines, the anchor checked, or "0 matches") — **a verdict with no quoted artifact is treated as not-run, not PASS.** **Fix the axis before the gates — two orthogonal dimensions, neither is epistemic status, neither pre-blocks a write** (this argument has recurred 3+ times; decisions.md 2026-07-03 [process]): - **Edit permission** (may I change this box?): **destructive-vs-additive** (Gate 1 / Gate 4; decisions.md 2026-06-30). Additive, `UNTESTED`-labeled, falsifier-carrying content is always recordable — validation is NOT a precondition. - **Routing** (which doc holds it?): **structural/durable vs tactical/volatile** — the structural bet (customer, value-prop, mechanism, and the channel *bet* of *who delivers*, e.g. coaches; *change = pivot*) → strategy docs; tactical mechanics (funnel choreography, prices, per-step targets, event run-of-show — including channel *mechanics* like a specific webinar format; *change = every experiment*) → decisions.md / goals.md / .private. Reason = **churn-isolation, NOT epistemic rank**. **Advisory, and it never withholds content:** default is to RECORD it (with a Gate-5 falsifier + honest `UNTESTED` label — that requirement is the churn/scope brake, so "record freely" is not "dump anything"); routing is a non-blocking note on *which doc*, never a reason to not write. **If a piece is genuinely ambiguous between structural and tactical, record it where the founder wants and move on — do not argue placement** (that argument IS the recurrence). > **STOP — retired axis.** If you are about to keep content OUT of a strategy doc because it is "unvalidated," "unrun," or "not yet validated" — that axis is **DEAD** (decisions.md 2026-06-30 + 2026-07-03). *Everything* in the strategy docs is an unvalidated bet. The only questions are destructive-vs-additive (edit permission) and structural-vs-tactical (routing). **Recording is never blocked, only routed — and routing is advisory.** Excluding on *structural* grounds is ALSO not a block: if the founder wants it in the canvas, it goes; a routing recommendation is a note, not a veto, and must never read to the founder as a refusal to record. Do not re-derive this; do not re-litigate it with the founder. **Gate 1 — Premature-fact (per-doc source of truth).** **Scope (read first):** this gate governs the *accuracy of epistemic status labels and numbers*, **not** whether reasoned-but-untested content may be recorded at all. A box MAY be rewritten with a deductively-reasoned model so long as it is honestly labeled (`UNTESTED` / hypothesis) and carries a falsifier (Gate 5) — recording it is permitted; **mislabeling** it as `Validated` / `Active` / `proven` is what this gate blocks. The discriminator for *may I update this box* is **destructive-vs-additive, NOT validated-vs-untested** (decisions.md 2026-06-30 [process]) — empirical validation is not a precondition for recording. With that scope set: every status word (`Active`, `Validated`, `proven`, `✅`) and hard number (price, R₀, %, count) must trace to real evidence: - `lean-canvas.md` / `theory-of-change.md` → must agree with that doc's **Validation Status** block. - `hypotheses.md` → must agree with the hypothesis's evidence rows / Transform-if. - `definitions.md` → **no status words at all** (it is a glossary). Flag any. - `progress.md` → numbers live ONLY inside the `` block and regenerate via `./scripts/progress-refresh.sh --write`; a hand-edited number anywhere in the doc is a FIX. Bets-and-kills rows must agree with `hypotheses.md` status + Transform-if. The human-stamped self-discipline line (untested-hypothesis date) must be re-checked against hypotheses.md on every sync. - A milestone label (e.g. `C1`) is NOT a customer. Unvalidated → label **"theory / untested bet"**, never "Active". - A doc with no Validation block to check against → **WARN** (never a silent pass). - Agreeing with the Validation block is **necessary but not sufficient** — Gate 7 still requires an external source. If a number is internally consistent but unsourced, **Gate 7 wins** (label it "unverified"). **Gate 2 — Reversal-lock.** Before rewriting a named construct or settled position, grep for a structural lock marker (case-sensitive + boundary-anchored, so *unlocked* / *Unblocked* don't false-match): ```bash grep -rnE '(^|[^[:alnum:]])(LOCKED|DECISION-LOCK):' docs/lean-canvas.md docs/hypotheses.md docs/theory-of-change.md docs/definitions.md docs/progress.md git log -S "" --oneline -- docs/ | head ``` As of this skill's creation the docs carry **no** lock markers, so expect zero grep hits — that means "no lock present, proceed", **not** "gate failed". The `git log -S` pass applies regardless of markers: if it surfaces a commit that settled this construct the other way, **read that commit before reversing**. If a lock exists and this edit reverses it, the edit + the decision entry (Step 3) must name the **new evidence** (not new phrasing) that justifies overriding it. When you settle a position you expect to hold, write `LOCKED: — ` next to it so future runs can see it. **Gate 3 — Cross-doc.** (a) Every anchor/section this edit links to must still exist — grep the target heading; a link to a missing heading is a FIX. (b) No sibling doc may assert the **negation** of what you're writing. Don't grep your new sentence — a contradiction is rarely a near-duplicate. Instead: list 3–5 key nouns in the new claim (e.g. *coach, distribution, spread*), then for each run `grep -rniE '(not|without|never|no|isn.?t) .{0,30}' docs/` and **read every hit in full**. Fix or remove the contradiction in the same edit. (This is what catches theory-of-change "spreads NOT through coaches" vs a coach-distribution pivot — grepping the literal new wording never surfaces it.) **Gate 4 — Bloat (propose-only deletion).** An addition that supersedes an existing dated block must delete or merge that block — but: - **Never auto-delete.** Show each proposed cut; get confirmation. - A block is "superseded" only if the newer block carries explicit supersede intent OR the user confirms it. Blocks marked as deliberate **alternates** ("alternates, not a sequence") are kept. - **Never delete a block containing a falsifier / Transform-if** — that content is load-bearing by Gate 5. - **Additive `UNTESTED` updates are NOT bloat.** Rewriting a box with current best thinking is permitted (see Gate 1 scope); only the *destruction of a revivable fallback* is a FIX. Do not block an additive, honestly-labeled rewrite. - **Active-on-top / dormant-below check (mechanical FIX).** When a box's active content is relabeled to a new (`UNTESTED`) market/construct, the prior version must survive as a `### Dormant (...)` sibling **in the same box**. Grep the box for a `Dormant` heading: a box carrying a new active framing but **no** dormant-below sibling for a construct that previously had one = **FIX** (revivable fallback destroyed — the one thing the discriminator still guards). Quote the grep result ("0 matches" where one is expected IS the FIX). - **Erosion guard (WARN).** If across syncs the count of `UNTESTED`-labeled active blocks climbs while none are promoted (validated) or pruned, flag **WARN** — the label may be laundering scrutiny rather than carrying honest epistemic weight (the failure mode in decisions.md 2026-06-30 [process] falsifier). - (A coarse, line-granular net-bloat count is also flagged in `scripts/pre-commit-checks.sh` — a hygiene signal that over-counts multi-line blocks, **not** this gate's judgment.) **Gate 5 — Disproof.** Every strategic claim being written carries a one-line falsifier — "how we'd know this is wrong" or a Transform-if. lean-canvas positioning claims are the usual offender; hypotheses.md is the model to copy. **Gate 6 — Fragile refs.** No `file.md:NNN` or `L123` line-number cross-references — use quoted-phrase anchors. (Also enforced mechanically in `scripts/pre-commit-checks.sh`.) **Gate 7 — Numbers cite a source.** Any prod number (R₀, count, %, conversion, price-as-validated) must cite an evidence source — a Mixpanel query, a prod row, a dated session note — not "a number mentioned this turn." No source → label **"unverified"**, never "Validated". Internal consistency is not truth. **Gate 8 — Single-valued-slot reconciliation.** A **single-valued slot** is a strategy-doc heading that must hold exactly **one** current answer (the page hero, the active channel bet, the active market focus) — as opposed to a **bet-list** like `hypotheses.md`, where accumulation is correct. Gates 1/4 are blind to this: three "lead the page with X" directives can each be `UNTESTED`-labeled (Gate 1 pass), carry a falsifier (Gate 5 pass), and not *negate* each other (Gate 3's negation-grep misses non-contradicting directives) — so they silently pile up (the §UVP drift: 2026-07-04 "Get to PMF faster" + 2026-07-11 "divergent-AI hook" both marked "lead"). This gate is deterministic because single-valued slots are tagged in the doc: ``` ``` placed immediately under the heading (convention documented in `docs/CHARTER.md`). A single-valued **directive** is a standalone dated blockquote callout `> **Name (2026-07-04, …).** …`; a `> - **…**` list bullet is an *elaboration* of the one answer, not a competing lead (excluded). **Run it:** ```bash python3 scripts/check-single-value-slots.py docs/lean-canvas.md docs/hypotheses.md docs/theory-of-change.md docs/definitions.md docs/progress.md ``` It counts unreconciled dated directive callouts under each `SINGLE-VALUE` marker (a callout carrying a structured `SUPERSEDED` / `FALLBACK` / `dormant` / `parked` / `demoted` token on its lead-in is treated as reconciled/subordinate, not counted). Exit 2 = a slot has **≥2** competing leads. **Quote the script output** (per this skill's "verdict with no artifact = not-run" rule). On exit 2 → **FIX**: surface the competing directives as an **A/B/C reconcile-to-one for the founder** (never auto-resolve — "never fill in positioning without being told"), then mark the losers with `[SUPERSEDED → …]` or subordinate them explicitly (primary + `[FALLBACK …]`). Adding a *new* directive to a `SINGLE-VALUE` slot without superseding/subordinating the incumbent is the exact FIX this gate blocks. This is the same logic the pre-commit `check-single-value-slots.py` canary enforces at commit time (defense-in-depth). ### Step 3 — Precondition: record the decision (Sync only) Before writing **any** strategy-doc change, the decision + its falsifier must exist in `decisions.md` (on the branch resolved in Step 0). `/kdd` is user-triggered and cannot auto-fire, so a "capture it later" hand-off orphans the doc edit — it asserts a position with no recorded kill-condition (the exact failure Gate 5 prevents). - Already in decisions.md → cite it. - Not yet → write the entry now (the user invoked this skill = authorization), using `/kdd`'s decisions.md format with a `[product]` tag and a one-line falsifier. `/kdd`'s deeper meta-reflection still runs separately when the user calls it. ### Step 4 — Apply (Sync) / report (Audit) - **Concurrency check:** re-run `git rev-parse HEAD` and `git status --short docs/`; if the four docs changed since Step 0's base, re-read before editing — a concurrent `/kdd`-at-merge or co-tenant edit must not be clobbered. - **Sync — two classes of change (the auto-vs-surface contract):** - **Mechanical → apply automatically:** fix fragile line-refs (Gate 6), add falsifiers (Gate 5), merge exact-duplicate framings, and apply the spine already settled in the Step-3 decision entry. - **Judgment → surface to the founder as A/B/C options, never resolve silently** (the "Founder decisions" rule — never fill in positioning / category / pricing without being told): every contradiction (Gate 3), every stale-fact / status reframe (Gate 1), every deletion (Gate 4, propose-only), and any positioning wording. Present each as: *current text · why it's stale/contradictory · 2–3 resolution options*; apply only the chosen one. Update the Validation Status block with the new evidence once resolved. - **Audit:** output the punch list grouped by gate, one line per violation in the shape ` | | "" | ` (matching the precision pre-commit Gate F already prints). A bare count is not actionable for a 50-item bloat list. No writes. ### Step 5 — Self-check Branch placement was resolved in Step 0 (decision + docs on `main` / a docs branch); confirm it held. Then verify every gate before writing. Self-check (**each box must cite its gate-report artifact** — a ticked box with no quoted evidence counts as not-done): - [ ] Branch resolved before any write (Step 0.1) — decision + docs on main / docs branch - [ ] All four docs read this session (Step 0) - [ ] Sync delta expressible as "X was true; now Y, because <evidence>" - [ ] Gate 1: no unsourced status word / number; definitions.md carries none - [ ] Gate 2: lock grep run (output quoted); any override names new evidence - [ ] Gate 3: negation greps run (terms quoted); no anchor broken, no contradiction left standing - [ ] Gate 4: every deletion shown + confirmed; no falsifier-bearing block cut; relabeled box has a `Dormant` sibling (active-on-top check, grep quoted) - [ ] Gate 5: every new claim has a one-line falsifier - [ ] Gate 6: no line-number cross-refs introduced - [ ] Gate 7: every number cites a source or is labeled unverified - [ ] Gate 8: `check-single-value-slots.py` run (exit code + output quoted); no `SINGLE-VALUE` slot has ≥2 unreconciled leads - [ ] Decision + falsifier recorded in decisions.md (Step 3) - [ ] Concurrency re-check passed (Step 4) ### Step 6 — Confirm + hand off Report: docs touched, gate report (pass/fix/warn with artifacts), the decision entry written, and the next step (`/kdd` for meta-reflection; `/slava:maintain:claude-md` if CLAUDE.md needs a pointer). **GTM-drift detect.** After applying, compare the *active* channel/posture in `lean-canvas.md` (the structural channel bet) against `docs/goals.md` §Active (the tactical funnel). If they name **different active channels** (e.g. the canvas says founder-direct while goals still runs coaches-first) that is **drift** — flag it, quoting the two active-channel phrases you compared. **Fix `goals.md` in this same edit** (Gates 1 + 3 only) when the drift was caused by the sync you just applied — a status or lead you changed in a gated doc that `goals.md` still contradicts. If you leave it unfixed, say so explicitly in the Step-6 report and why. **Hand off only `.private/docs/gtm-launch-icp-worksheet.md`** (CHARTER rule 1 — private, contains names): "the private residue needs updating to match the strategy docs; no skill owns it — update it directly." **Why this changed (2026-07-23):** the prior rule was detect-and-hand-off for `goals.md` too. `decisions.md` records two such hand-offs; neither produced the edit, and a stale page-lead copy survived in `goals.md` for nine days after the wedge flip. **Honest limit:** this binds only the path that runs *inside this skill*. `/day` and the kanban `PATCH /api/goals` endpoint write `goals.md` outside it, ungated. --- ## Template (gate report + decision stub) ``` docs-strategy-update — Branch:
Base: Delta: > # sync only Docs touched: Gate report (every verdict cites its artifact — grep output, anchor, or "0 matches"): 1 premature-fact ........ PASS|FIX|WARN 2 reversal-lock ......... PASS|FIX|WARN 3 cross-doc ............. PASS|FIX|WARN 4 bloat (prune) ......... PASS|FIX|WARN 5 disproof .............. PASS|FIX|WARN 6 fragile-refs .......... PASS|FIX|WARN 7 numbers-cite-source ... PASS|FIX|WARN 8 single-value-slot ..... PASS|FIX|WARN Decision recorded (decisions.md): ## [product]: Decision: <Y> Falsifier: <how we'd know this is wrong> Applied: <files> | Punch list: <n items> (audit) Next: /kdd (meta-reflection) · /slava:maintain:claude-md (if CLAUDE.md pointer) ``` --- ## Quality Gates (Agent Self-Review) - [ ] Ran in the correct mode (sync vs audit) — auto-detected, not asked - [ ] Branch resolved before the decision write (Step 0.1) - [ ] Gate report produced with a verdict + quoted artifact per gate (no gate silently skipped or rubber-stamped) - [ ] No status word / number written without an evidence source (Gates 1, 7; Gate 7 wins ties) - [ ] No block deleted without showing it first (Gate 4 propose-only) - [ ] Judgment calls (contradictions, stale-fact / positioning reframes) surfaced as A/B/C options — never silently resolved; only mechanical cleanup applied automatically - [ ] Decision + falsifier in decisions.md before the doc write (Step 3) --- ## Related Skills - `/kdd` — owns decisions.md + meta-reflection; this skill writes the decision stub as a precondition, `/kdd` does the deeper pass - `/slava:maintain:claude-md` — gate for CLAUDE.md / `.claude/rules/` changes - `/slava:build:create-spec` — when the output is a tracked feature, not a strategy-doc change - `/slava:think:falsify` — when a strategic claim itself needs first-principles stress-testing before it is written