From 111c9fd8bd66c0b4299974a32ccdd13226e5d0ce Mon Sep 17 00:00:00 2001 From: imwm Date: Fri, 17 Apr 2026 20:48:40 -0700 Subject: [PATCH 1/5] add strategy skill for docs/strategy.md --- .../skills/ce-strategy/SKILL.md | 97 ++++++++++++ .../ce-strategy/references/interview.md | 143 ++++++++++++++++++ .../references/strategy-template.md | 84 ++++++++++ 3 files changed, 324 insertions(+) create mode 100644 plugins/compound-engineering/skills/ce-strategy/SKILL.md create mode 100644 plugins/compound-engineering/skills/ce-strategy/references/interview.md create mode 100644 plugins/compound-engineering/skills/ce-strategy/references/strategy-template.md diff --git a/plugins/compound-engineering/skills/ce-strategy/SKILL.md b/plugins/compound-engineering/skills/ce-strategy/SKILL.md new file mode 100644 index 000000000..2003ff781 --- /dev/null +++ b/plugins/compound-engineering/skills/ce-strategy/SKILL.md @@ -0,0 +1,97 @@ +--- +name: ce:strategy +description: "Create or maintain docs/strategy.md - the product's target problem, approach, users, key metrics, and tracks of work. Use when starting a new product, updating direction, or when prompts like 'write our strategy', 'update the roadmap', 'what are we working on', or 'set up the strategy doc' come up. Also triggers when ce:ideate, ce:brainstorm, or ce:plan need upstream grounding and no strategy doc exists yet." +argument-hint: "[optional: section to revisit, e.g. 'metrics' or 'approach']" +--- + +# Product Strategy + +**Note: The current year is 2026.** Use this when dating the strategy document. + +`ce:strategy` produces and maintains `docs/strategy.md` - a short, durable anchor document that captures what the product is, who it serves, how it succeeds, and where the team is investing. Downstream skills (`ce:ideate`, `ce:brainstorm`, `ce:plan`) read it as grounding when it exists. + +The document is short and structured on purpose. Good answers to a handful of sharp questions produce a better strategy than any amount of prose. This skill asks those questions, pushes back on weak answers, and writes the doc. + +## Interaction Method + +Use the platform's blocking question tool when available (`AskUserQuestion` in Claude Code, `request_user_input` in Codex, `ask_user` in Gemini). Otherwise, present numbered options in chat and wait for the user's reply before proceeding. + +Ask one question at a time. Prefer free-form responses for the substantive sections (problem, approach, persona); reserve single-select for routing decisions (which section to revisit). Each option label must be self-contained. + +## Focus Hint + + #$ARGUMENTS + +Interpret any argument as an optional focus: a section name to revisit (`metrics`, `approach`, `tracks`) or a scope hint. With no argument, proceed open-ended and let the file state decide the path. + +## Core Principles + +1. **Anchor, not plan.** Strategy is what the product is and why. Features belong in `ce:brainstorm`; schedules belong in the issue tracker. Do not let either creep into the doc. +2. **Rigor in the questions, not the headings.** The section headers are plain English. The interview questions enforce strategy discipline. +3. **Short is a feature.** The template is constrained. Adding sections costs more than it looks like. Push back on expansion. +4. **Durable across runs.** This skill is rerunnable. On a second run it updates in place, preserves what is working, and only challenges sections that look stale or weak. + +## Execution Flow + +### Phase 0: Route by File State + +Read `docs/strategy.md` using the native file-read tool. + +- **File does not exist** -> First run. Go to Phase 1. +- **File exists and argument names a specific section** -> Targeted update. Go to Phase 2. +- **File exists, no argument** -> Ask which section(s) to revisit, then Phase 2. + +Announce the path in one line: "Strategy doc not found - let's write it." or "Found existing strategy - let's review and update." + +### Phase 1: First-Run Interview + +Read `references/interview.md`. This load is non-optional - the pushback rules, anti-pattern examples, and quality bar for each section live there. Improvising from memory produces a passive transcription instead of a strategy doc. + +Run the interview in the section order of the final document: + +1. Target problem +2. Our approach +3. Who it's for +4. Key metrics +5. Tracks +6. Milestones (optional) +7. Not working on (optional) +8. Marketing (optional) + +For each section, ask the opening question, apply the pushback rules, and capture the final answer in the user's own language. Do not skip the pushback step - it is the core of the skill. Two rounds of pushback per section maximum; capture what the user has given after that and note the section is worth revisiting on the next run. + +When all required sections (1-5) are captured, read `references/strategy-template.md`, fill it in, and present the full draft in chat before writing. Offer one round of edits. Then write to `docs/strategy.md`. + +### Phase 2: Update Run + +Read the existing `docs/strategy.md` thoroughly. Summarize current state in 3-5 lines so the user sees what is on file. + +If the argument named a specific section, jump to that section in `references/interview.md`. Preserve all other sections exactly. Apply pushback as if this were a first run - do not rubber-stamp existing weak content just because it is already written. + +If no specific target, ask the user which section to revisit using the blocking question tool. Options: + +- "Target problem" +- "Our approach" +- "Who it's for" +- "Metrics, tracks, or other" + +For each revisited section, re-interview with full pushback. For sections the user confirms are still accurate, leave them untouched. Update the `Last updated` date. + +Write the updated doc back to `docs/strategy.md`. + +### Phase 3: Downstream Handoff + +After writing, note in one line where the file lives and that `ce:ideate`, `ce:brainstorm`, and `ce:plan` will pick it up as grounding on their next run. + +If no downstream skill has run yet on this repo, suggest `/ce:ideate` or `/ce:brainstorm` as a next step. + +## What This Skill Does Not Do + +- Does not update the issue tracker or reconcile in-flight work. Strategy is the doc; execution lives elsewhere. +- Does not prioritize the backlog. Prioritization is a separate workflow. +- Does not write product requirements or implementation plans - those are `ce:brainstorm` and `ce:plan`. +- Does not compute metric values. It records which metrics matter and where they live, not what they read today. + +## Learn More + +The "Target problem / Our approach / Tracks" structure is informed by Richard Rumelt's *Good Strategy Bad Strategy* - specifically his kernel of diagnosis, guiding policy, and coherent action. The interview questions in `references/interview.md` 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. diff --git a/plugins/compound-engineering/skills/ce-strategy/references/interview.md b/plugins/compound-engineering/skills/ce-strategy/references/interview.md new file mode 100644 index 000000000..b6b38da7d --- /dev/null +++ b/plugins/compound-engineering/skills/ce-strategy/references/interview.md @@ -0,0 +1,143 @@ +# 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. + +--- + +## 1. Target Problem + +**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. No solution language. + +--- + +## 2. Our Approach + +**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." + +**Capture:** One or two sentences. Ideally ends with or implies "...so that [outcome tied to the problem]". + +--- + +## 3. Who It's For + +**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 load-bearing? 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 it's load-bearing for onboarding, 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?" + +**Capture:** 2-4 tracks. For each: a name, a one-line purpose, and a short note on why this serves the approach. + +--- + +## 6. 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. + +--- + +## 7. Not Working On (optional) + +**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. Skip by default. If the user names items, one sentence each. Do not encourage a long list. + +--- + +## 8. Marketing (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 (and any optional sections the user engaged with), read `strategy-template.md` and fill it in. Present the full draft in chat before writing. Offer one edit round. Then write to `docs/strategy.md`. diff --git a/plugins/compound-engineering/skills/ce-strategy/references/strategy-template.md b/plugins/compound-engineering/skills/ce-strategy/references/strategy-template.md new file mode 100644 index 000000000..f45afc8cf --- /dev/null +++ b/plugins/compound-engineering/skills/ce-strategy/references/strategy-template.md @@ -0,0 +1,84 @@ +# Strategy Template + +Loaded by `SKILL.md` after the interview is complete. Fill it in using the captured answers and write to `docs/strategy.md`. + +## Rules for filling in + +- Use the user's own language where possible. Do not paraphrase into generic PM-speak. +- Each section stays compact. The whole doc should read in under 5 minutes. +- Section order is locked. Do not add new top-level sections. +- Optional sections: delete entirely if unused. Do not leave empty headers. +- Write the `_Last updated_` line with today's ISO date (YYYY-MM-DD). + +## 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 +# {{product_name}} Strategy + +_Last updated: {{YYYY-MM-DD}}. Re-run `/ce:strategy` to update._ + +## Target problem + +{{1-2 sentence diagnosis. Names the user situation and the crux that makes it hard. No solution language.}} + +## Our approach + +{{1-2 sentence guiding policy. What this product commits to, so that the target problem becomes tractable.}} + +## Who it's for + +**Primary:** {{Persona name}} - {{one-sentence JTBD, e.g. "They're hiring {{product_name}} to..."}} + + + +## Key metrics + +- **{{metric 1 name}}** - {{one-line definition; where it's measured}} +- **{{metric 2 name}}** - {{...}} +- **{{metric 3 name}}** - {{...}} + + + +## Tracks + +### {{Track 1 name}} + +{{One line: what this track is - the investment area, not a feature list.}} + +_Why it serves the approach:_ {{one line}} + + + +## Milestones + +- **{{YYYY-MM-DD}}** - {{milestone}} + + + +## Not working on + +- {{one line per item}} + + + +## Marketing + +**One-liner:** {{single-sentence pitch}} + +**Key message:** {{2-3 lines if useful}} + + +~~~ + +## Post-write checklist + +Before confirming the write, scan the draft for: + +- [ ] No section has more than 4 sentences except Tracks (where each track has its own short block). +- [ ] No placeholders remain (`{{...}}`). +- [ ] Optional sections with no content have been deleted, not left empty. +- [ ] Metric count is between 3 and 5. Track count is between 2 and 4. +- [ ] Target problem and Our approach are connected - one clearly responds to the other. +- [ ] `_Last updated_` line carries today's date in ISO format. From 48d5c40f47da051e89f82feff99daa2cf2ab64b2 Mon Sep 17 00:00:00 2001 From: imwm Date: Fri, 17 Apr 2026 20:49:04 -0700 Subject: [PATCH 2/5] add pulse skill for usage reports --- .../skills/ce-product-pulse/SKILL.md | 150 +++++++++ .../ce-product-pulse/references/interview.md | 290 ++++++++++++++++++ .../references/report-template.md | 86 ++++++ 3 files changed, 526 insertions(+) create mode 100644 plugins/compound-engineering/skills/ce-product-pulse/SKILL.md create mode 100644 plugins/compound-engineering/skills/ce-product-pulse/references/interview.md create mode 100644 plugins/compound-engineering/skills/ce-product-pulse/references/report-template.md diff --git a/plugins/compound-engineering/skills/ce-product-pulse/SKILL.md b/plugins/compound-engineering/skills/ce-product-pulse/SKILL.md new file mode 100644 index 000000000..95caeb3cc --- /dev/null +++ b/plugins/compound-engineering/skills/ce-product-pulse/SKILL.md @@ -0,0 +1,150 @@ +--- +name: ce:product-pulse +description: "Generate a time-windowed pulse report on what users experienced and how the product performed - usage, quality, errors, signals worth investigating. Use when the user says 'run a pulse', 'show me the pulse', 'how are we doing', 'weekly recap', 'launch-day check', or passes a time window like '24h' or '7d'. Produces a single-page report saved to ~/pulse-reports/ and summarized in chat." +argument-hint: "[lookback window, e.g. '24h', '7d', '1h'; default 24h]" +--- + +# Product Pulse + +`ce:product-pulse` queries the product's data sources for a given time window and produces a compact, single-page report covering usage, performance, errors, and followups. The report is saved to `~/pulse-reports/` and the key points are surfaced in chat. + +This is a read-only skill. It reports on what happened; it does not fix anything, ship anything, or change the product. + +## Interaction Method + +Use the platform's blocking question tool when available (`AskUserQuestion` in Claude Code, `request_user_input` in Codex, `ask_user` in Gemini). Otherwise, present numbered options in chat and wait for the user's reply before proceeding. + +Ask one question at a time. Reserve multi-select for first-run configuration only. + +## Lookback Window + + #$ARGUMENTS + +Interpret the argument as a time window. Common forms: + +- `24h`, `48h`, `72h` - trailing hours +- `7d`, `30d` - trailing days +- `1h` - short-window (useful during launches) + +If the argument is empty, default to `24h`. If it is unparseable, ask the user to clarify. + +Apply a **15-minute trailing buffer** to the window's upper bound. Many analytics and tracing tools have ingestion lag; querying right up to `now` under-reports the most recent events. For a `24h` window, query `[now - 24h - 15m, now - 15m]`. + +## Core Principles + +1. **Read it like a founder.** No hardcoded thresholds. Do not label things "bad" or "good" by default - present the numbers and let the reader judge. +2. **Single page.** Target 30-40 lines of terminal output. If the report is getting long, cut. +3. **No PII in saved reports.** Do not include user emails, account IDs, or message content in the report written to disk. +4. **Parallel where safe, serial where it matters.** Analytics and tracing queries run in parallel. Database queries run serially to avoid load. +5. **Memory through saved reports.** Every run writes to `~/pulse-reports/` so past pulses are browseable as a timeline. +6. **Read-only database access only.** If a database is used as a data source, the connection must be read-only. The interview refuses to accept read-write credentials. Database access is optional - many products complete the pulse with analytics and tracing alone. +7. **Strategy-seeded when available.** If `docs/strategy.md` exists, the interview reads it before asking questions and carries forward the product name and key metrics as seeds. The goal of data-source setup is to wire up whatever connections are needed to actually measure those metrics. + +## Execution Flow + +### Phase 0: Route by Config State + +Read `docs/product-pulse.md` using the native file-read tool. + +- **File does not exist** -> First run. Go to Phase 1 (interview), then Phase 2. +- **File exists** -> Skip to Phase 2. + +If the argument was `setup`, `reconfigure`, or `edit config`, go to Phase 1 regardless of file state. + +### Phase 1: First-Run Interview + +#### 1.0 Seed from strategy (if available) + +Before asking any questions, read `docs/strategy.md` using the native file-read tool. If the file exists, extract: + +- The product name (from the title) +- The list of key metrics (from the `## Key metrics` section) + +Open the interview by showing the user what was pulled forward: "I see you have a strategy doc on file - I'll seed the product name as `{{name}}` and carry these key metrics into the event/data setup: {{metric list}}. Say so if any of that needs to change." + +If `docs/strategy.md` does not exist, note that too: "No strategy doc on file. Running the full setup from scratch. (If you want strategy to seed this later, run `/ce:strategy` first.)" + +#### 1.1 Interview + +Read `references/interview.md`. This load is non-optional - the pushback rules, anti-pattern examples, and metric-to-source mapping logic live there. + +Run the interview in this order: + +1. Product name (confirm or edit the seeded value) +2. Primary engagement event +3. Value-realization event +4. Completions or conversions (0-3) +5. Quality scoring (opt-in, AI products only) +6. Data sources - wire up connections for each agreed metric and event. Nudge toward MCP. Reject read-write database access. DB entirely optional. +7. System performance - a short recommended setup for top errors and latency. Users rarely have strong opinions here; present defaults and accept. +8. Default lookback window + +Apply the pushback rules in `references/interview.md` for each section. Treat every metric, event, and signal the user proposes against the **SMART bar** (specific, measurable, actionable, relevant, timely) spelled out in `references/interview.md` under "Overall Rules" - push back on anything vague, vanity, or unactionable. + +If the user offers read-write database access, refuse and offer the alternatives documented in `references/interview.md` section 6. + +Write the captured config to `docs/product-pulse.md` using the structure defined in `references/interview.md` under "Config file shape". Show the file to the user and offer one round of edits. + +After the config is written, run the **scheduling recommendation** from `references/interview.md` section 9: offer to set up a recurring run (via `schedule` skill or a cron-like routine) so the user gets the pulse on a cadence instead of having to remember to run it. Accept yes/no/later. If yes, hand off to the `schedule` skill; do not schedule inline. Then proceed to Phase 2. + +### Phase 2: Run the Pulse + +Read `docs/product-pulse.md`. + +#### 2.1 Dispatch Queries + +Run these in **parallel** (different tools, no shared load): + +- Product analytics query (primary event count, value-realization count, completions, conversion ratios) over the window +- Application tracing query (error counts by category, latency distribution, top error signatures) over the window +- Payments query, if configured (new customers, churn, revenue delta) over the window + +Run these **serially**, after the parallel batch: + +- Read-only database queries. One at a time. Tight, scoped queries only. Never full-table scans on large tables. If a DB query would be expensive, skip it and note "DB query skipped (estimated cost too high)". + +#### 2.2 Optional: Sample Quality Scoring + +If quality scoring is opted in (AI products only, see interview config), sample up to 10 sessions or conversations from the window and score each 1-5 on the dimension the user specified at setup. + +**Scoring discipline:** Default to 4 or 5 when the session looks normal. Reserve 1-3 for sessions with a clear failure mode (product gave wrong answer, user got stuck, error surfaced). If every session is scoring 3, the bar is too strict; if every session is scoring 5, the bar is too loose. + +**No PII in the score summary.** Capture a count distribution (e.g., "8x 5, 1x 4, 1x 2") and a short anonymized note on any session scored below 4. Do not include message content or user identifiers in the saved report. + +#### 2.3 Assemble the Report + +Read `references/report-template.md`. Fill in the template using the query results. Four sections, in order: + +1. **Headlines** - 2-3 lines summarizing the window +2. **Usage** - primary engagement, value realization, completions, quality sample +3. **System performance** - latency (p50/p95/p99) and top 5 errors by count with one-line explanation each +4. **Followups** - 1-5 things worth investigating + +Keep the total to 30-40 lines. If a section is thin, leave it thin; do not pad. + +#### 2.4 Write the Report + +Save to `~/pulse-reports/YYYY-MM-DD_HH-MM.md` using the local time of the run. Create `~/pulse-reports/` if it does not exist. + +Surface the Headlines and top Followup in chat. Provide the full file path so the user can open the saved report. + +### Phase 3: Routine Hook + +First-run setup already offered scheduling (see Phase 1.1 end). Phase 3 is a lighter re-surface for ad-hoc runs: + +- If the argument was a known schedule keyword (`daily`, `hourly`, `weekly`), note that this run is ad-hoc and suggest the `schedule` skill for recurring runs. +- If no schedule is on file (check `schedule`-skill output or the user's routine config if available) and this is the third or later pulse run the user has done, mention once that scheduling is available. Don't nag on every run. + +Never schedule automatically. Handing off to the `schedule` skill requires explicit confirmation. + +## What This Skill Does Not Do + +- Does not report "what shipped." Shipped work lives in the issue tracker and commit history, not here. Pulse is strictly about user experience and system performance. +- Does not set thresholds or alert the user. The reader interprets. +- Does not persist PII in saved reports. +- Does not mutate the database or any external system. All queries are read-only. +- Does not replace tracing dashboards or analytics tools. It consolidates a single-page read; deep investigation still uses the native tools. + +## Learn More + +The "read like a founder" posture and the single-page constraint are deliberate. Dashboards with 40 metrics produce attention sprawl; one page with the right four sections forces the reader to notice what matters. The saved-reports folder is designed to be a team's working memory, not a data warehouse - past pulses are grepable, diffable, and disposable. diff --git a/plugins/compound-engineering/skills/ce-product-pulse/references/interview.md b/plugins/compound-engineering/skills/ce-product-pulse/references/interview.md new file mode 100644 index 000000000..adfbe3599 --- /dev/null +++ b/plugins/compound-engineering/skills/ce-product-pulse/references/interview.md @@ -0,0 +1,290 @@ +# Product Pulse First-Run Interview + +Loaded by `SKILL.md` at the start of Phase 1. Captures the configuration that will be written to `docs/product-pulse.md` and re-read on every subsequent run. + +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. **Push back, but don't spiral.** One round of pushback per section max. If the second answer still isn't usable, capture what the user gave, flag it in the config as `needs-review`, and move on. +2. **Name events in the user's own words.** The config will be readable by the whole team - use the terms they actually use, not a generic template. +3. **Ask about tools, not credentials.** The interview captures *which* tool and *what shape of query*. It does not collect API keys, tokens, or database passwords. Those stay in the user's environment. +4. **Honor strategy seeds.** If `SKILL.md` Phase 1.0 surfaced a product name or a list of key metrics from `docs/strategy.md`, start with those as defaults and let the user edit. Do not re-ask questions that the strategy doc already answered unambiguously. +5. **Evaluate metrics against the SMART bar.** Every event, metric, and signal the user proposes should be: + - **Specific** - a named event or a named metric, not a category. `message_sent` passes; "engagement" does not. + - **Measurable** - you can point to the tool and query that returns a number. "Users like it" does not pass; "NPS score from Delighted" does. + - **Actionable** - if the number moves, the team knows what to do next. "Daily active users" alone usually fails this - pair it with a conversion or retention signal that surfaces a decision. + - **Relevant** - ties to the product's target problem and persona (from the strategy doc if seeded). Generic funnel metrics that don't connect to the strategy are suspect. + - **Timely** - reads in the pulse window (24h, 7d, etc.) and reflects the current state. Lagging metrics that only move quarterly don't belong in a daily pulse. + + When a user proposes a metric that fails one of these, push back by naming the specific dimension: "That sounds more like a vanity metric than an actionable one - if it moves, what do we do? Is there a tighter signal that would drive a decision?" Do not use the word "SMART" with the user; use the plain-English question. + +--- + +## 1. Product Name + +**Opening question:** + +- If seeded from strategy: "Product name from strategy is `{{name}}`. Keep it or edit?" +- Otherwise: "What's the product called?" + +No pushback needed. Capture verbatim. + +--- + +## 2. Primary Engagement Event + +**Opening question:** "When someone is using your product, what single event fires? The one that tells you a user is active right now." + +This is the heartbeat of the pulse. Pick one event - the one that represents a user actually using the product, not opening a page. + +**Apply the SMART bar** (see Overall Rules). The event must be specific (a named event), measurable (the analytics tool returns a count), actionable (if it moves, the team notices), relevant (ties to the product's job), and timely (reads cleanly in short windows). + +**Engagement vs value test.** After the user names an event, ask yourself: does this event fire when the user is *using* the product, or when the user has *gotten value* from it? Engagement is earlier (they're in it). Value is later (it worked). If the candidate is really value-realization, push back: "That sounds like the moment the product *worked* for them. What event happens earlier - when they're in the middle of using it? The value event belongs in section 3." Common slips: `agent_accepted_draft` (value) vs `agent_received_draft` (engagement); `ride_completed` (value) vs `ride_started` (engagement); `question_answered_correctly` (value) vs `question_asked` (engagement). + +**Anti-patterns and pushback:** + +- **Page view or visit** ("pageview", "app opened", "login") -> "Those tell you someone showed up. I'm looking for the event that says they actually *used* the product. What fires when a user is doing the thing the product is for?" +- **Multiple events with no clear primary** ("well, it could be X or Y or Z depending on the flow") -> "For the pulse, pick the one that's closest to 'a user is active using the core product.' If two candidates are genuinely tied, pick the one that happens *when the user spends time in exchange for value* - for async products that's usually 'contributed content' over 'opened app'." +- **Too deep in the funnel** ("purchase_completed") -> "That's a conversion event - we'll capture that separately. For the primary engagement event, what happens earlier - when they're using the product, not when they've already converted?" +- **Vague** ("interaction", "activity") -> "Is there a specific event name in your analytics tool? I want to write down the literal event name so this is repeatable." + +**Capture:** Event name verbatim (e.g., `message_sent`, `document_edited`, `ride_started`). Plus a one-line description of what it means. + +--- + +## 3. Value-Realization Event + +**Opening question:** "What event fires when a user actually gets value - when the product delivered what they came for?" + +Different from engagement. Engagement says "they're using it"; value-realization says "they got what they wanted." Some products have a clear distinction (engagement: `typed_in_box`; value: `got_useful_answer`); for others it's the same event (engagement: `ride_requested`; value: `ride_completed`). + +**Apply the SMART bar.** The bar here is the same - specific, measurable, actionable, relevant, timely - and the proxy test is especially important because value-realization is often felt, not fired. + +**Anti-patterns and pushback:** + +- **Same as engagement event, accidentally** -> "Is that the same as the engagement event you gave me? If so, that's fine - some products have one event that covers both. Want to confirm, or is there a later signal that says 'this user got the thing they came for'?" +- **Revenue event** ("purchase") -> "Purchase is a conversion event - we'll capture that separately. For value-realization, I'm looking for the moment a user knows the product worked for them, which is usually before or separate from payment." +- **Value is a feeling, not an event** ("they feel like the team aligned", "they trust the output") -> "That's real, but we can't measure a feeling directly in the pulse. What's a proxy event that correlates? Common patterns: a completion event (workflow finished), a time-to-first-X metric (seconds from open to output), a short-window return rate (came back the next day), or a copy/share/export event (took the output into their actual work). Pick the one closest to the feeling." +- **Can't name one** -> "That's useful to know. If there's no discrete event, is there a session or workflow *completion* that stands in? Something like 'they finished the task they opened the product to do.' If not, we'll treat engagement as the value proxy and note it in the config." + +**Capture:** Event name verbatim, or `same-as-engagement` with a note, or `not-defined` with a note. + +--- + +## 4. Completion or Conversion Events + +**Opening question:** "Any conversion or completion events worth tracking - signups, upgrades, trial starts, purchases?" + +Optional section. 0-3 events is typical. + +**Apply the SMART bar** (see Overall Rules). Each conversion event should tie to a decision: if `trial_started` moves ±20%, what would the team do? If the answer is "nothing", the event is a vanity metric and shouldn't be in the pulse. + +**Anti-patterns and pushback:** + +- **Long list** ("we have 12 of them") -> "Pick the top 3 that move the business. The others can be queried ad-hoc when you want; the pulse keeps the top 3." +- **Non-actionable conversion** ("email_opens", "logo_impressions") -> "If that number swings, what do we do? If the answer is 'nothing,' it's a vanity metric. What's a tighter signal further down the funnel?" + +**Capture:** List of 0-3 event names with one-line descriptions each. + +--- + +## 5. Quality Scoring (optional, AI products) + +**Opening question:** "Is this an AI product where a conversation or session could be rated for quality? If yes, I'll sample up to 10 sessions per run and score each 1-5 on a dimension you define. Say no if this isn't applicable." + +If the user opts in, ask: "What dimension should sessions be scored on? (e.g., 'got to a useful answer', 'response was accurate', 'no hallucinations')." + +**Pushback:** + +- **Vague dimension** ("quality", "goodness", "helpful", "good response") -> "Quality on what axis specifically? The dimension should be something a human could look at a transcript and judge consistently." +- **Multiple dimensions** ("accurate AND actionable") -> "Start with one. You can add dimensions by editing the config later. Keeping it at one keeps the scores comparable across runs. Which matters more right now?" +- **Reviewability test** - after the user names a dimension, apply this check silently: could two separate reviewers look at the same session and agree on the score? If no, push back once: "Let's tighten this - what would make a reviewer score this a 5 vs a 3? If you can name the distinction in one sentence, the dimension is tight enough." If the user can answer, capture it as a scoring note alongside the dimension. If they can't, flag the dimension `needs-review` and move on. + +**Capture:** opt-in (yes/no), dimension (if opted in), scoring note (1 sentence distinguishing 5 from 3), scoring discipline reminder ("default to 4-5; reserve 1-3 for clear failures"). + +--- + +## 6. Data Sources + +**Opening framing:** "Now we wire up the connections needed to actually report on the events and metrics you've named. The goal is the smallest set of sources that covers everything above - one source can be enough. Let's walk through each metric." + +### 6.0 Build the metric-to-source list + +Compile the full list of signals that need a source: + +- The primary engagement event (section 2) +- The value-realization event (section 3), if different from engagement +- Each completion/conversion event (section 4) +- Each key metric carried from the strategy doc, if strategy was seeded + +For each entry, ask one question: "Where does `{{event or metric}}` live? Name the tool (e.g. Mixpanel, PostHog, Amplitude, Stripe, internal DB) and how the agent would query it." + +The answer produces (tool name, query shape). If multiple entries land in the same tool, consolidate them into one source entry. + +**Dual-source arbitration.** If a single signal could be answered from two different sources (e.g., both PostHog and a read-only DB replica have the search events), pick one as canonical and name it in the config. Ask: "Both `{{source A}}` and `{{source B}}` can cover this - which is the source of truth? The pulse queries one per signal so numbers stay consistent across runs." Capture the canonical source. The other tool may still be used for ad-hoc investigation but is not wired into the pulse. + +**If the user says "we don't have that instrumented yet"** (common for strategy-seeded metrics like retention or NPS): offer two off-ramps and let them pick. + +- **Defer** - capture the metric as `instrumentation-pending` with a one-line note. The metric will appear in the config and render as `no data` in each pulse report until instrumentation lands. This is the right call if the metric matters and they'll fix it. +- **Drop from pulse** - capture the metric as `strategy-only - not in pulse`. The metric stays in `docs/strategy.md` but the pulse ignores it. This is the right call if the metric is aspirational and won't have data any time soon. + +Do not silently skip. An unmeasured strategy metric should either show up as a `no data` slot (forcing visibility) or be explicitly dropped. + +### 6.1 MCP nudge + +After each unique source is named, check MCP coverage: + +1. Call `search_mcp_registry` with the tool name to see if an official or community MCP exists. Do not guess from memory. +2. If one exists and the user already has it connected (ask: "Is the `{{tool}}` MCP already connected?"), note `using MCP for {{tool}}` in the config. +3. If one exists but the user hasn't connected it, suggest: "There's an MCP for `{{tool}}`. Connecting it is the fastest way to let the agent query on each run - I can call `suggest_connectors` to walk you through it, or we can skip and I'll note the source as `manual - agent will need credentials or another path`." +4. If no MCP exists, capture `manual` and note what shape of query the agent should use (CLI, API, etc.). + +Do not set up MCP connections inside this interview - that's a separate flow. Just record which tools have MCP coverage and which do not. + +### 6.2 Database access (optional, read-only only) + +Ask explicitly: "Do you have a read-only database connection you'd like the agent to use for any signals that live in the DB? Read-only only - I will refuse a read-write connection." + +**Handling the answer:** + +- **"No" or "skip"** -> capture `database: not used` and move on. DB is entirely optional; many products report the pulse from analytics and tracing alone. +- **"Yes, read-only"** (read replica, read-only user, row-level-security enforced) -> capture connection shape and which tables are available. Ask about cost: "For pulse queries, scans need to be cheap - what indexed columns are available, and are there any tables to avoid?" +- **"Yes, but it's my prod credential"** or any indication the connection has write access -> refuse: "For safety the pulse will not query a database with write access, even read-only in intent. The options are: (a) set up a read-only replica or a read-only user, (b) skip the DB entirely - analytics usually covers the pulse. Which do you want?" Do not proceed until the user picks (a) with verified read-only scope or (b) skip. Do not capture a read-write connection under any framing. + +### 6.3 Consolidated source list + +When every signal has a source (or is marked "covered by analytics above"), summarize the source list back to the user: "Here's what we'll wire up: {{sources}}. Any source missing for a signal you care about?" + +Capture the final list in the config. A minimum of one source is acceptable. + +**Source-count check** - judge by ratio, not absolute count: + +- If the config has 3-4 metrics and every source covers a distinct one, 3-4 sources is the floor and not a warning. Accept without flagging. +- If the config has 1-2 metrics spread across 4+ sources, the setup is over-instrumented - flag for review and ask: "We have {{N}} sources but only {{M}} metrics. Is there a single tool that could cover most of this?" +- Above 5 sources regardless of metric count, flag for review. Lots of sources means lots of auth, latency, and failure modes on every run. + +--- + +## 7. System Performance + +**Opening framing:** "The system performance portion of the pulse is pretty standard - most teams want the same thing: top errors with context, and latency percentiles. Unless you have strong opinions, I'll set up the recommended default." + +**Recommended default (confirm or override):** + +- **Top errors:** top 5 error signatures from the tracing tool, by count, descending. Each entry includes the signature and a one-line explanation of what it likely means. +- **Latency:** p50, p95, p99 over the window, compared to the prior equal-length window. +- **Tracing tool:** {{capture tool name if not already named in section 6}} + +Ask one confirmation question: "Keep the recommended setup, or customize?" + +- **Keep** -> capture defaults. +- **Customize** -> ask what they want to change. Common adjustments: "top 3 instead of 5", "skip latency", "add a specific error signature to always surface". Accept and record. + +If no tracing tool was named in section 6, ask: "What tool do you use for application tracing and errors? (e.g., Datadog, Sentry, Honeycomb, New Relic.) Skip if you don't have one - I'll omit the system performance section from the report." Skipping is fine - the pulse will just report usage and followups in that case. + +**Capture:** tool name (or "none"), top-error count (default 5), latency opt (default on). + +--- + +## 8. Default Lookback Window + +**Opening question:** "What should the default lookback window be when no time window is specified? Common: 24h for daily ops, 7d for weekly review, 1h for launches." + +Capture: single default (e.g., `24h`). + +--- + +## 9. Scheduling Recommendation + +After the config is written and shown to the user, make a scheduling offer before handing back to Phase 2. + +**Opening framing:** "Pulses are most useful on a cadence - a report once a day (or once a week) catches drift you'd miss otherwise. Want me to set up a recurring run?" + +**Ask one question:** + +- "Yes, daily" - at a time they pick +- "Yes, weekly" - day + time they pick +- "Not now - I'll run it manually" +- "Later - remind me after a few manual runs" + +**Handling the answer:** + +- **Yes (daily or weekly)** -> "I'll hand this to the `schedule` skill. Confirm the time/day and it'll set up the recurring job." Do not schedule inline - hand off to the `schedule` skill explicitly, which is the single source of truth for recurring tasks. On Claude Code, this uses the Routines feature. +- **Not now** -> capture `schedule: manual` in the config. No nag. +- **Later** -> capture `schedule: ask-again-after-3-runs` in the config. The SKILL.md Phase 3 logic re-surfaces the offer after 3 manual runs. + +Skipping this entirely is fine - the skill does not require a schedule to function. But recommending one is the right default because the value of pulse compounds through the saved-reports timeline; one-off runs lose most of that value. + +**Capture:** `schedule: daily | weekly | manual | ask-again-after-3-runs` plus time/day if applicable. + +--- + +## Config File Shape + +After the interview completes, write `docs/product-pulse.md` using this structure. Keep it human-readable - a teammate should be able to read and edit it without any special tooling. + +~~~markdown +# {{product_name}} Pulse Config + +_Last updated: {{YYYY-MM-DD}}. Re-run `/ce:product-pulse setup` to edit._ + +## Events + +- **Primary engagement:** `{{event_name}}` - {{description}} +- **Value realization:** `{{event_name}}` - {{description}} _(or `same-as-engagement` or `not-defined`)_ +- **Completions / conversions:** + - `{{event_name}}` - {{description}} + +## Strategy metrics carried forward + +- **{{metric name}}** - sourced from {{tool}} _(or: strategy doc not present)_ + +## Quality scoring + +- **Opted in:** {{yes | no}} +- **Dimension:** {{dimension}} +- **Sample size:** up to 10 sessions per run +- **Scoring discipline:** default to 4-5; reserve 1-3 for clear failures + +## Data sources + + + +- **{{tool name}}** ({{mcp | manual}}) - covers: {{signals this source provides}} +- **{{tool name}}** ({{mcp | manual}}) - covers: {{signals}} + +### Database + +- **Status:** {{not used | read-only replica | read-only user}} +- **Tables available:** {{table list, or omit}} +- **Cost guardrails:** {{indexed columns, tables to avoid, or omit}} + +_Read-write database access is not supported and will be refused by the skill on subsequent runs._ + +## System performance + +- **Tracing tool:** {{tool name, or none}} +- **Top errors:** top {{5 | custom}} by count, descending, with one-line explanation +- **Latency:** {{on | off}} - p50, p95, p99, vs prior window + +## Defaults + +- **Lookback window:** {{24h | 7d | 1h | other}} +- **Trailing buffer:** 15 minutes +- **Report location:** `~/pulse-reports/YYYY-MM-DD_HH-MM.md` + +## Schedule + +- **Cadence:** {{daily @ HH:MM | weekly @ DAY HH:MM | manual | ask-again-after-3-runs}} +- **Managed by:** {{schedule skill | manual runs only}} + +## Query guardrails + +- Analytics and tracing queries run in parallel. +- Database queries run serially and must be indexed; skip expensive scans. +- No PII in saved reports. +- No hardcoded thresholds in the report. Report numbers; let the reader judge. +~~~ + +Show the file to the user. Offer one round of edits. Then return to SKILL.md Phase 2. diff --git a/plugins/compound-engineering/skills/ce-product-pulse/references/report-template.md b/plugins/compound-engineering/skills/ce-product-pulse/references/report-template.md new file mode 100644 index 000000000..e5e62a76c --- /dev/null +++ b/plugins/compound-engineering/skills/ce-product-pulse/references/report-template.md @@ -0,0 +1,86 @@ +# Pulse Report Template + +Loaded by `SKILL.md` at Phase 2.3 after queries have returned. Fill the template using the query results. Target total length: 30-40 lines. + +## Rules for filling in + +- Use real numbers, not ranges or hedges. If a number is uncertain, note the source inline. +- Percent deltas compare the current window to the previous equal-length window (e.g., for `24h`, compare to the prior `24h`). If no comparison is possible, omit the delta rather than inventing one. +- No hardcoded thresholds. Do not label things "high" or "low" or color anything red unless the reader asked for threshold-based annotation at setup. +- No PII. No emails, no account IDs, no message content. +- Headlines are the top of the page. If a reader only reads the first 3 lines, they should know the most important thing that happened. +- If the config carried strategy metrics forward (see `docs/product-pulse.md` "Strategy metrics carried forward"), render each one in the Usage section with its current value and delta. If a strategy metric has no current value, include it anyway and mark it `no data`. + +## Template + +The block below is the literal content to write. Replace every `{{placeholder}}` with query output. Delete lines whose data isn't available for this run. + +~~~markdown +# {{product_name}} Pulse - {{window}} - {{YYYY-MM-DD HH:MM}} {{TZ}} + +## Headlines + +- {{one-line headline capturing the most notable thing in the window}} +- {{optional second headline}} +- {{optional third headline}} + +## Usage + +- **Primary engagement:** {{N events}} ({{delta vs prior window}}) +- **Value realization:** {{N events}} ({{delta}}) - {{ratio vs engagement}} +- **Completions / conversions:** + - {{conversion event 1}}: {{N}} ({{delta}}) + - {{conversion event 2}}: {{N}} ({{delta}}) +- **Strategy metrics (if carried forward):** + - {{metric name}}: {{value}} ({{delta}}) +- **Quality sample (if configured):** {{distribution e.g. "8x 5, 1x 4, 1x 2"}} + +## System performance + +- **Latency:** p50 {{ms}}, p95 {{ms}}, p99 {{ms}} ({{delta vs prior window}}) +- **Top errors** (top 5 by count, descending): + 1. **{{error signature}}** - {{N occurrences}} - {{one-line context, no PII}} + 2. **{{error signature}}** - {{N occurrences}} - {{one-line context}} + 3. **{{error signature}}** - {{N occurrences}} - {{one-line context}} + 4. **{{error signature}}** - {{N occurrences}} - {{one-line context}} + 5. **{{error signature}}** - {{N occurrences}} - {{one-line context}} + +## Followups + +- {{One thing worth investigating next - specific enough to act on}} +- {{Another thing worth investigating}} +- {{3-5 items max; trim if thin}} + +--- +_Source windows: analytics [{{start}} -> {{end}}], tracing [{{start}} -> {{end}}], payments [{{start}} -> {{end}}]. Trailing buffer: 15m. Saved to `~/pulse-reports/{{YYYY-MM-DD}}_{{HH-MM}}.md`._ +~~~ + +## Variations + +- **No system performance tool configured:** omit the entire `## System performance` section. The report stays Headlines / Usage / Followups. +- **Quality scoring not opted in:** omit the quality sample line. +- **Single-source setup (analytics only):** omit the tracing and payments source windows from the footer. +- **Error count customized at setup** (e.g., top 3 instead of top 5): follow the configured count. Do not pad or trim beyond what the query returned. + +## Post-write checklist + +Before saving and surfacing to chat: + +- [ ] Total length is 30-40 lines (give or take 5). +- [ ] Headlines exist and lead with the most notable item. +- [ ] No hardcoded thresholds ("high error rate", "low conversion"). +- [ ] No PII. Scan error signatures and followups for user emails, IDs, or message snippets. +- [ ] Top 5 errors (or the configured count), not top 10. Trim if the query returned more. +- [ ] Strategy metrics carried forward from config are rendered in Usage, or marked `no data`. +- [ ] Followups are specific - each one should be actionable as a sentence. +- [ ] Filename and in-file timestamp use the same wall-clock time. + +## What to surface in chat + +After writing the file, post back: + +- The Headlines section verbatim +- The top Followup, if action looks urgent +- The saved file path so the user can open the full report + +Do not paste the full report into chat - the file is the artifact. From d5dbe6139c464814ccbc9e54945f974feb0aee1a Mon Sep 17 00:00:00 2001 From: imwm Date: Fri, 17 Apr 2026 20:49:45 -0700 Subject: [PATCH 3/5] ideate, brainstorm, and plan read docs/strategy.md as grounding --- plugins/compound-engineering/skills/ce-brainstorm/SKILL.md | 2 +- plugins/compound-engineering/skills/ce-ideate/SKILL.md | 5 +++-- plugins/compound-engineering/skills/ce-plan/SKILL.md | 2 ++ 3 files changed, 6 insertions(+), 3 deletions(-) diff --git a/plugins/compound-engineering/skills/ce-brainstorm/SKILL.md b/plugins/compound-engineering/skills/ce-brainstorm/SKILL.md index 44e59a61f..8689754fe 100644 --- a/plugins/compound-engineering/skills/ce-brainstorm/SKILL.md +++ b/plugins/compound-engineering/skills/ce-brainstorm/SKILL.md @@ -100,7 +100,7 @@ Scan the repo before substantive brainstorming. Match depth to scope: **Standard and Deep** — Two passes: -*Constraint Check* — Check project instruction files (`AGENTS.md`, and `CLAUDE.md` only if retained as compatibility context) for workflow, product, or scope constraints that affect the brainstorm. If these add nothing, move on. +*Constraint Check* — Check project instruction files (`AGENTS.md`, and `CLAUDE.md` only if retained as compatibility context) for workflow, product, or scope constraints that affect the brainstorm. Also read `docs/strategy.md` if it exists — the product's target problem, approach, persona, and active tracks are direct input to what this brainstorm should deliver and should shape scope, success criteria, and which approaches are aligned vs out-of-scope. If these add nothing, move on. *Topic Scan* — Search for relevant terms. Read the most relevant existing artifact if one exists (brainstorm, plan, spec, skill, feature doc). Skim adjacent examples covering similar behavior. diff --git a/plugins/compound-engineering/skills/ce-ideate/SKILL.md b/plugins/compound-engineering/skills/ce-ideate/SKILL.md index f322a08bf..c3d92d337 100644 --- a/plugins/compound-engineering/skills/ce-ideate/SKILL.md +++ b/plugins/compound-engineering/skills/ce-ideate/SKILL.md @@ -181,13 +181,14 @@ Run grounding agents in parallel in the **foreground** (do not background — re 1. **Quick context scan** — dispatch a general-purpose sub-agent using the platform's cheapest capable model (e.g., `model: "haiku"` in Claude Code) with this prompt: - > Read the project's AGENTS.md (or CLAUDE.md only as compatibility fallback, then README.md if neither exists), then discover the top-level directory layout using the native file-search/glob tool (e.g., `Glob` with pattern `*` or `*/*` in Claude Code). Return a concise summary (under 30 lines) covering: + > Read the project's AGENTS.md (or CLAUDE.md only as compatibility fallback, then README.md if neither exists), then discover the top-level directory layout using the native file-search/glob tool (e.g., `Glob` with pattern `*` or `*/*` in Claude Code). Also read `docs/strategy.md` if it exists — it captures the product's target problem, approach, persona, metrics, and tracks. Return a concise summary (under 30 lines) covering: > - project shape (language, framework, top-level directory layout) > - notable patterns or conventions > - obvious pain points or gaps > - likely leverage points for improvement + > - product strategy summary, if `docs/strategy.md` was present — include the approach and active tracks verbatim so ideation can weight toward strategy-aligned directions > - > Keep the scan shallow — read only top-level documentation and directory structure. Do not analyze GitHub issues, templates, or contribution guidelines. Do not do deep code search. + > Keep the scan shallow — read only top-level documentation, `docs/strategy.md` if present, and directory structure. Do not analyze GitHub issues, templates, or contribution guidelines. Do not do deep code search. > > Focus hint: {focus_hint} diff --git a/plugins/compound-engineering/skills/ce-plan/SKILL.md b/plugins/compound-engineering/skills/ce-plan/SKILL.md index f5a9176b9..a72bdff01 100644 --- a/plugins/compound-engineering/skills/ce-plan/SKILL.md +++ b/plugins/compound-engineering/skills/ce-plan/SKILL.md @@ -172,6 +172,7 @@ If depth is unclear, ask one targeted question and then continue. Prepare a concise planning context summary (a paragraph or two) to pass as input to the research agents: - If an origin document exists, summarize the problem frame, requirements, and key decisions from that document - Otherwise use the feature description directly +- If `docs/strategy.md` exists, read it and include the relevant pieces (target problem, approach, active tracks) in the summary so downstream research and planning decisions are anchored to product strategy Run these agents in parallel: @@ -183,6 +184,7 @@ Collect: - Implementation patterns, relevant files, modules, and tests - AGENTS.md guidance that materially affects the plan, with CLAUDE.md used only as compatibility fallback when present - Institutional learnings from `docs/solutions/` +- Product strategy context when `docs/strategy.md` is present — flag any plan decisions that pull away from the active tracks or the stated approach **Slack context** (opt-in) — never auto-dispatch. Route by condition: From ab29498ae6274ce7eb3257f122f77db418859ca0 Mon Sep 17 00:00:00 2001 From: imwm Date: Fri, 17 Apr 2026 20:50:12 -0700 Subject: [PATCH 4/5] add strategy and product-pulse to readme --- README.md | 10 ++++++++-- plugins/compound-engineering/README.md | 6 ++++-- 2 files changed, 12 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 4d8401b85..77c93be81 100644 --- a/README.md +++ b/README.md @@ -28,22 +28,28 @@ Compound engineering inverts this. 80% is in planning and review, 20% is in exec ``` Brainstorm -> Plan -> Work -> Review -> Compound -> Repeat ^ - Ideate (optional -- when you need ideas) + Ideate (optional) ``` | Command | Purpose | |---------|---------| +| `/ce:strategy` | Create or maintain `docs/strategy.md` -- the product's target problem, approach, persona, key metrics, and tracks. Read as grounding by ideate, brainstorm, and plan | | `/ce:ideate` | Discover high-impact project improvements through divergent ideation and adversarial filtering | | `/ce:brainstorm` | Explore requirements and approaches before planning | | `/ce:plan` | Turn feature ideas into detailed implementation plans | | `/ce:work` | Execute plans with worktrees and task tracking | | `/ce:review` | Multi-agent code review before merging | | `/ce:compound` | Document learnings to make future work easier | +| `/ce:product-pulse` | Generate a single-page, time-windowed pulse report on usage, performance, errors, and followups. Saves to `~/pulse-reports/` | -`/ce:brainstorm` is the main entry point -- it refines ideas into a requirements plan through interactive Q&A, and short-circuits automatically when ceremony isn't needed. `/ce:plan` takes either a requirements doc from brainstorming or a detailed idea and distills it into a technical plan that agents (or humans) can work from. +`/ce:strategy` is upstream of the loop -- it captures the product's target problem, approach, persona, metrics, and tracks as a short durable anchor at `docs/strategy.md`. Ideate, brainstorm, and plan read it as grounding when present, so strategy choices flow into feature conception, prioritization, and spec. + +`/ce:brainstorm` is the main loop entry point -- it refines ideas into a requirements plan through interactive Q&A, and short-circuits automatically when ceremony isn't needed. `/ce:plan` takes either a requirements doc from brainstorming or a detailed idea and distills it into a technical plan that agents (or humans) can work from. `/ce:ideate` is used less often but can be a force multiplier -- it proactively surfaces strong improvement ideas based on your codebase, with optional steering from you. +`/ce:product-pulse` is the read-side companion -- a time-windowed report on what users actually experienced and how the product performed over a given window (24h, 7d, etc.), saved to `~/pulse-reports/` so past pulses form a browseable timeline of user outcomes. The next strategy update and the next brainstorm get real signal to anchor to. + Each cycle compounds: brainstorms sharpen plans, plans inform future plans, reviews catch more issues, patterns get documented. ### Getting started diff --git a/plugins/compound-engineering/README.md b/plugins/compound-engineering/README.md index e90b1bafd..35aaf82ae 100644 --- a/plugins/compound-engineering/README.md +++ b/plugins/compound-engineering/README.md @@ -11,16 +11,17 @@ After installing, run `/ce-setup` in any project. It diagnoses your environment, | Component | Count | |-----------|-------| | Agents | 50+ | -| Skills | 42+ | +| Skills | 44+ | ## Skills ### Core Workflow -The primary entry points for engineering work, invoked as slash commands: +The primary entry points for engineering work, invoked as slash commands. `/ce:strategy` anchors the loop upstream; `/ce:product-pulse` closes it with a read on user outcomes. | Skill | Description | |-------|-------------| +| `/ce:strategy` | Create or maintain `docs/strategy.md` — the product's target problem, approach, persona, key metrics, and tracks. Re-runnable to update. Read as grounding by `/ce:ideate`, `/ce:brainstorm`, and `/ce:plan` when present | | `/ce:ideate` | Discover high-impact project improvements through divergent ideation and adversarial filtering | | `/ce:brainstorm` | Explore requirements and approaches before planning | | `/ce:plan` | Create structured plans for any multi-step task -- software features, research workflows, events, study plans -- with automatic confidence checking | @@ -30,6 +31,7 @@ The primary entry points for engineering work, invoked as slash commands: | `/ce:compound` | Document solved problems to compound team knowledge | | `/ce:compound-refresh` | Refresh stale or drifting learnings and decide whether to keep, update, replace, or archive them | | `/ce-optimize` | Run iterative optimization loops with parallel experiments, measurement gates, and LLM-as-judge quality scoring | +| `/ce:product-pulse` | Generate a single-page, time-windowed report on usage, performance, errors, and followups. Saves reports to `~/pulse-reports/` as a browseable timeline of what users experienced | For `/ce-optimize`, see [`skills/ce-optimize/README.md`](./skills/ce-optimize/README.md) for usage guidance, example specs, and links to the schema and workflow docs. From cdb1664a1fbd6bbbdbae57a06caccad919c51f97 Mon Sep 17 00:00:00 2001 From: imwm Date: Mon, 20 Apr 2026 13:13:38 -0700 Subject: [PATCH 5/5] refactor(ce-strategy,ce-product-pulse): switch to dash-form skill names --- README.md | 8 ++++---- plugins/compound-engineering/README.md | 6 +++--- .../compound-engineering/skills/ce-product-pulse/SKILL.md | 6 +++--- .../skills/ce-product-pulse/references/interview.md | 2 +- plugins/compound-engineering/skills/ce-strategy/SKILL.md | 4 ++-- .../skills/ce-strategy/references/strategy-template.md | 2 +- 6 files changed, 14 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 77c93be81..d2c16ce9f 100644 --- a/README.md +++ b/README.md @@ -33,22 +33,22 @@ Brainstorm -> Plan -> Work -> Review -> Compound -> Repeat | Command | Purpose | |---------|---------| -| `/ce:strategy` | Create or maintain `docs/strategy.md` -- the product's target problem, approach, persona, key metrics, and tracks. Read as grounding by ideate, brainstorm, and plan | +| `/ce-strategy` | Create or maintain `docs/strategy.md` -- the product's target problem, approach, persona, key metrics, and tracks. Read as grounding by ideate, brainstorm, and plan | | `/ce:ideate` | Discover high-impact project improvements through divergent ideation and adversarial filtering | | `/ce:brainstorm` | Explore requirements and approaches before planning | | `/ce:plan` | Turn feature ideas into detailed implementation plans | | `/ce:work` | Execute plans with worktrees and task tracking | | `/ce:review` | Multi-agent code review before merging | | `/ce:compound` | Document learnings to make future work easier | -| `/ce:product-pulse` | Generate a single-page, time-windowed pulse report on usage, performance, errors, and followups. Saves to `~/pulse-reports/` | +| `/ce-product-pulse` | Generate a single-page, time-windowed pulse report on usage, performance, errors, and followups. Saves to `~/pulse-reports/` | -`/ce:strategy` is upstream of the loop -- it captures the product's target problem, approach, persona, metrics, and tracks as a short durable anchor at `docs/strategy.md`. Ideate, brainstorm, and plan read it as grounding when present, so strategy choices flow into feature conception, prioritization, and spec. +`/ce-strategy` is upstream of the loop -- it captures the product's target problem, approach, persona, metrics, and tracks as a short durable anchor at `docs/strategy.md`. Ideate, brainstorm, and plan read it as grounding when present, so strategy choices flow into feature conception, prioritization, and spec. `/ce:brainstorm` is the main loop entry point -- it refines ideas into a requirements plan through interactive Q&A, and short-circuits automatically when ceremony isn't needed. `/ce:plan` takes either a requirements doc from brainstorming or a detailed idea and distills it into a technical plan that agents (or humans) can work from. `/ce:ideate` is used less often but can be a force multiplier -- it proactively surfaces strong improvement ideas based on your codebase, with optional steering from you. -`/ce:product-pulse` is the read-side companion -- a time-windowed report on what users actually experienced and how the product performed over a given window (24h, 7d, etc.), saved to `~/pulse-reports/` so past pulses form a browseable timeline of user outcomes. The next strategy update and the next brainstorm get real signal to anchor to. +`/ce-product-pulse` is the read-side companion -- a time-windowed report on what users actually experienced and how the product performed over a given window (24h, 7d, etc.), saved to `~/pulse-reports/` so past pulses form a browseable timeline of user outcomes. The next strategy update and the next brainstorm get real signal to anchor to. Each cycle compounds: brainstorms sharpen plans, plans inform future plans, reviews catch more issues, patterns get documented. diff --git a/plugins/compound-engineering/README.md b/plugins/compound-engineering/README.md index 35aaf82ae..cb559598b 100644 --- a/plugins/compound-engineering/README.md +++ b/plugins/compound-engineering/README.md @@ -17,11 +17,11 @@ After installing, run `/ce-setup` in any project. It diagnoses your environment, ### Core Workflow -The primary entry points for engineering work, invoked as slash commands. `/ce:strategy` anchors the loop upstream; `/ce:product-pulse` closes it with a read on user outcomes. +The primary entry points for engineering work, invoked as slash commands. `/ce-strategy` anchors the loop upstream; `/ce-product-pulse` closes it with a read on user outcomes. | Skill | Description | |-------|-------------| -| `/ce:strategy` | Create or maintain `docs/strategy.md` — the product's target problem, approach, persona, key metrics, and tracks. Re-runnable to update. Read as grounding by `/ce:ideate`, `/ce:brainstorm`, and `/ce:plan` when present | +| `/ce-strategy` | Create or maintain `docs/strategy.md` — the product's target problem, approach, persona, key metrics, and tracks. Re-runnable to update. Read as grounding by `/ce:ideate`, `/ce:brainstorm`, and `/ce:plan` when present | | `/ce:ideate` | Discover high-impact project improvements through divergent ideation and adversarial filtering | | `/ce:brainstorm` | Explore requirements and approaches before planning | | `/ce:plan` | Create structured plans for any multi-step task -- software features, research workflows, events, study plans -- with automatic confidence checking | @@ -31,7 +31,7 @@ The primary entry points for engineering work, invoked as slash commands. `/ce:s | `/ce:compound` | Document solved problems to compound team knowledge | | `/ce:compound-refresh` | Refresh stale or drifting learnings and decide whether to keep, update, replace, or archive them | | `/ce-optimize` | Run iterative optimization loops with parallel experiments, measurement gates, and LLM-as-judge quality scoring | -| `/ce:product-pulse` | Generate a single-page, time-windowed report on usage, performance, errors, and followups. Saves reports to `~/pulse-reports/` as a browseable timeline of what users experienced | +| `/ce-product-pulse` | Generate a single-page, time-windowed report on usage, performance, errors, and followups. Saves reports to `~/pulse-reports/` as a browseable timeline of what users experienced | For `/ce-optimize`, see [`skills/ce-optimize/README.md`](./skills/ce-optimize/README.md) for usage guidance, example specs, and links to the schema and workflow docs. diff --git a/plugins/compound-engineering/skills/ce-product-pulse/SKILL.md b/plugins/compound-engineering/skills/ce-product-pulse/SKILL.md index 95caeb3cc..3d1a678fd 100644 --- a/plugins/compound-engineering/skills/ce-product-pulse/SKILL.md +++ b/plugins/compound-engineering/skills/ce-product-pulse/SKILL.md @@ -1,12 +1,12 @@ --- -name: ce:product-pulse +name: ce-product-pulse description: "Generate a time-windowed pulse report on what users experienced and how the product performed - usage, quality, errors, signals worth investigating. Use when the user says 'run a pulse', 'show me the pulse', 'how are we doing', 'weekly recap', 'launch-day check', or passes a time window like '24h' or '7d'. Produces a single-page report saved to ~/pulse-reports/ and summarized in chat." argument-hint: "[lookback window, e.g. '24h', '7d', '1h'; default 24h]" --- # Product Pulse -`ce:product-pulse` queries the product's data sources for a given time window and produces a compact, single-page report covering usage, performance, errors, and followups. The report is saved to `~/pulse-reports/` and the key points are surfaced in chat. +`ce-product-pulse` queries the product's data sources for a given time window and produces a compact, single-page report covering usage, performance, errors, and followups. The report is saved to `~/pulse-reports/` and the key points are surfaced in chat. This is a read-only skill. It reports on what happened; it does not fix anything, ship anything, or change the product. @@ -62,7 +62,7 @@ Before asking any questions, read `docs/strategy.md` using the native file-read Open the interview by showing the user what was pulled forward: "I see you have a strategy doc on file - I'll seed the product name as `{{name}}` and carry these key metrics into the event/data setup: {{metric list}}. Say so if any of that needs to change." -If `docs/strategy.md` does not exist, note that too: "No strategy doc on file. Running the full setup from scratch. (If you want strategy to seed this later, run `/ce:strategy` first.)" +If `docs/strategy.md` does not exist, note that too: "No strategy doc on file. Running the full setup from scratch. (If you want strategy to seed this later, run `/ce-strategy` first.)" #### 1.1 Interview diff --git a/plugins/compound-engineering/skills/ce-product-pulse/references/interview.md b/plugins/compound-engineering/skills/ce-product-pulse/references/interview.md index adfbe3599..bf0db6ec2 100644 --- a/plugins/compound-engineering/skills/ce-product-pulse/references/interview.md +++ b/plugins/compound-engineering/skills/ce-product-pulse/references/interview.md @@ -227,7 +227,7 @@ After the interview completes, write `docs/product-pulse.md` using this structur ~~~markdown # {{product_name}} Pulse Config -_Last updated: {{YYYY-MM-DD}}. Re-run `/ce:product-pulse setup` to edit._ +_Last updated: {{YYYY-MM-DD}}. Re-run `/ce-product-pulse setup` to edit._ ## Events diff --git a/plugins/compound-engineering/skills/ce-strategy/SKILL.md b/plugins/compound-engineering/skills/ce-strategy/SKILL.md index 2003ff781..180fb469c 100644 --- a/plugins/compound-engineering/skills/ce-strategy/SKILL.md +++ b/plugins/compound-engineering/skills/ce-strategy/SKILL.md @@ -1,5 +1,5 @@ --- -name: ce:strategy +name: ce-strategy description: "Create or maintain docs/strategy.md - the product's target problem, approach, users, key metrics, and tracks of work. Use when starting a new product, updating direction, or when prompts like 'write our strategy', 'update the roadmap', 'what are we working on', or 'set up the strategy doc' come up. Also triggers when ce:ideate, ce:brainstorm, or ce:plan need upstream grounding and no strategy doc exists yet." argument-hint: "[optional: section to revisit, e.g. 'metrics' or 'approach']" --- @@ -8,7 +8,7 @@ argument-hint: "[optional: section to revisit, e.g. 'metrics' or 'approach']" **Note: The current year is 2026.** Use this when dating the strategy document. -`ce:strategy` produces and maintains `docs/strategy.md` - a short, durable anchor document that captures what the product is, who it serves, how it succeeds, and where the team is investing. Downstream skills (`ce:ideate`, `ce:brainstorm`, `ce:plan`) read it as grounding when it exists. +`ce-strategy` produces and maintains `docs/strategy.md` - a short, durable anchor document that captures what the product is, who it serves, how it succeeds, and where the team is investing. Downstream skills (`ce:ideate`, `ce:brainstorm`, `ce:plan`) read it as grounding when it exists. The document is short and structured on purpose. Good answers to a handful of sharp questions produce a better strategy than any amount of prose. This skill asks those questions, pushes back on weak answers, and writes the doc. diff --git a/plugins/compound-engineering/skills/ce-strategy/references/strategy-template.md b/plugins/compound-engineering/skills/ce-strategy/references/strategy-template.md index f45afc8cf..e4fc1302f 100644 --- a/plugins/compound-engineering/skills/ce-strategy/references/strategy-template.md +++ b/plugins/compound-engineering/skills/ce-strategy/references/strategy-template.md @@ -17,7 +17,7 @@ The block below is the literal file to write (minus this line and the fences). R ~~~markdown # {{product_name}} Strategy -_Last updated: {{YYYY-MM-DD}}. Re-run `/ce:strategy` to update._ +_Last updated: {{YYYY-MM-DD}}. Re-run `/ce-strategy` to update._ ## Target problem