Skip to content

Planet Pivot Playbook

Captured 14 May 2026 from the Claw v0a → v0b multi-vendor expansion. Apply when an existing planet's scope no longer matches what Sush wants to learn out loud about — either fold the new scope in, or spin a sibling planet that shares engineering DNA.

When this applies

Any session where Sush proposes either:

  • A new planet for a topic he wants to learn (e.g. "let's make a Claude planet")
  • A scope expansion of an existing planet (e.g. "can Claw cover OpenAI too?")
  • A brand reframe that touches identity (tagline, audience, IA, voice rules)

Read this BEFORE locking any decisions. The first reaction is usually wrong; the right answer comes out of 4-6 turns of structured tradeoff conversation + one rubber-duck pass.

TL;DR — the 6 things that mattered

  1. Multi-turn requirements gathering beats one-shot scoping. Don't commit on turn 1. Use ranked tradeoff tables, not "what do you want?" questions.
  2. Call the rubber-duck after planning, before implementing. It saved this project from a content treadmill + scope sprawl. Find blind spots while course-corrections are cheap.
  3. Sush's primary-user reality changes the calculus. "No external audience yet" + "I want one place for everything" can flip a recommendation from "separate planets" to "fold." Don't anchor on assumptions Sush hasn't confirmed.
  4. Content shape (Cat A vs Cat B) determines IA. When a planet wants to cover both developer infrastructure (install/run) AND hosted products (sign-in/use), one shared IA breaks. Use a primary wing + lightweight secondary wing.
  5. Sourced-seed > empty templates. Day 1 the AI populates the planet as sourced from public docs so Sush has a learning roadmap. He upgrades to tried as he experiments. Empty tabs = "I don't know what to try."
  6. Migration discipline matters more than feature ambition. Batch 0 = foundation (identity reframe + schema + voice-lint + nav + placeholder hubs). Defer the riskiest piece (URL migration of existing live content) to a fresh session.

Pattern A — Multi-turn requirements gathering ("creative-juice arc")

The arc that worked for Claw v0b:

Turn Question What flipped
1 Claude-only OR vendor-agnostic dev tooling? Vendor-agnostic chosen (future-proof, honest comparison is the rare angle)
2 Separate planet ("Forge") OR fold into Claw? Sush revealed nobody outside him uses Claw yet → audience-disruption argument evaporated → fold chosen
3 Vendor-first OR topic-first IA? Topic-first proposed → Sush asked about NotebookLM/Perplexity → Cat A vs Cat B problem surfaced → vendor-first eventually wins
4 How handle Cat A (dev infrastructure) vs Cat B (hosted products)? Rubber-duck recommended β-lite: primary Dev Tools wing with §1-§10 + lightweight Hosted Notes wing
5 Loose guardrails reality check Locked OUT list + positive inclusion test (5 questions a page must answer)
6 Audience confirmation + Day-1 product list + execution plan Slightly broader audience (junior devs welcome), heavily seeded Day-1 (~70 pages), 6-batch execution plan

What made each turn productive

  • Ranked tradeoff tables, not open questions. Present 3-4 paths with pros/cons/verdict, not "what do you want?". Sush picks a path or describes a different one.
  • One question per ask_user call. Don't bundle. Each question unlocks the next.
  • Concrete mockups for hard concepts. When Sush said "I can't picture topic-first IA", ASCII mockups of vendor-first vs topic-first vendor-first cleared it instantly.
  • Honest reversals when new info arrives. When Sush revealed "no audience yet", I reversed my earlier "separate planets" recommendation rather than defending it. Reversing is cheaper than digging in.
  • Affirmations + ONE focused question, not chains of questions. Each turn followed the creative-juice response pattern (affirm what's right → ranked paths table → better-than-asked add-ons → risks to watch → ONE scope question).

Anti-patterns to avoid

  • ❌ Asking "what do you want?" on turn 1 — Sush often can't articulate yet; that's literally what he said this session ("do you want to ask questions to me to refine it and get the full content which i am not able to articulate now")
  • ❌ Locking in scope before the rubber-duck pass
  • ❌ Anchoring on assumed audience/SEO equity that hasn't been confirmed
  • ❌ Bundling multiple unrelated decisions into one question
  • ❌ Defending an earlier recommendation after new context arrives

Pattern B — When to call the rubber-duck (and what to ask)

This session's rubber-duck pass caught 3 blocking issues that would have cost weeks if shipped:

  1. Scope was too broad ("all AI tooling reference") — Claw's identity is load-bearing. Reframe narrower: "practitioner's field notebook for AI tools you can run, wire, script, compare, or operationally reason about." Excludes NotebookLM/Perplexity from §1-§10 naturally.
  2. Auto-crawl was a content treadmill — 6+ source feeds, weekly triage, "the inbox becomes the product." Shrink to: official changelogs of covered tools + Simon Willison. Max 5 inbox items/week, max 2 published updates/week. Caps prevent burnout.
  3. Verification contract was bigger than I thought — multi-vendor verification needs structured test-context object (tool · version · platform · accountTier · testedBy · testedAt · notes). "tried-on-claude" isn't enough. The fact that the structure feels heavy IS the signal scope was too wide.

When to call it (mandatory checkpoints)

  • ✅ After locking the design but before implementing
  • ✅ When you find yourself agreeing with Sush too easily (am I caving without thinking it through?)
  • ✅ When the design feels right but you can't articulate WHY it's right
  • ✅ When proposing major scope expansion (multi-week+ effort)
  • ✅ When introducing a new IA, schema, or content contract

What to give it

  • Full context with file pointers (the duck reads files via filesystem)
  • The current plan + all locked decisions so far
  • The 3-4 options you're weighing for the next decision
  • A specific list of questions you want answered (don't say "what do you think?")
  • Permission to push back on the consolidation — "did I cave too easily?"

How to use the output

  • Adopt findings that prevent bugs or scope-creep
  • Adopt in spirit findings that point at a real problem with a different fix in mind
  • Set aside findings that significantly complicate without clear benefit
  • Document what changed in your plan after the critique — Sush wants to know the duck's value

Pattern C — Sourced-seed content lifecycle

The big mental flip from this session: Claw is a learning ROADMAP, not a publish-when-tested reference.

Stage 1: SOURCED   ← Copilot researches public docs and drafts comprehensive entry
           ↓
Stage 2: TRIED     ← Sush actually runs it on his machine (date · version · platform captured)
           ↓
Stage 3: VERIFIED  ← Sush considers it correct (no surprises)
           ↓
Stage 4: DISPUTED  ← A reader raised a correctness issue (linked discussion)

   PLANNED state = stub, not in nav until promoted

Why this matters

  • Empty tabs = "I don't know what to try." Heavily-seeded tabs = "Here's my learning queue laid out."
  • Verification context captures honesty. Different versions of the same tool can behave differently. claude-code v1.2.3 on macOS Pro tier is a different claim from claude-code v2.0 on Windows Team tier.
  • The AI does the heavy lifting (research from public docs); Sush adds the human-tested signal over time. Asymmetric workload that respects both contributors' strengths.

Day 1 vs Ongoing economics

  • Day 1: Copilot researches + drafts ~70 sourced pages across 5 vendor hubs. Heavy upfront cost, but unblocks Sush's whole learning queue.
  • Ongoing: Sush experiments, upgrades entries to tried with margin-note commentary. Low marginal cost per upgrade.
  • Auto-crawl comes LATER (Phase 1.1) — only after publishing rhythm proves out.

How to implement

  • verificationState enum with all 5 states (planned · sourced · tried · verified · disputed)
  • Optional verificationContext object on tried/verified entries
  • VerificationBanner component shows different copy + colour per state
  • Audit script enforces every applicable entry has a state
  • Voice-lint enforces public-source-citation for sensitive vendors (e.g. Microsoft public-domain check)

Pattern D — Cat A vs Cat B problem (vendor scope shape)

When a planet wants to cover both developer infrastructure (install/run/configure) AND hosted products (sign-in/use), one shared IA breaks.

Category Examples Setup needed? Hardware? Plugins/MCP? Security model?
Cat A — Dev infrastructure OpenClaw · Claude Code · Codex CLI · Gemini CLI · M365 ATK · Copilot Studio · Aider · Cursor · Windsurf ✓ install steps ✓ matters ✓ MCP/plugins/connectors ✓ self-managed
Cat B — Hosted product NotebookLM · Perplexity · ChatGPT web · Claude.ai · Mistral Le Chat · Gemini chat ✗ just sign in ✗ browser ⚠️ some extensions ✗ vendor-managed

Three options for handling the asymmetry

Option What it is When to use
α. Sharpen to Cat A only Drop hosted tools entirely. Honest scope discipline. When Sush has zero interest in Cat B and doesn't want them mentioned.
β-lite. Primary wing + lightweight Hosted Notes wing ⭐ Recommended Cat A gets full §1-§10. Cat B gets shorter dossiers (Sign-up · Use Cases · Limits · Privacy · Compare · Pricing). When Sush wants some hosted tool coverage but not as much depth. Solves "NotebookLM under §2 Setup → Laptop" awkwardness.
γ. Adaptive sections per vendor Sidebar dynamically reflects what's applicable per vendor. ❌ Avoid. Dynamic sidebars feel unstable. Too clever.

The fourth shape (declined this round)

Mode-first IA (replace §1-§10 with: Run locally · Connect to repos · Build agents · Use hosted research · Compare choices · Security/privacy · Updates) is conceptually elegant but a heavy rebuild. Only adopt if greenfield; not worth migrating an existing planet.

Pattern E — Microsoft slice discipline (data classification)

Sush works at Microsoft NZ as a Copilot Solution Engineer. Anything he learns about Microsoft Copilot/Studio/Foundry from internal sources (WorkIQ · ADO · Teams · SharePoint · customer engagements) is MICROSOFT CONFIDENTIAL. Personal public surfaces (Claw, Plain AI, Earth blog, etc.) must use ONLY publicly-sourced material.

The clean line (Earth vs Claw)

Earth (aguidetocloud.com) Claw (claw.aguidetocloud.com)
Audience Anyone (users, learners, decision-makers) Tech practitioners (builders, tinkerers)
Tone Polished, curated Field notes, honest, "I tried this and broke it"
Microsoft slice "How to USE Copilot" — features, blog explainers, comparison matrices, cert paths "How to BUILD with Copilot" — ATK, Studio, Foundry, declarative agents, MCP integration
Example pages Copilot Feature Matrix · "April 2026 updates" blog · cert tracker "Set up ATK on Windows" · "Declarative agent manifest from scratch" · "Wire MCP into Copilot Studio"

The enforcement

// scripts/voice-lint.mjs — extract from the Microsoft public-source-citation check
const MS_PUBLIC_DOMAINS = [
  'learn.microsoft.com',
  'github.com/microsoft',
  'github.com/microsoftgraph',
  'github.com/OfficeDev',
  'devblogs.microsoft.com',
  'techcommunity.microsoft.com',
  'azure.microsoft.com',
  'microsoft.com/en-',
  'docs.microsoft.com',
];

// If frontmatter has vendor: "microsoft", `sources:` must include
// at least one URL matching one of these domains.

Why this matters operationally

  • Voice-lint blocks any Microsoft entry shipping without a public source citation
  • The lint runs in CI on every push
  • Sush + Copilot share the cognitive load — Copilot writes the entries, Sush enforces "is this internal-sourced?" gut check, CI provides the safety net

Sush's mental model when writing Microsoft content

  • ✅ Microsoft Learn docs (learn.microsoft.com) — public
  • ✅ Official Microsoft GitHub repos (github.com/microsoft/*, github.com/OfficeDev/*) — public
  • ✅ Microsoft devblogs + techcommunity — public
  • ✅ Sush's own experiments at home on a personal tenant — public observations
  • ❌ Customer engagement detail — never anywhere
  • ❌ WorkIQ search results / internal Teams chat / SharePoint docs — internal
  • ❌ Pre-GA features under NDA — internal
  • ❌ Internal customer success stories — internal

Pattern F — Batch 0 migration phases (safe order)

When pivoting a live planet, run Batch 0 in this order — lowest risk first, highest risk last and ideally deferred to Batch 0b.

Phase 0.1 — Identity reframe (lowest risk · copy/meta only)

  • Banner / BaseLayout description default / home page title + description
  • About page (§0.1 What this is, §0.2 Why this exists, etc.)
  • Methodology page (verification states · scope guardrails · independence statement)
  • Header brand subtext
  • public/llms.txt
  • README.md
  • package.json description
  • Cosmos Atlas atlas.json (one-line tagline update)
  • Planet playbook (in learning-docs) — add admonition section ABOVE existing TL;DR, preserve historical record

Why first: Pure copy changes. Nothing structural. Builds confidence + visible signal of direction before anything risky.

Phase 0.2 — Schema + frontmatter migration (medium risk)

  • Update src/content.config.ts with new schema (new fields, expanded enums, structured objects)
  • Write a migration script (e.g. scripts/migrate-frontmatter-multivendor.mjs):
  • Idempotent (safe to re-run)
  • Dry-run by default (--apply to write)
  • Handles CRLF line endings on Windows
  • Maps old enum values to new
  • Adds new required/default fields to existing files
  • Run migration with --apply
  • Update all consumer code (components + page templates) to use new field names
  • Update CI audit scripts (audit-verification-states.mjs etc.) with new vocabulary
  • Restart dev server with .astro cache cleared (Astro can cache stale schema state)

Gotchas: - Astro content store can cache a failed validation state across the migration; clear .astro/ directory + restart dev server - The same enum/state name often appears in BOTH frontmatter (validation) AND body text (prose documentation). PowerShell -Raw -replace across all .mdx files catches body-text references. - ~20+ consumer files often reference state names. Use grep to find them all, then either mass-replace or update central component badge functions to accept the new vocabulary.

Phase 0.3 — Voice-lint extension (low risk · additive)

  • Add OUT-list patterns (advisory flags for scope-drift signals)
  • Add data-classification rules (e.g. Microsoft public-source-citation gate)
  • Add inline annotation pattern (e.g. <!-- voice-lint:ignore -->) for docs that legitimately list forbidden words
  • Test against current content — should still pass

Phase 0.4 — Templates + nav (additive, placeholders are OK)

  • Build new reusable components (VendorTabs.astro · VendorHub.astro · etc.)
  • Inject new nav into BaseLayout.astro
  • Create placeholder hub pages for each new vendor/section that lists upcoming products with status (live / coming-in-batch / phase-2 / planned)
  • Do not require content batches A-E to be done first; placeholders communicate direction
  • Full build verifies (look for build errors, not just dev-server happy path)

Phase 0.5 — URL migration (DEFER TO BATCH 0b)

If existing content lives at URLs that don't fit the new IA (e.g. /setup/laptop/ should become /openclaw/setup/laptop/):

  • ❌ Don't rush this at the end of a long session
  • ✅ Open a new session with fresh energy
  • ✅ Plan the redirect strategy first (Cloudflare _redirects vs Astro middleware)
  • ✅ Test ALL redirects locally before pushing
  • ✅ Update internal links + sitemap
  • ✅ Deploy + verify each redirect works on live

Pages control-file pitfall (caught Batch 0b · 2026-05-14)

If the planet uses a custom Direct Upload deploy script (scripts/deploy.mjs via Cloudflare Pages REST API — necessary when Wrangler is broken on win32-arm64), audit it for _redirects/_headers handling BEFORE relying on a redirect-heavy migration.

The Direct Upload REST API does NOT auto-extract Pages "control files" (_redirects, _headers, _routes.json, _worker.js) the way Wrangler does. Without explicit handling, they get uploaded as ordinary static assets at /_redirects etc. — Cloudflare serves the file contents but never applies the rules. Symptom: new URLs work, but legacy URLs return 404 instead of 301.

Reference implementations to copy from: plainai/deploy.mjs (uses SPECIAL set + appends as FormData fields) or cosmos-atlas/deploy.mjs (header explicitly says "adapted from plainai"). Do NOT copy from claw-planet/scripts/deploy.mjs or agentic-planet/scripts/deploy.mjs pre-2026-05-14 — those were the buggy lineage; the fix landed in claw-planet@ba65183 and agentic-planet@0c938e8 respectively.

The fix pattern: 

const CONTROL_FILES = new Set(['_redirects', '_headers', '_routes.json', '_worker.js']);
// In buildManifest: if (CONTROL_FILES.has(rel)) { controlFiles[rel] = buf.toString('utf8'); continue; }
// In createDeployment: for (const [name, content] of Object.entries(controlFiles ?? {})) {
//   form.append(name, new Blob([content], { type: 'text/plain' }), name);
// }

Smoke-check pattern to catch this fast: split your smoke-check into expect200 and expect301 lists, and for expect301 verify the Location header target — not just that status is 3xx. A status-only check passes a redirect-to-wrong-target silently. See claw-planet/scripts/smoke-check.mjs for the reference template.

CI deploy gate

Run these BEFORE pushing each batch:

node scripts/voice-lint.mjs          # forbidden words + OUT-list + Microsoft sources
node scripts/integrity-check.mjs     # broken internal links + coverage mismatches
node scripts/audit-claims.mjs        # entry counts match coverage.json
node scripts/audit-verification-states.mjs  # every applicable entry has a state
node scripts/smoke-check.mjs         # live URL smoke test
npm run build:no-search              # full production build

If any fail, fix before pushing. If all green, push + verify GitHub Actions auto-deploy + smoke-test live URLs after deploy lands.

File map — Claw v0b expansion as a worked example

Files touched (60+ in claw-planet repo + 1 each in cosmos-atlas + learning-docs):

Category Files What changed
Identity copy src/components/Banner.astro · src/layouts/BaseLayout.astro · src/pages/index.astro · src/pages/about.astro · src/pages/methodology.astro · src/components/Header.astro · public/llms.txt · README.md · package.json New tagline, new audience def, new lane statement, scope guardrails section, OUT list
Schema src/content.config.ts New vendor enum (5) · product optional · verificationContext object · 5-state verificationState enum
Migration tooling scripts/migrate-frontmatter-multivendor.mjs (NEW) One-shot idempotent script for the 26 MDX files
Content 26 .mdx files under src/content/**/ vendor: "openclaw" + product: "openclaw-runtime" added · old state names → new · body text terminology updated
Consumer code src/components/{Sidebar,MobileDrawer,FieldNote,CatalogTable,VerificationBanner}.astro · src/utils/og-render.ts · src/data/updates.ts · 7 × src/pages/*/[slug].astro · 7 × src/pages/*/index.astro · src/pages/setup/compare/index.astro · src/pages/faq/index.astro Badge functions, state label maps, state→class maps updated for new vocab
CI scripts/voice-lint.mjs · scripts/audit-verification-states.mjs OUT-list patterns · Microsoft source-citation gate · voice-lint:ignore annotation · new vocab
Nav src/components/VendorTabs.astro (NEW) · src/layouts/BaseLayout.astro Sticky sub-nav · 5 vendor tabs + Compare + Updates · legacy URL detection
Hub system src/components/VendorHub.astro (NEW) + 5 × src/pages/{openclaw,anthropic,openai,google,microsoft}/index.astro (NEW) Reusable hub component · 5 placeholder vendor hubs with product cards + status
Cosmos cosmos-atlas/src/data/atlas.json Claw planet entry: tagline · audience · content · founder · stats · lastShippedAt
Memory learning-docs/docs/cosmos/claw/playbook.md Admonition section above existing TL;DR documenting the v0b expansion

Lessons learned (May 2026)

Things I got wrong and had to course-correct

  1. First recommendation was "separate planets" (Forge + Claw). Reversed when Sush revealed no audience yet + 60-70% scaffolding overlap. Lesson: don't anchor on assumed brand equity that hasn't been confirmed.
  2. First IA was "topic-first" with vendor filter pills. Failed Sush's NotebookLM/Perplexity test (Cat A vs Cat B problem). Lesson: ask about asymmetric content shapes BEFORE proposing IA.
  3. First plan had aggressive auto-crawl (6+ source feeds). Rubber-duck flagged as content treadmill. Lesson: when proposing automation, ask "what's the maintenance burden?" and "what's the realistic triage cadence?"
  4. Underestimated the verification contract upgrade. "Tried-by-claude" isn't enough — different versions/platforms/tiers behave differently. Structured verificationContext is the right level. Lesson: when adding a new dimension (e.g. vendor), check what other dimensions are now implicit.

Things I got right that paid off

  1. Multi-turn requirements gathering. 6 turns of ask_user with ranked tradeoff tables. Each turn unlocked the next. Better than trying to one-shot scope.
  2. Calling the rubber-duck after the plan but before implementing. Caught 3 blocking issues. Cost: 5 minutes of conversation. Benefit: weeks of saved work.
  3. Heavily-seeded sourced-content pattern. Sush's correction ("if you keep it blank i dont even know what to try") reshaped the whole Day-1 scope. ~70 pages of sourced content + Sush upgrades to tried = the right division of labour.
  4. Batch 0 = foundation only. Identity + schema + voice-lint + templates + placeholders. Deferred URL migration to Batch 0b. End-of-long-session migrations break production.
  5. OUT-list locked in voice-lint. Without explicit scope discipline, multi-vendor planets drift into "AI everything." The 5-question positive inclusion gate + voice-lint pattern enforcement is the safety net.

Process patterns to reuse

  • Affirm what's right BEFORE proposing tradeoffs. Sush's instincts are usually directionally right; pure pushback feels dismissive. Always lead with 2-4 bullets of "here's what's right about what you said."
  • Ranked paths table over open questions. "Three paths: A, B, C with verdict X" beats "what do you want?".
  • 8-10 better-than-asked add-ons. After locking the direction, propose enrichment ideas Sush hasn't asked for. They sharpen the design.
  • ONE focused question per ask_user call. Bundling multiple questions = decision fatigue.
  • Honest reversals. When new info arrives, reverse cleanly. "I was anchoring on X; with your new context, Y is the better call."

Anti-patterns to avoid

  • ❌ Don't reframe the planet's NAME if it has even small brand equity. Domain reuse is fine; visual rename is high-cost. We kept "Claw" as the name; only the tagline and scope changed.
  • ❌ Don't migrate URLs at the end of a long session. URL migrations have many small risks (broken redirects, sitemap drift, internal-link breakage). They benefit from fresh energy.
  • ❌ Don't auto-crawl 6+ source feeds in v1. Start with 1-2 high-signal feeds (official changelogs + Simon Willison). Expand when you've proven you can keep up.
  • ❌ Don't force Cat A and Cat B through the same IA. NotebookLM doesn't have a "§2 Setup → Laptop." Pretending it does = forced content.
  • ❌ Don't ship a verification state vocabulary that needs upgrading mid-batch. The 5-state + verificationContext upgrade was a Batch 0 task, deliberately done before any vendor content lands.
  • ❌ Don't skip the rubber-duck on non-trivial pivots. "I've thought this through" is exactly when blind spots are most dangerous.

Quick reference — checklist for the next planet pivot

When Sush proposes a planet pivot or scope expansion, before writing any code:

  • [ ] Read this playbook + the planet's existing playbook + cosmos-philosophy
  • [ ] Do 4-6 turns of ask_user with ranked tradeoff tables (don't one-shot scope)
  • [ ] Lock the audience definition (who is this for? primary user? secondary?)
  • [ ] Lock the OUT list (what stays off the planet to prevent drift?)
  • [ ] Lock the IA shape (vendor-first · topic-first · mode-first · hub-and-spoke · etc.)
  • [ ] Identify Cat A vs Cat B asymmetry if applicable
  • [ ] Define the verification contract (states + optional context object)
  • [ ] Decide content lifecycle (sourced-seed vs publish-when-tested)
  • [ ] Cap auto-crawl scope (max source feeds + max triage cadence)
  • [ ] Call the rubber-duck with full context + specific questions
  • [ ] Update plan accordingly
  • [ ] Save plan.md to session workspace
  • [ ] Mirror todos into SQL tracking
  • [ ] Run Batch 0 in safe order: identity → schema → voice-lint → templates → URL migration deferred
  • [ ] Run all CI scripts BEFORE pushing
  • [ ] Push + verify GH Actions + smoke-test live URLs
  • [ ] Add admonition section to the planet's playbook in learning-docs
  • [ ] Update cosmos-atlas/src/data/atlas.json if planet copy changed
  • [ ] Update ~/.copilot/session-journal.md with ≤30-line entry
  • [ ] Write follow-ups prompt for next session (this is the kickoff doc)

See also