dsh-compound-engineering 0.0.0-stage → 0.1.0

package/skills/ce-simplify-code/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: ce-simplify-code
+description: "Simplify code for clarity, reuse, quality, and efficiency while preserving behavior, and prune tests and comments that carry no value. Use after implementation and before review, or to audit tests or comments in any part of a repo; use ce-debug for bugs."
+argument-hint: "[blank for current branch changes, or describe what to simplify or audit] [mode:pipeline] [proof-test:<path>]"
+---
+
+Simplify code for clarity, reuse, quality, and efficiency, and prune tests and comments that carry no value, while preserving exact behavior. Prioritize readable, explicit code over compact code — fewer lines is not the goal.
+
+## Mode
+
+Strip a `mode:pipeline` token and every `proof-test:<path>` token from the input before reading the rest as the scope. The proof-test path is context for Step 3, never scope; a caller may pass several.
+
+- **Pipeline** when `mode:pipeline` is present, or when no one asked for this run in their own current message: a step of another skill, or a run the agent starts itself, such as at a completion boundary. Work only on the current work, apply fixes without asking or waiting, and return the Step 5 summary to the caller. That summary is for the caller's record; never paste it into a commit, PR body, or other artifact.
+- **Standalone** when the user's own current message asked for this run. Their request sets the scope and focus. Report findings before editing anything, unless the request says to just fix them. Read `references/standalone-report.md` now, and again before applying any reported finding.
+
+## Step 1: Identify scope
+
+Resolve the scope in this order:
+
+1. **User-named scope** is authoritative; do not widen it. In standalone mode it may be the whole repo, an area, or a path.
+2. **Otherwise, in git**, use the current branch versus its base. Without a usable base, use staged and unstaged changes (`git diff HEAD`).
+3. **Outside git or without a diff**, use files the user named or that were edited earlier in the conversation.
+
+In pipeline mode the scope is what the caller passed, else the branch diff. Within it, prune only tests and comments the current work added or changed.
+
+If none of the above produces a non-empty scope, pipeline mode reports "nothing to simplify" and returns. Standalone mode asks the user what to simplify, as `references/standalone-report.md` describes.
+
+**Preflight.** If the scope has no substantive human-authored code — only documentation, generated or vendored files, dependencies or lockfiles, or mechanical churn — report that there is nothing to simplify and stop without reviewers. For mixed scopes, retain only the code and its tests. This check is about the kind of change, never its size: explicit small scopes still run, and any size or cost threshold is the caller's to set.
+
+When the platform's task-tracking capability is available, show the review, apply, and verification outcomes without creating one task per reviewer. Otherwise continue without simulating a task list in chat.
+
+## Step 2: Launch review agents in parallel
+
+Dispatch generic subagents via the platform's subagent primitive (`Agent`/`Task` in Claude Code, `spawn_agent` in Codex) where available; otherwise run the reviews inline or serially. For each reviewer, read its prompt asset from this skill's directory and pass the **full file content** as the subagent's prompt, together with the resolved scope (the full diff or file set), the mode, any proof test, the user's constraints, and the project standards governing the scope (or their file paths):
+
+- `references/personas/code-reuse-reviewer.md`
+- `references/personas/code-quality-reviewer.md`
+- `references/personas/efficiency-reviewer.md`
+- `references/personas/test-value-reviewer.md`, when the scope holds tests
+- `references/personas/comment-reviewer.md`, when the scope holds comments
+
+A standalone request about only tests or only comments runs only that reviewer.
+
+Do not paraphrase these rubrics from memory. Read each file and pass it verbatim, or the reviewer loses the rules that keep the pass behavior-preserving.
+
+Read `references/reviewer-dispatch.md` before dispatching; it covers a full harness, releasing review agents, and the permission mode.
+
+**Model selection.** Use the platform's balanced mid-tier model for these reviewers when the current harness exposes a known override. In Claude Code this is the Sonnet class. In Codex, apply this tier only when the active dispatch primitive exposes an explicit model or custom-agent selector; task wording alone does not select a different model. Otherwise omit the override and inherit the parent model -- a working pass on the parent model beats a broken dispatch.
+
+If the user's or project's active instructions or the live prompt name a model for this subagent, use that model instead of the default tier above. They can name it by the subagent's tier, by its prompt-asset name, or for the subagents being dispatched. Without such an instruction, a model configured for this subagent's role takes precedence over the default tier.
+
+## Step 3: Fix issues
+
+Proceed only after every review outcome is complete, whether returned by subagents or produced inline. In standalone mode, unless the request says to just fix them, report and stop here. Otherwise apply worthwhile findings directly; record false positives and low-value findings as skipped without asking the user.
+
+Inspect beyond the resolved scope when needed to evaluate a finding, but edit only that scope and the import/export lines it needs. For a user-named file or directory scope, those import/export lines must also be inside it; skip any fix that would edit outside the mutation boundary.
+
+Each fix must preserve outputs, errors, side effects, and ordering. If that cannot be established, skip it.
+
+**Never simplify away a safety check.** Preserve trust-boundary validation, data-loss protection, security checks, and accessibility affordances. Skip any finding that would thin or remove one.
+
+**Protect the proof tests.** In pipeline mode, each test the current work relied on to show its change works stays exactly as it is: every `proof-test:` path, else the tests the session's evidence names. Skip any finding from any reviewer that would delete, weaken, rename, move, merge, or rewrite one, or remove or rename the test-only code it calls. Behavior-preserving changes to the production code it exercises still apply. When you cannot tell which tests those are, delete or rewrite none of the tests the current work added or changed.
+
+**Honor caller-passed structure pins.** A plan path passed with the structure-pin constraint is context, not scope. Preserve its `session-settled:` Key Technical Decisions, including deliberate duplication or separation.
+
+## Step 4: Verify behavior is preserved
+
+Run project-wide typecheck and lint. Run tests matched to blast radius: scoped tests for local changes, broader tests for shared or wide-reach changes, and the full suite when the runner cannot scope tests.
+
+Report failures with the check name and relevant output. Fix simplification-caused failures or revert the responsible change. Never weaken or remove a test to make a check pass. A test is removed only as a test-value finding, and any remaining tests that finding named must still pass afterwards.
+
+If no test suite, lint, or typecheck is configured, state that explicitly in the summary; do not silently skip verification.
+
+## Step 5: Summarize
+
+Summarize what was already sound and what improved. Report applied counts by reuse, quality, efficiency, tests, and comments; skipped count; check outcomes; and any comment kept because its constraint could not be encoded. If nothing changed, say so. Do not use net lines removed as the success metric. In pipeline mode this summary ends the skill, not the turn: the caller's next step follows it.

package/skills/ce-simplify-code/references/personas/code-quality-reviewer.md

@@ -0,0 +1,17 @@
+You are the **Code Quality Reviewer**. You receive recently changed code as a diff or resolved file set. Find hacky patterns, while preserving exact behavior. Review for:
+
+1. **Redundant state**: state that duplicates existing state, cached values that could be derived, observers/effects that could be direct calls
+2. **Parameter sprawl**: adding new parameters to a function instead of generalizing or restructuring existing ones
+3. **Copy-paste with slight variation**: first check whether an existing source of truth or verified platform guarantee eliminates the duplication; otherwise consolidate only when behavior-preserving. A branch made reachable by removing a guard or filter is not dead; replace serializers or coercions only after proving exact equivalence.
+4. **Leaky abstractions**: exposing internal details that should be encapsulated, or breaking existing abstraction boundaries
+5. **Stringly-typed code**: using raw strings where constants, enums (string unions), or branded types already exist in the codebase
+6. **Unnecessary wrapper elements (framework-gated)**: in component-tree UI frameworks only, flag wrappers with no layout or behavioral role; skip elsewhere
+7. **Nested conditionals**: ternary, if/else, or switch nesting 3+ levels deep
+8. **Comments**: leave comment findings to the comment reviewer
+9. **Dead code, unused imports, unused exports**: verify project-wide non-use with configured analysis, otherwise structural search. Account for re-exports, dynamic imports, and framework-conventional exports; if uncertain, skip.
+10. **Context-dependent vocabulary**: rename conversation- or iteration-bound and inconsistent terms toward established codebase vocabulary; preserve precise domain terms
+11. **Pre-release compatibility scaffolding**: an interface or data shape that existed only in an earlier iteration of the current unshipped scope is not protected behavior once you verify it has no deployed, persisted, public, external, dependent-branch, or in-repo caller outside the resolved scope. Recommend removing that compatibility path only when every required caller update fits the scope being edited; if uncertain, skip
+
+**Balance.** Do not reduce comprehension, inline named concepts, merge unrelated logic, or remove abstractions whose testability or extensibility purpose is not verified obsolete.
+
+Return each finding as: location (`file:line`), the issue, and the concrete fix. If there is nothing to flag, say so explicitly.

package/skills/ce-simplify-code/references/personas/code-reuse-reviewer.md

@@ -0,0 +1,7 @@
+You are the **Code Reuse Reviewer**. You receive recently changed code as a diff or resolved file set. Find places where the new code duplicates something that already exists, while preserving exact behavior. For each change:
+
+1. **Existing utilities and helpers**: search for behavior-equivalent symbols that replace new functions or inline logic; name the symbol to use
+2. **Standard-library or runtime primitives**: suggest built-ins only when behavior-equivalent for the inputs in play. Skip swaps with UX, locale, sort-stability, or serialization differences.
+3. **Platform, framework, or downstream guarantees**: flag code that hand-maintains a verified guarantee. Name the provider and resulting simplification. Remove only behavior that guarantee directly owns while preserving every output, error, side effect, and ordering. Keep value transformations before downstream projection. Do not combine this with serializer or coercion replacement without tests or direct comparisons covering every relevant value type. Newly reachable branches are not dead code.
+
+Return each finding as: location (`file:line`), the duplication or missed reuse, and the existing utility or built-in to use instead. If there is nothing to flag, say so explicitly.

package/skills/ce-simplify-code/references/personas/comment-reviewer.md

@@ -0,0 +1,24 @@
+You are the **Comment Reviewer**. You receive a resolved scope and the mode (pipeline or standalone). Find comments to delete, and code to reshape so a comment is no longer needed. You report findings; you do not edit.
+
+Comments are deleted by default, and doubt does not save one. Deleting a comment cannot change behavior, which is why this default runs opposite to "if uncertain, skip" elsewhere in this review. Only these survive:
+
+- license and copyright headers
+- notes on behavior forced by something outside our control, such as a dependency, platform, vendor, or protocol, that still holds on a live code path
+- doc comments that define a public API contract
+- links to an issue or spec that explain a constraint code cannot express
+- comments a tool, compiler, or runtime reads; these are code, not prose: directives, pragmas, build tags, type annotations in comments, doctests, generated-file markers, and lint or type suppressions
+- comments the project's written coding standards explicitly require for that kind of code
+
+Words like `IMPORTANT`, "do not remove", "too risky", "fine for now", and long justifications are claims to check, not reasons to keep. Read the code path, and keep the comment only when it describes a keep-list case that is true today.
+
+For a comment that fails the keep list:
+
+- If it restates the code, narrates a change, records task history, or is commented-out code, delete it.
+- If it explains a surprise in our own code, recommend the reshape that makes it unnecessary (rename, extract, type, or restructure), then delete it. In pipeline mode, when the reshape falls outside the scope or would change behavior, still delete the comment and report the reshape as open work.
+- If it states a rule the code must keep, one a later change could silently break and that nothing enforces, recommend encoding the rule as a test or type assertion, then deleting the comment. A comment that only describes what the code already does or accepts is not such a rule; delete it. In pipeline mode, the encoding is one assertion in a test file already inside the scope; when that is not possible, recommend keeping the comment and say why. Never encode a constraint as a new runtime check.
+
+Never recommend rewording or shortening a comment in place of deleting it.
+
+Skip generated and vendored files. In pipeline mode, flag only comments the current work added or changed.
+
+Return each finding as: location (`file:line`), recommended action (delete, reshape then delete, encode then delete, or keep and note), the keep-list check it failed, and for a reshape or encoding the concrete change. Report several comments that share one cause as one finding. If there is nothing to flag, say so explicitly.

package/skills/ce-simplify-code/references/personas/efficiency-reviewer.md

@@ -0,0 +1,11 @@
+You are the **Efficiency Reviewer**. You receive recently changed code as a diff or resolved file set. Find wasted work and resource problems, while preserving exact behavior. Review for:
+
+1. **Unnecessary work**: redundant computations, repeated file reads, duplicate network/API calls, N+1 patterns
+2. **Missed concurrency**: independent operations run sequentially when they could run in parallel
+3. **Hot-path bloat**: new blocking work added to startup or per-request/per-render hot paths
+4. **Recurring no-op updates**: guard polling, event, and reducer updates; verify wrappers preserve the platform's no-change signal, such as a same-reference return
+5. **Unnecessary existence checks**: pre-checking file/resource existence before operating (TOCTOU anti-pattern) — operate directly and handle the error
+6. **Memory**: unbounded data structures, missing cleanup, event listener leaks
+7. **Overly broad operations**: reading entire files when only a portion is needed, loading all items when filtering for one
+
+Return each finding as: location (`file:line`), the inefficiency, and the concrete fix. If there is nothing to flag, say so explicitly.

package/skills/ce-simplify-code/references/personas/test-value-reviewer.md

@@ -0,0 +1,23 @@
+You are the **Test Value Reviewer**. You receive a resolved scope, the mode (pipeline or standalone), and in pipeline mode any proof test. Find tests that cost maintenance without protecting anything, and say what should happen to each. You report findings; you do not edit.
+
+A test earns its place when it protects observable behavior, a credible regression, or an independent contract. It must fail when the behavior it names breaks, and keep passing when only the implementation changes. Review for:
+
+1. **False-confidence tests**: the expected value comes from the code under test, a mock or fixture supplies the result the code should produce, a negative case is rejected by a different guard than the one named, or the test asserts nothing that could fail. A quick check: would it still pass if the code under test returned nothing useful?
+2. **Implementation-coupled tests**: the test asserts calls between internal parts, or would break under a behavior-preserving refactor. Recommend rewriting it at the owning boundary; recommend deletion only when a stronger test already covers the behavior.
+3. **Duplicate coverage**: the same contract is asserted at several layers, or near-identical tests differ only in input. Keep the one at the strongest boundary and delete the rest, or merge them into one table-driven test.
+4. **Test-only seams**: a production export, flag, wrapper, or hook that only tests use. Report the test and the seam as one finding, since deleting the test also deletes the seam. In pipeline mode, flag only seams the current work introduced.
+5. **Restated inventories**: copied fixtures, export lists, or source text that only mirror the code.
+
+Never recommend deleting:
+
+- a test that fails before any change; report it as a possible defect
+- a source-inspection test that fails when a user-facing key, byte, or path changes and survives an identifier-only rename
+- the only test guarding a public API, protocol, config or schema, migration or storage format, security behavior, or release or package contract
+- in pipeline mode, a proof test, or the test-only code it calls
+- a test only because it is slow, static, or looks like the implementation
+
+Before flagging, run the test and read the whole test, the code it covers, that code's callers, and the tests that overlap it. Recommend deleting a test only after seeing it pass; one that fails or cannot be run is a possible defect, never a deletion candidate. When a test claims behavior of a dependency, read the dependency's source or types. In standalone mode, check the test's history when it may explain why the test exists. A deletion finding must name the remaining test that covers the same ground, or show that the test asserts nothing that could fail, so no coverage is lost; without one of those, do not flag it. Prefer a few well-evidenced findings over a long speculative list, and do not recommend new tests except as the replacement in a rewrite.
+
+In pipeline mode, flag only tests the current work added or changed.
+
+Return each finding as: location (`file:line`), category, recommended action (delete, merge, rewrite, or report as defect), the failure the test can catch, the remaining test that covers it, any seam its deletion unlocks, and how you checked. If there is nothing to flag, say so explicitly.

package/skills/ce-simplify-code/references/reviewer-dispatch.md

@@ -0,0 +1,11 @@
+# Reviewer Dispatch
+
+Read this before dispatching the Step 2 reviewers. It covers what happens when the harness is full, how review agents are released, and the permission mode.
+
+A generic subagent is one whose whole brief is the prompt you send it. When the host's subagent tool makes you name an agent, use only a name you have seen the host list, and list its agents before the first dispatch if you have not. Pick the plain one that adds no role of its own, which still counts as a generic subagent. Never pick a specialist, such as a reviewer or worker agent, whose own role prompt, output format, or tool limits would replace or narrow your prompt.
+
+**Bounded dispatch.** Queue the reviewers and launch only as many as the harness accepts at once. A concurrency or active-agent-limit error means the harness is full, not that the reviewer failed: leave the reviewer queued and retry after a slot frees. When a dispatch cannot recover through active work, supported release, or a corrected invocation, run that pass inline using the same prompt asset and disclose the substitution.
+
+**Agent lifecycle.** Collect terminal outcomes, including failures, before cleanup. Close or release review-owned agents when the harness provides caller-owned cleanup, before refilling slots, advancing stages, or returning. Do not message completed agents with no remaining work. Do not infer released capacity from completion or interruption, or invent cleanup operations.
+
+**Permission mode.** Omit the `mode` parameter on the dispatch call so the user's configured permission settings apply.

package/skills/ce-simplify-code/references/standalone-report.md

@@ -0,0 +1,25 @@
+# Standalone Report and Apply
+
+Read this at the start of a standalone run, and again before applying any reported finding. It covers the empty-scope question, when to report instead of applying, the report itself, and how a later request to apply findings works.
+
+## Empty scope
+
+When Step 1 finds no scope, ask the user what to simplify rather than guessing. Use the host's blocking question tool already in the current tool list (match by capability, not by a host-specific name). Presence in the current tool list is proof the tool exists; never call a user-facing question tool to discover whether it exists. If a matching tool is listed but unloaded, use the host's tool-discovery primitive to load that capability — do not search for another host's tool name. Fall back to numbered options on the host's user-visible chat surface only when no such tool is in the list or a real question call errors. Never silently skip the question.
+
+## Report or apply
+
+Report first, and leave every file unchanged, unless the request tells you to make the changes without review ("just fix them", "no need to check with me", "remove the useless comments without asking"). A request to audit, find, review, or list always reports first. When the request does say to fix, apply per Step 3, verify per Step 4, and report what changed in the shape below.
+
+## The report
+
+- Open with one line: what scope was covered, which reviewers ran, and the totals per group.
+- Number findings continuously across three groups: **Delete**, **Refactor**, and **Encode as a test**. Each finding names its location, what is wrong, and the evidence the reviewer returned. A test deletion carries what failure the test could catch, which remaining test covers that (or that the test asserts nothing that could fail), any production seam the deletion unlocks, and how that was checked.
+- When several comments share one cause in the code, report one refactor finding for the cause, not one finding per comment.
+- List tests that fail before any change separately, as possible defects, never as deletions.
+- When nothing qualifies, say so in one line, naming what was covered.
+- For a scope too large for one reviewer to read in full, you may split each review by top-level directory. The report then gives totals per group and the strongest findings, and offers the rest on request.
+- End by saying how to apply: all findings, specific numbers, or a described subset.
+
+## Applying reported findings
+
+Apply only the findings the user picked. Before editing for a finding, re-check it against the current code. If the code under it changed since the report, skip it and say why. Apply the rest under Step 3's rules, verify under Step 4, and summarize under Step 5, listing applied and skipped findings by number.

package/skills/ce-strategy/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: ce-strategy
+description: "Create or update STRATEGY.md. Use when starting a product, adding a strategy doc, or changing direction or roadmap."
+argument-hint: "[optional: section to revisit, e.g. 'metrics' or 'approach']"
+---
+
+# Product Strategy
+
+**The current year is 2026** - use it when dating the document.
+
+`ce-strategy` writes and maintains its part of `STRATEGY.md` - the repo-root project document that captures what the project is, who it serves, how it succeeds, and where the team is investing. The file is shared with other tools and people; this skill writes only the sections `references/strategy-template.md` names. Downstream skills read it when it exists: `ce-ideate`, `ce-brainstorm`, and `ce-plan` for what work is on-strategy; `ce-product-pulse` for the product name and key metrics; `ce-dogfood` for the primary persona. Its frontmatter keys and this skill's section headings are the contract those skills parse - keep them for every section this skill authors; a meaning an existing section already carries is merged into it (`references/update-run.md`).
+
+**Done:** `STRATEGY.md` exists at the repo root and the user has seen what will be written and had an edit pass. For a file in this skill's house format, every required section is filled from answers that survived pushback (or explicitly deferred to a linked legacy doc) and the file matches `references/strategy-template.md`. For a file in any other shape, done is the user-approved minimal edits applied, with the document's shape unchanged. A section the user could not sharpen in two rounds is written as given and named in chat as worth revisiting - a completed run, not a blocked one.
+
+## Boundaries
+
+- **Anchor, not plan.** Strategy is what the product is and why. Features belong in `ce-brainstorm`, schedules and prioritization in the issue tracker, implementation plans in `ce-plan`; do not let them creep into the doc, and do not update the tracker or reconcile in-flight work.
+- **The user answers; the repo only grounds the question.** Use evidence to ask a sharper question, never to fill in a section. Do not derive the strategy from the repo.
+- **Short is a feature.** Push back on expansion rather than adding sections.
+- **Record which metrics matter and where they live**, not what they read today.
+- **Meaning is the contract; the shape belongs to whoever created the doc.** A file that is solely this skill's (`references/update-run.md` states the test) is maintained in house format on every write: headings renamed, sections in the template's current order, missing required sections offered. Do not treat it as multi-writer merely because the file is shared in principle. A file in any other shape, hand-written or from another tool, is read by meaning and edited in its own shape and idiom: no restructuring into the template, no uninvited frontmatter or headings. Either way, two things are never edited: a section carrying an author-approved marker (e.g. `<!-- <tool>: author-approved 2026-07-10 -->`), and a doc the user does not own. For those, report the conflict, or write a separate file that links to it. A targeted update preserves every other section's content exactly. Where that section sits follows the same ownership test: a solely-owned file takes the template's order; a multi-writer file is never reordered. `references/update-run.md` defines the rest and is a required read before you edit an existing file.
+
+## Asking and routing
+
+Ask one question at a time through the host's blocking question tool already in the current tool list. Match by capability; never probe a user-facing tool to discover it. Fall back to numbered options on the visible chat surface only when no such tool is listed or a real question call errors. Never silently skip the question.
+
+Any argument this skill was invoked with — present in the current prompt or conversation, from the user or a calling skill — is a focus hint: a section to revisit (`metrics`, `positioning`, `tracks`; older names such as `approach` or `who it's for` map to the current section) or a scope hint. With none, proceed open-ended and let the file state decide the path.
+
+## Phase 0: Ground and route
+
+Phase 0 produces a repo model and a decision about which phase runs next, whatever the harness reads. `references/grounding.md` is a non-optional load: it carries the full source list and the wording of the disagreement question and the focus hint.
+
+**The repo model** is your working understanding of what this product is. Read `STRATEGY.md` if it exists. Take what the product is from its stated intent and structure - README, `CONCEPTS.md`, `docs/`, sibling docs such as `PRODUCT.md`, what the code is organized around - and bound that read to "what is this and who is it for" rather than profiling the whole repo. Take what is getting attention now from recent commits or PRs. Attention informs only the Tracks question and staleness in an update run; where it disagrees with stated intent, that is a question for the user, never a conclusion. Show the model in chat before the first question: three to five lines on what you take the product to be, who it seems to serve, and where attention has gone, each with its source named, and invite correction. If the model did not supply the product's name, ask for it here - the template's frontmatter and title need it. A repo with no substantive content is a normal path: say so in one line and run the interview ungrounded.
+
+**The next phase** is announced in one line by file state: no file -> Phase 1 ("Strategy doc not found - let's write it."), after the legacy-sibling offer in `references/grounding.md` when one applies; file exists -> Phase 2 ("Found existing strategy - let's review and update.").
+
+## Phase 1: First-run interview
+
+Read `references/interview.md` before the first question - a non-optional load. The opening questions, pushback rules, anti-pattern examples, quality bar, blocking-question tool per host, and the two-round cap live there; improvising from memory produces a passive transcription instead of a strategy doc.
+
+Run the interview in this order (the document itself follows the template's order; Boundaries is asked after the stress test, where its content comes from):
+
+1. Purpose
+2. Positioning
+3. Users
+4. Key metrics
+5. Tracks
+6. Stress test
+7. Boundaries (always written)
+8. Milestones (optional)
+9. Brand (optional)
+
+When every section is captured, read `references/strategy-template.md`, fill it in, present the full draft in chat, offer one round of edits, then write `STRATEGY.md`.
+
+## Phase 2: Update run
+
+Read `references/update-run.md` first - a non-optional load, before the summary, the drift check, or any question. It decides how drift candidates are raised, which section is revisited, and what is preserved untouched. An update run summarizes the file's current state in 3-5 lines, and names any section the repo model suggests is stale as a candidate rather than a verdict. It then revisits the section the focus hint named, or the one the user picks when asked. The user may pick any section; list the drift candidates first, as suggestions rather than as the only choices. Every other section's content is left untouched, and its place follows the ownership test in `references/update-run.md`. Questions and pushback still come from `references/interview.md`, applied as if this were a first run.
+
+## Phase 3: Downstream handoff
+
+Note in one line where the file lives and that `ce-ideate`, `ce-brainstorm`, and `ce-plan` pick it up as grounding on their next run. If no downstream skill has run here yet, suggest `ce-ideate` or `ce-brainstorm` as a next step.

package/skills/ce-strategy/references/grounding.md

@@ -0,0 +1,22 @@
+# Grounding the interview in the repo
+
+Required read at the start of Phase 0, before the repo model is built.
+
+Read `STRATEGY.md` with the native file-read tool.
+
+Then build a **repo model** - your working understanding of what this product is - from two inputs with different jobs:
+
+- **What the product is.** Stated intent (README, `CONCEPTS.md`, `docs/`, an existing `STRATEGY.md`, sibling docs such as `PRODUCT.md` or `VISION.md`) and structure (what the code is organized around, what is public, what is tested) - the authority for the problem, approach, and persona questions. Bound the read to "what is this and who is it for"; do not profile the whole repo.
+- **What is getting attention now.** Recent commits or PRs, informing only the Tracks question and staleness in an update run. A burst of recent work is a fact about the last few weeks, not about what the product is; where it disagrees with stated intent, that is a question for the user ("recent work is mostly in X - is X a track, a temporary push, or unrelated?"), never a conclusion.
+
+If the repo has no substantive content, say so in one line and run the interview ungrounded - a normal path, not a blocker.
+
+## A legacy sibling doc and no `STRATEGY.md`
+
+`STRATEGY.md` is the shared project doc; `VISION.md` and `PRODUCT.md` are legacy names other tools used before converging on it. When one of those exists and `STRATEGY.md` does not, it has already seeded the repo model; before the interview, offer the user the choice of folding it in or linking to it. Folding: this skill creates `STRATEGY.md` in the template's order and carries the legacy doc in - every meaning this run writes - whichever of the template's sections the interview captures - merges with the legacy content that carries the same meaning into one section in the author's words, with any contradiction put to the user; every meaning outside this skill's contribution is carried in under its own heading with content unchanged. The legacy file then becomes redundant: say so and leave its removal to the user (this skill never deletes a user's file; the CE readers take `STRATEGY.md` first and consult a legacy sibling only for meanings it lacks, so a folded sibling is not re-read for the meanings it carried). Linking: leave the legacy file where it is and point to it from the template's sibling line. Never edit the legacy file either way.
+
+Show the repo model in chat before the first question: three to five lines on what you take the product to be, who it seems to serve, and where attention has gone, each with its source named. Invite correction. On a first run the interview then runs in full; an update run still revisits only the section Phase 2 settles on. If it could not supply the product's name, ask for that here - the template's frontmatter and title need it.
+
+## Focus hint
+
+(Also stated in the always-loaded body, which is where it has to fire.) Any argument this skill was invoked with — present in the current prompt or conversation, from the user or a calling skill — is a focus hint: a section to revisit (`metrics`, `positioning`, `tracks`; older names such as `approach` or `who it's for` map to the current section) or a scope hint. With none, proceed open-ended and let the file state decide the path.

package/skills/ce-strategy/references/interview.md

@@ -0,0 +1,179 @@
+# Strategy Interview
+
+Loaded by `SKILL.md` at the start of Phase 1 and revisited per-section in Phase 2. Every section below maps one-to-one to a section in `strategy-template.md`.
+
+For each section: ask the opening question, evaluate the answer against the quality bar, push back when it falls into a named anti-pattern, and capture the final answer in the user's own language.
+
+## Overall Rules
+
+1. **Ask, don't prescribe.** Do not offer menu options for open answers (problem, approach, persona). Use free-form responses. Reserve multi-select for routing decisions.
+2. **Push back once, maybe twice.** If the first answer is weak, name the specific issue and ask a sharper question. If the second answer is still weak, capture what the user has given and note in the draft that the section is worth revisiting. Do not let the interview spiral.
+3. **Quote the user back at them.** When challenging an answer, use the user's own words verbatim. Paraphrasing softens the challenge and is easier to dismiss.
+4. **Keep each answer to 1-3 sentences.** Longer answers are usually hiding something vague. If the user writes a paragraph, ask them to pick the sentence that matters most.
+5. **Don't leak the anti-pattern names.** The user does not need to hear "that's a vanity metric" - just ask the sharper question that follows.
+6. **Ground the question, not the answer.** When the repo model from `SKILL.md` Phase 0 bears on a section, open with what it suggests ("From the README this looks like X - is that the problem?") and let the user confirm or correct; cite repo specifics when an answer contradicts what the repo states. Never write a section from the repo model alone, and never let recent activity stand in for what the product is. Where stated intent and the user's answer disagree, that is the pushback question, and the user's answer is what gets captured.
+
+---
+
+## 1. Purpose
+
+**Opening question:** "What's the core problem this product solves - and what makes that problem hard?"
+
+Strong answers name a specific situation the target user is in, identify what makes the situation hard *right now* (a crux, a constraint, something that isn't easy to route around), and are falsifiable - you could imagine the problem being absent and know the difference.
+
+**Anti-patterns and pushback:**
+
+- **Goal stated as problem** ("the problem is we need to grow revenue") -> "That's a goal, not a problem. What's in the world that's making that goal hard to achieve? Whose situation are you changing?"
+- **Vague wish** ("people need better tools for X") -> "Whose situation specifically? Doing what? What do they try today, and why doesn't it work?"
+- **Symptom, not cause** ("users churn after 30 days") -> "That's a symptom. What's happening in their world that makes them stop caring? What's the underlying condition?"
+- **Too broad** ("communication at work is broken") -> "That's a civilization-scale problem. Narrow it to a situation you can actually affect - which users, doing what, when does it hurt most?"
+- **Feature-shaped** ("there's no good way to do [specific workflow] with AI") -> "That's a missing feature, not the underlying problem. What outcome do users want that the feature would give them?"
+
+**Capture:** One or two sentences naming the user's situation and the crux - the reason the product exists. No solution language.
+
+---
+
+## 2. Positioning
+
+**Opening question:** "Given that problem, what's your approach - the commitment or principle that makes it tractable?"
+
+This is the guiding choice: how the product competes or operates, so that many downstream decisions become easier. It is not the product and it is not a feature list.
+
+Strong answers are a choice (implying alternatives explicitly *not* pursued), are general enough to direct many decisions but specific enough to rule things out, and sound more like "we win by [doing X differently]" than "we do [a list of things]".
+
+**Anti-patterns and pushback:**
+
+- **Fluff / values** ("we're customer-obsessed and move fast") -> "Those are values, not an approach. What are you doing *differently* from the other products users could pick? If the answer applies to any company, it's not your approach."
+- **Feature list** ("we're building AI-powered X, Y, and Z") -> "That's a feature list. What's the underlying bet that makes you pick those features over others? What principle is guiding what you ship?"
+- **Product description as approach** ("we use AI to draft replies") -> "That's what the product does, but what's the *choice* inside it? Every competitor will say the same thing. Your approach should name what you're doing that the obvious alternative isn't - is it a grounding choice, a trust-building commitment, a workflow bet? What are you betting on that they're not?"
+- **Goal restated** ("our approach is to be the market leader") -> "That's still the goal. How does the product win? What choice are you making that competitors aren't?"
+- **Multiple approaches at once** ("we're going deep on enterprise, self-serve, and a consumer app") -> "Pick one as the guiding approach. The others may still get work, but one of them organizes the rest. Which is it?"
+- **Doesn't connect to the problem** (problem: "users can't trust AI output"; approach: "build a fast, beautiful UI") -> "How does that approach solve the problem you named? If there's no line between them, one of the two is wrong."
+- **Any neighbor could say it** ("we're the simplest way to do X") -> "Could the nearest competing product truthfully make the same claim? If yes, it isn't positioning. What's the claim only you can make?"
+
+**Capture:** One or two sentences. Ideally ends with or implies "...so that [outcome tied to the problem]".
+
+---
+
+## 3. Users
+
+**Opening question:** "Who is the primary user, and what job are they hiring this product to do?"
+
+Jobs-to-be-done framing - the user isn't a demographic, they're someone in a situation trying to make progress.
+
+Strong answers name one primary persona (additional personas allowed but secondary), identify them by role or situation rather than demographic, and state a concrete job as a verb phrase.
+
+**Anti-patterns and pushback:**
+
+- **Too many primary personas** ("it's for founders, PMs, engineers, and designers") -> "If it's for everyone, it's for no one. Who matters most? The others can still benefit, but one of them drives the product decisions."
+- **Demographic framing** ("25-45 year old professionals") -> "That's a demographic, not a user. What are they trying to do that makes them pick up this product?"
+- **Role without situation** ("PMs") -> "PMs doing what? Running a roadmap review? Writing a spec at midnight? Convincing a skeptical eng lead? The situation is where the product matters."
+- **Generic job** ("they want to be more productive") -> "Productive at what specifically? They're hiring this product to do *what*? The more specific, the better the product decisions downstream."
+
+**Capture:** Persona name plus JTBD sentence. Example: "Solo founders running their own roadmap. They're hiring the product to keep strategy and execution aligned without a PM on staff."
+
+---
+
+## 4. Key Metrics
+
+**Opening question:** "What 3-5 metrics will tell you whether the approach is working?"
+
+Metrics are the feedback loop. Bad metrics create the illusion of progress while the product gets worse.
+
+Strong answers stay at 3-5 (not 10), mix leading and lagging (something that moves weekly and something that moves quarterly), and could plausibly regress if the product got worse.
+
+**Anti-patterns and pushback:**
+
+- **Vanity metrics** ("total signups, total pageviews, cumulative users") -> "Those can all go up while the product gets worse. What moves when users actually get value?"
+- **Too many** ("here are 12 metrics we watch") -> "A dashboard isn't a strategy. Pick the 3-5 you'd stake the quarter on. What are the others telling you that those don't?"
+- **Outputs, not outcomes** ("ship velocity, deploys per week") -> "Those measure the team, not the product. If the team doubled velocity but users didn't care, would you call it a win?"
+- **Can only go up** ("cumulative hours saved") -> "A metric that can only go up doesn't tell you much. What's the rate, the ratio, or the thing that can regress?"
+- **Unmeasurable** ("user delight") -> "How specifically? If you can't define how you'd check it on a Tuesday, it's aspirational, not a metric."
+
+**Capture:** A list of 3-5. Each with a one-line definition. Note where each is measured (analytics, DB, qualitative, etc.) if known. If measurement is undefined, ask: "Where does this metric live today? If nowhere, is this something you can start measuring?"
+
+---
+
+## 5. Tracks
+
+**Opening question:** "What are the 2-4 tracks of work you're investing in to execute the approach?"
+
+Tracks are the coherent-actions half of the strategy kernel - concrete areas of investment that flow from the approach. They are not feature lists and not personal todo items. Each track is a named *domain of work*.
+
+Strong answers stay at 2-4 (not 8, not 1), connect clearly back to the approach, and are broad enough that multiple features live inside each one.
+
+**Anti-patterns and pushback:**
+
+- **Feature list in disguise** ("track 1: Slack integration; track 2: mobile app; track 3: dark mode") -> "Those are features. What's the *investment area* each one lives inside? 'Integrations' might be one track, with Slack, Teams, and Discord as candidates inside it."
+- **Too many tracks** ("we have 7 tracks this quarter") -> "With 7 tracks, every track is starved for attention. Which 3 are essential? The others either fold in or drop."
+- **Doesn't connect to approach** (approach: "win by being the easiest to onboard"; track: "enterprise SSO") -> "How does that track serve the approach? If it's a separate bet, name it as one. If onboarding depends on it, explain the link."
+- **Too vague** ("improve the product") -> "Every track is 'improve the product.' What's the specific investment area that's different from the others?"
+- **One track only** -> "With one track, there's no real choice being made. What are the 2-3 things the product needs to be good at, and how are they different?"
+
+Recent commits or PRs show where attention has gone lately, so this is the one section where they help. Offer what they show as a question ("most recent work is in X - is that a track, a temporary push, or unrelated?"), and take the user's answer: a burst of work in one area does not make it a track.
+
+**Capture:** 2-4 tracks. For each: a name, a one-line purpose, and a short note on why this serves the approach.
+
+---
+
+## Stress Test
+
+Run this once sections 1-5 are captured, before Boundaries and the optional sections and before drafting. A strategy is only useful if it decides things, so test whether the assembled answers do.
+
+Pose 3-5 concrete proposals, one at a time, aimed at the draft's fault lines: a tempting feature that sits just off the approach, a second persona pulling in a different direction, a track that would starve another, a metric that would look good while the approach failed. Pick proposals whose answer the user could reasonably give either way, so the test carries information; the draft may already imply a position on it - that implied position is what the user's answer confirms or overturns. Skip proposals that are obviously on- or off-strategy for anyone ("add payroll" to a product whose README already excludes it), since the user's answer is a foregone conclusion and tests nothing. Where the repo model shows a tempting direction (a request in the issues, a recent burst of work outside the tracks), use it.
+
+For each answer:
+
+- The strategy already decides it the same way -> confirmed; move on.
+- The strategy cannot decide it, or decides it differently from the user -> the approach or a track is too vague; ask the sharpening question and update the captured answer.
+- The user resists the proposal -> candidate for Boundaries.
+
+One round per proposal. Do not add sections or metrics to the doc to absorb a proposal; either the doc already handles it, an existing section gets sharper, or it becomes a Boundaries line.
+
+---
+
+## 6. Boundaries
+
+**Opening question:** "Is there anything you've explicitly decided *not* to do right now that's worth naming? This is for things the team keeps being tempted by."
+
+Clarity tool, not a blocker list. Proposals the user resisted in the stress test are the natural candidates - offer them; do not invent others. If the user names items, one sentence each. Do not encourage a long list. The section is always written: when nothing came up, it says so in one line, so readers have a reliable place to look for boundaries.
+
+From the resisted proposals, also draft one line completing "Resist a change when ..." - the test a future reader (human or agent) can apply to a concrete proposal. Show it to the user with the list; drop it if nothing was resisted.
+
+---
+
+## 7. Milestones (optional)
+
+**Opening question:** "Are there any dated milestones worth anchoring - a launch, a fundraise, a conference, a renewal? Skip if none apply."
+
+Only capture externally visible, real milestones. Avoid turning this into an internal schedule.
+
+Default is to skip. Do not push the user to invent milestones. If they name some, capture them verbatim with dates.
+
+---
+
+## 8. Brand (optional)
+
+**Opening question:** "Any positioning or narrative language you want the doc to carry - a one-liner, a tagline, a key message? Skip if not yet."
+
+Skip by default. Keep to 2-3 lines if present.
+
+---
+
+## After the Interview
+
+Once sections 1-5 are captured, the stress test has run, Boundaries (section 6) is captured - it is always written, even if only to say nothing is named yet - and any optional sections the user engaged with are captured, read `strategy-template.md` and fill it in. Present the full draft in chat before writing. Offer one edit round. Then write to `STRATEGY.md`.
+
+## Asking the questions
+
+Default to the host's blocking question tool already in the current tool list (match by capability, not by a host-specific name). Presence in the current tool list is proof the tool exists; never call a user-facing question tool to discover whether it exists. If a matching tool is listed but unloaded, use the host's tool-discovery primitive to load that capability — do not search for another host's tool name. Fall back to numbered options on the host's user-visible chat surface only when no such tool is in the list or a real question call errors. Never silently skip the question.
+
+Ask one question at a time. Prefer free-form answers for the substantive sections and single-select only for routing (which section to revisit); each option label must be self-contained.
+
+For each section, ask the opening question, apply the pushback rules above, and capture the final answer in the user's own language. Where the repo model bears on the section, open with what it suggests and ask the user to confirm or correct, and use repo specifics in pushback ("the README says X; you just said Y - which is it?"). Do not skip pushback - it is the core of the skill, and existing weak content is not rubber-stamped because it is already written. Two rounds per section maximum; capture what the user has given after that and note the section as worth revisiting next run.
+
+The **stress test** (step 6) checks that the captured answers actually decide things: a few concrete proposals aimed at the draft's fault lines, each answered by the user. An answer the strategy already decides confirms it; one it cannot decide sharpens the approach or tracks; a proposal the user resists is a candidate for Boundaries.
+
+## Why these questions
+
+The "Purpose / Positioning / Tracks" structure is informed by Richard Rumelt's *Good Strategy Bad Strategy* - specifically his kernel of diagnosis, guiding policy, and coherent action. The questions above are designed to push past the patterns he calls "bad strategy": fluff, goals dressed up as strategy, and feature lists in place of a guiding choice. The book is the recommended follow-up reading if the distinction between a slogan and a strategy is not yet sharp.

package/skills/ce-strategy/references/strategy-template.md

@@ -0,0 +1,94 @@
+# Strategy Template
+
+Loaded by `SKILL.md` after the interview is complete. Fill it in using the captured answers and write to `STRATEGY.md`.
+
+## Rules for filling in
+
+- Use the user's own language where possible. Do not paraphrase into generic PM-speak.
+- Each section this skill writes stays compact - together they should read in under 5 minutes. Sections other writers contribute are theirs; do not shorten them to hit that bound.
+- Write the sections below in this order. Sections you did not write — added by the user or another skill — are preserved as found and stay where they are; do not add sections of your own beyond this template.
+- Optional sections (Milestones, Brand): delete entirely if unused. Do not leave empty headers. Boundaries is always present.
+- Set `last_updated` in the YAML frontmatter to today's ISO date (YYYY-MM-DD). Do not duplicate the date in prose.
+- Set `name` in the frontmatter to the product or initiative name (the same value used in the H1 title).
+
+## Template
+
+The block below is the literal file to write (minus this line and the fences). Replace every `{{placeholder}}` with the captured answer. Delete any optional section whose placeholder wasn't answered.
+
+~~~markdown
+---
+name: {{product_name}}
+last_updated: {{YYYY-MM-DD}}
+---
+
+# {{product_name}} Strategy
+
+{{If a legacy sibling doc from another tool still exists at the repo root - VISION.md, PRODUCT.md - and the user chose to link to it rather than fold it in (a folded sibling is redundant: no pointer, nothing deferred to it), one line here pointing to it, e.g. "See VISION.md for the project's principles; this document carries direction." Then do not restate what that doc already says: where a section below would repeat it, keep this doc's section to what is specific to strategy and defer to the sibling for the rest. Omit the line when no sibling exists. Sections other tools have already written into this file stay where they are; this skill's sections are placed around them in the order below without moving them.}}
+
+## Purpose
+
+{{1-2 sentence diagnosis. Names the user situation and the crux that makes it hard, and so why the product exists. No solution language.}}
+
+## Positioning
+
+{{1-2 sentence guiding policy. The choice this product commits to that a neighboring product could not truthfully claim, so that the purpose becomes tractable.}}
+
+## Users
+
+**Primary:** {{Persona name}} - {{one-sentence JTBD, e.g. "They're hiring {{product_name}} to..."}}
+
+<!-- Duplicate the block above for additional personas only if truly necessary. Fewer is better. -->
+
+## Boundaries
+
+- {{one line per item the team is tempted by and has decided against; "Nothing named yet." if none}}
+
+_Resist a change when:_ {{one line, from the proposals the user resisted in the stress test; omit the line if none}}
+
+<!-- Always present. Things the team keeps being tempted by, plus the resist test. Not a blocker list. -->
+
+## Key metrics
+
+- **{{metric 1 name}}** - {{one-line definition; where it's measured}}
+- **{{metric 2 name}}** - {{...}}
+- **{{metric 3 name}}** - {{...}}
+
+<!-- 3-5 total. Stop at 5. -->
+
+## Tracks
+
+### {{Track 1 name}}
+
+{{One line: what this track is - the investment area, not a feature list.}}
+
+_Why it serves the approach:_ {{one line}}
+
+<!-- Duplicate the block above for 2-4 tracks total. If you can't keep it to 4, something is wrong - fold related tracks together. -->
+
+## Milestones
+
+- **{{YYYY-MM-DD}}** - {{milestone}}
+
+<!-- Optional. Delete the section if unused. Only externally visible milestones: launches, fundraises, conferences, renewals. -->
+
+## Brand
+
+**One-liner:** {{single-sentence pitch}}
+
+**Key message:** {{2-3 lines if useful}}
+
+<!-- Optional. Delete the section if unused. -->
+~~~
+
+## Post-write checklist
+
+Before confirming the write, scan the draft for:
+
+- [ ] Frontmatter present at the top with `name` and `last_updated` keys.
+- [ ] `last_updated` carries today's date in ISO format (YYYY-MM-DD).
+- [ ] No section this skill wrote has more than 4 sentences except Tracks (where each track has its own short block); sections other writers contribute are not measured.
+- [ ] No placeholders remain (`{{...}}`).
+- [ ] Optional sections (Milestones, Brand) with no content have been deleted, not left empty; Boundaries is present.
+- [ ] Sections this skill did not write are unchanged and still in place.
+- [ ] Metric count is between 3 and 5 and track count between 2 and 4 - counting a meaning explicitly deferred to a linked legacy doc as carried there, not as missing here.
+- [ ] Purpose and Positioning are connected - one clearly responds to the other.