Every template Claude reads on session start.

# CLAUDE.md

> Memory file. Claude reads this on every session start. Keep it under 500 lines.
> Replace the bracketed TODOs with details about your team and product.

## Product

[TODO] One paragraph: what you're building and who it's for.

Example: *We build a payments API for marketplaces with 1–50 sellers. Our buyer is the marketplace's founding engineer. Our anti-buyer is enterprise procurement.*

## Team

- **PM:** [TODO — your name + handle]
- **Eng lead:** [TODO]
- **Design:** [TODO]
- **Anyone else with commit access:** [TODO]

## Stack

- [TODO] Frontend
- [TODO] Backend
- [TODO] Database
- [TODO] Hosting
- [TODO] Auth
- [TODO] Analytics

## Voice

How we write — for docs, release notes, support replies, and anything else that goes out.

- Period-end declarative sentences. No questions in marketing copy.
- Specific nouns over abstract claims. "Datadog, Salesforce, Stripe" beats "every major tool".
- Active verbs. "Ships the fix" beats "facilitates resolution".
- Trust the reader. Don't over-explain.
- Plain words. "Tag" not "invoke". "Run" not "execute".

**Words we don't use:** unlock, empower, leverage, seamless, frictionless, revolutionary, next-generation, AI-powered, ecosystem, cutting-edge, robust, scalable, enterprise-grade.

## Agents and skills

Skills live in `skills/`. The ones shipped with this repo:

- `your-brand/` — our design system as a skill
- `writing-prds/` — paired with `pr_flow/create-prd.mdc`
- `writing-release-notes/` — user-facing notes from merged PRs
- `writing-stakeholder-updates/` — weekly updates by audience
- `synthesizing-user-research/` — interview → themes + JTBD
- `prioritizing-features/` — framework picker + scoring

When you write the same kind of artifact twice, build a skill the third time. Gerund form (`writing-foo`, `prioritizing-bar`) so Claude auto-invokes.

## Workflow

For any non-trivial feature:

1. Drop a PRD into `tasks/prd-<feature>.md` using `pr_flow/create-prd.mdc`.
2. Generate the task list with `pr_flow/generate-tasks.mdc`.
3. Process tasks one at a time with `pr_flow/process-task-list.mdc`.
4. Use plan mode (`Shift+Tab` in the CLI) before any file changes.

## What not to do

- Don't commit `.env`, API keys, or anything in `.gitignore`'d paths.
- Don't paste secrets into chat. They live in the context forever.
- Don't skip the PRD on features the eng team will spend more than a day on.
- Don't approve a plan you didn't read.
- Don't write a skill named `helper`, `utils`, or anything vague.
- Don't stay in a session past the point Claude has lost the plot — open a new chat.
- **Don't force-push or reset shared branches.** Never run `git reset --hard`, `git push --force`, or `git rebase -i` against `main` or any branch others use without explicit written approval. Even retroactively "fixing" commit history rewrites what others have cloned and causes merge conflicts.

## References

Long-form context Claude can pull in when relevant:

- `docs/product.md` — what we're building, in depth
- `docs/architecture.md` — stack, dependencies, decisions
- `docs/voice.md` — voice rules with examples
- `DESIGN.md` — brand spec (colors, type, components)
- `pr_flow/*.mdc` — the PRD → tasks → execute rules

# DESIGN.md

> Brand spec template. Fill in your brand values and Claude reads them every session.
> Reference this file from `CLAUDE.md` so the design system is always in context.
>
> For the deeper version (used by Claude when generating artifacts), see `skills/your-brand/SKILL.md`.

## At a glance

| Element | Spec |
|---|---|
| Primary color | [TODO `#xxxxxx`] |
| Logo | [TODO file path + dark/light variants] |
| Headline type | [TODO size/weight/letter-spacing/color] |
| Body type | [TODO size/line-height/color] |
| Voice | [TODO one sentence — e.g. "Short, declarative, period-ending. One idea per sentence."] |

## Colors

- `primary` `[TODO]` — brand color, used sparingly
- `text` `[TODO]` — body and headlines
- `textMuted` `[TODO]` — supporting copy
- `border` `[TODO]` — card borders, dividers
- `bg` `[TODO]` — default background

Status colors (use only for meaning, not branding):

- `success` `[TODO]`
- `info` `[TODO]`
- `warning` `[TODO]`
- `error` `[TODO]`

## Typography

System stacks recommended (no webfont latency, consistent everywhere):

- Sans: `-apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif`
- Mono: `"SF Mono", "JetBrains Mono", Menlo, monospace`

Type scale:

| Role | Size | Weight | Color |
|---|---|---|---|
| Hero headline | [TODO] | [TODO] | text |
| Page H1 | [TODO] | [TODO] | text |
| Section H2 | [TODO] | [TODO] | text |
| Body | [TODO] | [TODO] | textMuted |
| Code | [TODO] | [TODO] | text (mono) |

## Voice

[TODO three paragraphs on how your brand sounds. Include 3–5 example sentences in your voice and 3–5 words you never use.]

### Words we don't use

[TODO list]

## Logo

- Where to find it: [TODO file path]
- When to invert: [TODO]
- Minimum clear space: [TODO]
- What never to do: [TODO]

## Cards & surfaces

[TODO describe how cards look — border, radius, shadow, padding]

## Checklist before shipping anything branded

- [ ] Color is from the palette above (no improvised hex codes)
- [ ] Headline reads like one of our example sentences
- [ ] No words from the "don't use" list
- [ ] Logo respects clear space and color rules
- [ ] If it lives next to other brand artifacts, they look like siblings

---
description: PRD authoring rule. Invoke when the user wants a new feature spec.
globs:
alwaysApply: false
---
# Rule: Generating a Product Requirements Document (PRD)

## Goal

To guide an AI assistant in creating a detailed Product Requirements Document (PRD) in Markdown format, based on an initial user prompt. The PRD should be clear, actionable, and suitable for a junior developer to understand and implement the feature.

## Process

1. **Receive Initial Prompt:** The user provides a brief description or request for a new feature or functionality.
2. **Ask Clarifying Questions:** Before writing the PRD, the AI *must* ask clarifying questions to gather sufficient detail. The goal is to understand the "what" and "why" of the feature, not necessarily the "how" (which the developer will figure out). Make sure to provide options in letter/number lists so the user can respond easily with selections.
3. **Generate PRD:** Based on the initial prompt and the user's answers, generate a PRD using the structure outlined below.
4. **Save PRD:** Save the generated document as `tasks/[feature-name]/task.md`.
5. **Seed sessions log:** Create `tasks/[feature-name]/sessions.md` with a single starter entry: today's date, status "Not started", and any open questions noted.

## Clarifying Questions (Examples)

Adapt the questions based on the prompt, but cover these areas:

- **Problem/Goal:** "What problem does this feature solve for the user?" or "What is the main goal we want to achieve?"
- **Target User:** "Who is the primary user of this feature?"
- **Core Functionality:** "Can you describe the key actions a user should be able to perform?"
- **User Stories:** "Could you provide a few user stories? (As a [type of user], I want to [perform an action] so that [benefit].)"
- **Acceptance Criteria:** "How will we know when this feature is successfully implemented?"
- **Scope/Boundaries:** "Are there any specific things this feature *should not* do (non-goals)?"
- **Data Requirements:** "What kind of data does this feature need to display or manipulate?"
- **Design/UI:** "Are there existing design mockups or UI guidelines to follow?"
- **Edge Cases:** "Are there any potential edge cases or error conditions to consider?"

## PRD Structure

1. **Introduction/Overview:** Briefly describe the feature and the problem it solves. State the goal.
2. **Goals:** List the specific, measurable objectives for this feature.
3. **User Stories:** Detail the user narratives describing feature usage and benefits.
4. **Functional Requirements:** List the specific functionalities the feature must have. Number them. Use clear, concise language.
5. **Non-Goals (Out of Scope):** Clearly state what this feature will *not* include to manage scope.
6. **Design Considerations (Optional):** Link to mockups, describe UI/UX requirements, or mention relevant components/styles.
7. **Technical Considerations (Optional):** Mention known technical constraints, dependencies, or suggestions.
8. **Success Metrics:** How will the success of this feature be measured?
9. **Open Questions:** List any remaining questions or areas needing further clarification.

## Target Audience

Assume the primary reader of the PRD is a **junior developer**. Requirements must be explicit, unambiguous, and avoid jargon where possible. Provide enough detail for them to understand the feature's purpose and core logic.

## Output

- **Format:** Markdown (`.md`)
- **Location:** `tasks/[feature-name]/`
- **Files created:** `task.md` (the PRD) and `sessions.md` (seeded work log)

## Final instructions

1. Do NOT start implementing the PRD.
2. Make sure to ask the user clarifying questions.
3. Take the user's answers and improve the PRD before saving.
4. Create both files: `task.md` and a seeded `sessions.md`.

---
description: Task-list generation rule. Invoke after a PRD exists.
globs:
alwaysApply: false
---
# Rule: Generating a Task List from a PRD

## Goal

To guide an AI assistant in turning a PRD (`tasks/[feature-name]/task.md`) into a detailed, step-by-step task list a junior developer can execute one item at a time.

## Output

- **Format:** Markdown (`.md`)
- **Location:** `tasks/[feature-name]/`
- **Filename:** `tasks.md`

## Process

1. **Read the PRD:** Open `tasks/[feature-name]/task.md` in full.
2. **Generate Parent Tasks (Phase 1):** Produce 4–7 high-level parent tasks that, together, deliver the PRD. Stop and ask: **"Ready to generate sub-tasks? Respond 'go' to continue."**
3. **Wait for confirmation:** Do not proceed until the user replies `go`.
4. **Generate Sub-tasks (Phase 2):** Break each parent task into 2–6 ordered sub-tasks. Each sub-task is small enough to complete in one editing session.
5. **Identify Relevant Files:** List the files the implementer will create or change, with a one-line description each.
6. **Save** the file to `tasks/[feature-name]/tasks.md` in the structure below.

## Output Structure

```markdown
# Tasks: [feature name]

## Relevant Files

- `path/to/file.ts` — what changes here
- `path/to/test.spec.ts` — tests for the above

## Parent Tasks

- [ ] 1.0 Parent task title
  - [ ] 1.1 Sub-task
  - [ ] 1.2 Sub-task
- [ ] 2.0 Parent task title
  - [ ] 2.1 Sub-task
```

## Final instructions

1. Do NOT start implementing.
2. Pause for `go` between Phase 1 and Phase 2.
3. Each sub-task should be small enough that processing it via `process-task-list.mdc` won't sprawl into multiple files unexpectedly.

---
description: Task execution rule. Process one sub-task at a time.
globs:
alwaysApply: false
---
# Rule: Processing a Task List

## Goal

To guide an AI assistant through executing a task list (`tasks/[feature-name]/tasks.md`) **one sub-task at a time**, with user approval between each.

## Starting a session

Before picking up the first sub-task, read both:
- `tasks/[feature-name]/task.md` — the full requirements
- `tasks/[feature-name]/sessions.md` — the history of prior sessions

Give a one-paragraph summary of where things stand, then ask which sub-task to start with (or default to the next unchecked one).

## Process

1. **Find the next unchecked sub-task** (top-down, left-to-right).
2. **Implement only that sub-task.** No scope creep. No "while I'm here".
3. **Mark it complete:** change `[ ]` to `[x]` in the task list file.
4. **Stop and report:**
   - What you changed (file paths, one line each).
   - What you tested (or what you couldn't test).
   - What's next.
5. **Wait for the user to say `next`** (or equivalent) before starting the next sub-task.

## When a parent task's sub-tasks are all `[x]`

- Mark the parent `[x]`.
- Run any tests or linters relevant to the parent task.
- Summarize what the parent delivered.
- Pause for the user to review before moving on.

## Ending a session

When the user signals they're done for the day (or after completing a parent task), append a dated entry to `tasks/[feature-name]/sessions.md`:

```markdown
## YYYY-MM-DD

**Accomplished:**
- What was built or changed

**Decisions:**
- Any choices made and why

**Next steps:**
- First unchecked sub-task and anything that depends on it

**Status:** In progress / Blocked / Done
```

## What not to do

- Do NOT batch multiple sub-tasks in one response.
- Do NOT proceed without explicit `next`.
- Do NOT modify files outside the "Relevant Files" list without flagging it first.
- Do NOT skip the test/lint step on parent-task completion.
- Do NOT skip updating `sessions.md` at session end — it's the handoff note for the next session.

## When you get stuck

If a sub-task can't be completed as written:

1. Stop. Don't improvise.
2. Tell the user: *"Sub-task X.Y is blocked by Z. Options: (a) skip and move to X.Y+1, (b) revise the task, (c) revise the PRD."*
3. Wait for direction.

---
name: your-brand
description: |
  Your team's brand system — colors, typography, voice, logo rules, and the
  surface treatments that make every artifact look like the same studio shipped
  it. Use whenever generating UI, landing pages, ads, decks, emails, animations,
  release notes, or any artifact that will be seen by a customer or stakeholder.
allowed-tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
---

# Rule: <Your brand> visual + voice system

> This file is a **template**. Fill in every `[TODO]`. Delete this notice when done.
> Reference this skill from `CLAUDE.md` so Claude loads it on every session.

## Goal

To give Claude one source of truth for how your brand looks and sounds, so every artifact it produces — a release note, a landing page, a slide, a tweet — comes out looking like the same studio shipped it. Without this skill, Claude defaults to mesh gradients and Tailwind indigo. With it, your design system wins.

## At a glance

| Element | Spec |
|---|---|
| Primary color | `[TODO #xxxxxx]` |
| Secondary / accent | `[TODO]` |
| Logo | `[TODO file path]` — `[TODO when to invert]` |
| Headline type | `[TODO size / weight / letter-spacing / color]` |
| Body type | `[TODO size / line-height / color]` |
| Voice | `[TODO one sentence — e.g. "Short, declarative, period-ending."]` |

## Color system

### Primary
- `primary` `[TODO]` — the brand color. Use sparingly.
- `primarySoft` `[TODO]` — tinted backgrounds, focus rings.

### Neutrals
- `text` `[TODO]` — body, headlines.
- `textMuted` `[TODO]` — supporting copy.
- `textSoft` `[TODO]` — captions, metadata.
- `border` `[TODO]` — dividers, card borders.

### Status (use only for meaning, not branding)
- `success` `[TODO]` · `info` `[TODO]` · `warning` `[TODO]` · `error` `[TODO]`

### Rules
- Don't introduce a new shade of the primary. If the existing tone doesn't work, change the surface around it.
- Don't use status colors for branding.
- Don't use true black. Use `text` (a near-black like `#18181b`).

## Typography

System stacks unless you have a tested webfont reason otherwise.

- Sans: `-apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif`
- Mono: `"SF Mono", "JetBrains Mono", Menlo, monospace`

### Type scale

| Role | Size | Weight | Letter-spacing | Line-height | Color |
|---|---|---|---|---|---|
| Hero headline | `[TODO]` | `[TODO]` | `[TODO]` | `[TODO]` | text |
| Page H1 | `[TODO]` | `[TODO]` | normal | `[TODO]` | text |
| Section H2 | `[TODO]` | `[TODO]` | normal | `[TODO]` | text |
| Body | `[TODO]` | `[TODO]` | normal | `[TODO]` | textMuted |
| Eyebrow | `[TODO]` ALL CAPS | `[TODO]` | `[TODO]` | 1 | primary |
| Code | `[TODO]` | `[TODO]` | normal | inherit | text (mono) |

### Mono use
Only for: code blocks, terminal output, IDs, URLs, agent handles, file paths.

## Logo

- Source asset: `[TODO file path]`
- On dark surfaces: `[TODO invert / use alt asset / never on dark]`
- Minimum clear space: `[TODO]`
- What never to do: `[TODO — e.g. recolor, stretch, combine with wordmark]`

## Voice

### In one sentence
`[TODO — e.g. "Plainspoken and concrete. Like an engineer confident in what they built, not a marketer trying to convince you."]`

### Principles
- **Specific nouns** over abstract claims. List the three things, not "every feature".
- **Active verbs.** "Ships" beats "facilitates".
- **Period-end declarative sentences.** No questions in marketing.
- **Plain words.** Choose the word a colleague would use in a demo.

### Real example headlines (your voice)
`[TODO — paste 5 real headlines from shipped work. These are the reference.]`

### Words to avoid
| Don't say | Say instead |
|---|---|
| Unlock, empower, leverage | Use, give, let |
| Seamless, frictionless | (describe what happens) |
| Revolutionary, next-generation | (cut) |
| Ecosystem, platform, solution | The actual product noun |
| Robust, scalable, enterprise-grade | (specific capability) |

## Cards & surfaces

`[TODO — describe how your cards look: border, radius, shadow, padding. Include one block of CSS or a tiny tsx snippet.]`

## Iconography

`[TODO — emoji policy, SVG line weight, when to use the brand logo as an icon.]`

## Process

1. Receive the request (a piece of UI, a release note, a deck slide, etc.).
2. Ask which surface this lives on (`marketing site`, `in-app`, `email`, `social`, `internal doc`).
3. Apply the rules above. When in doubt, fewer colors, smaller shadows, plainer copy.
4. Before delivering, run the checklist below.

## Checklist before shipping

- [ ] Color is from the palette above (no improvised hex codes).
- [ ] Headline reads like one of the example headlines.
- [ ] Body uses no banned words.
- [ ] Logo respects clear space and color rules.
- [ ] Mono font only for code, IDs, URLs.
- [ ] If it lives next to other brand artifacts, they look like siblings.

## Final instructions

1. Never improvise on color, type, or voice. If a request can't fit the spec, ask the user before extending.
2. The voice section is non-negotiable. The visual spec accommodates new surfaces; the voice carries across all of them.
3. When the user pushes back on output, note the rule that was missing. Add it to this skill the same day.

## Attribution

Inspired by Runtime's brand skill ([source](https://github.com/runtm-ai/claudecode-for-pms)) and the Notion [Brand Design Template](https://www.notion.so/Brand-Design-Template-29af2126a3a28019ba24fcd5fa6b6fc2). Approach to design-system-as-skill from Owen Williams (Stripe) on *How I AI*.

---
name: writing-prds
description: |
  Authoring a Product Requirements Document — the spec a junior dev can build
  from. Use when the user says "write a PRD", "spec out a feature", "what are
  the requirements for X", "draft a feature brief", or mentions a feature they
  want to scope. Pairs with `pr_flow/create-prd.mdc` for the full workflow.
allowed-tools:
  - Read
  - Write
  - Edit
---

# Rule: Writing a PRD

## Goal

Turn a one-line feature ask into a Product Requirements Document a junior developer can implement without having to come back with twenty questions. A PRD answers four things a prompt usually doesn't: **what problem we're solving, who it's for, what "done" looks like, and what's out of scope.** Hand Claude a prompt without those and it picks its own answers — the prompt becomes a negotiation. A PRD makes it a brief.

## Process

1. **Receive the feature request.** One sentence is fine.
2. **Ask clarifying questions** (see below) — letter/number options so the user replies with selections, not paragraphs. Never skip this step, even if the request seems clear.
3. **Draft the PRD** using the structure below.
4. **Show it to the user, ask for corrections, refine.**
5. **Save** as `tasks/prd-<feature-name>.md`.

## Clarifying Questions

Pick from these categories. Ask 4–7 questions, not all of them. Format each as a numbered or lettered list so the user can reply "1, B, 2, A".

**Problem & Goal**
- What problem does this solve?
- Why now? What changes if we don't ship this?
- A. New behavior. B. Speeds up an existing behavior. C. Fixes a broken behavior.

**Users**
- Who's the primary user? Pick one: A. New visitor. B. Existing customer. C. Internal team. D. Partner / API consumer.
- Roughly how many of them, and how often will they hit this?

**Core functionality**
- What's the smallest version that delivers the value? List the top 3 actions in order of importance.

**Acceptance criteria**
- How will we know it's working? Name one metric and one observable behavior.

**Scope**
- What's explicitly *out* of scope for this version? List 2–3 things this feature will NOT do.

**Data**
- What does the feature read, write, or transform? Is any of it sensitive?

**Design**
- Is there a mockup, a Figma link, an existing pattern to match, or do you want Claude to propose UI?

**Edge cases**
- What happens on: empty state, error state, rate-limit, offline, slow network?

## PRD Structure

The output is one Markdown file with these sections, in this order.

1. **Introduction / Overview** — one paragraph. The feature in plain words and the problem it solves.
2. **Goals** — numbered list. Each goal is specific and measurable.
3. **User Stories** — `As a [user], I want to [action] so that [benefit].` Three to seven.
4. **Functional Requirements** — numbered. Each starts with "The system must…". Junior-dev-clear.
5. **Non-Goals (Out of Scope)** — bullet list. Each line starts with "We are NOT…".
6. **Design Considerations** — links to mockups, references to existing components, brand notes.
7. **Technical Considerations** — known constraints, dependencies, "should integrate with X".
8. **Success Metrics** — primary, guardrail, secondary. Number the threshold if you can.
9. **Open Questions** — list what you couldn't pin down. Don't pretend the doc is final when it isn't.

## Target Audience

Assume the reader is a **junior developer**. Requirements must be explicit and unambiguous. Avoid jargon when a plain word works. If the team has a `docs/architecture.md` or `CLAUDE.md`, reference it instead of restating it.

## Tiny worked example

> *Feature: "passwordless login"*
>
> **Functional Requirements (excerpt):**
> 1. The login screen shall display an email field and a single "Email me a sign-in link" button.
> 2. The system shall send a one-time link valid for 15 minutes.
> 3. Clicking the link shall sign the user in and redirect them to `/dashboard`.
> 4. If the link is expired or already used, the system shall display "Link expired. Request a new one." with the email pre-filled.
> 5. The system shall rate-limit magic-link requests to 3 per email per hour.

Numbered, "system shall" form, one behavior per line. No "robust authentication flow". A junior dev reads this and writes it.

## Anti-patterns

- A PRD without a Non-Goals section. You will regret this within a week.
- "Build a feature" written in chat instead of a file Claude can re-read.
- Acceptance criteria that are vibes ("works well", "feels fast"). Pick a number.
- Functional requirements written like marketing copy. Boring is correct.
- Skipping the clarifying questions to "save time". This costs time downstream.

## Output

- **Format:** Markdown (`.md`)
- **Location:** `tasks/`
- **Filename:** `prd-<feature-name>.md` (kebab-case)

## Final instructions

1. Do NOT start implementing the feature from the PRD. The PRD's job is the spec.
2. Always ask the clarifying questions before writing. If the user pushes to skip them, write the PRD with explicit `[TBD]` markers for the answers you skipped.
3. After delivering the draft, ask one question: *"What's wrong with it?"* Then revise.

## Attribution

Synthesized from: `anthropics/knowledge-work-plugins · feature-spec` (Apache 2.0); the create-prd.mdc rule popularized in the Cursor community and updated for Claude Code; Andre Albuquerque on Aakash Gupta's [Product Growth podcast](https://www.aakashg.com/albuquerque-podcast/) (the 4-level Lovable→CC→Cursor→Agents framing); Cat Wu / Anthropic team on Lenny's Newsletter; Marcus Moretti / [Every](https://every.to/source-code/claude-code-for-product-managers) on roadmap-then-PRD; Ryan Nystrom (Notion) on [chatprd.ai](https://www.chatprd.ai/how-i-ai/ryan-nystrom-notion-workflows-for-engineering-velocity) for the spec-first dev pattern.

---
name: writing-release-notes
description: |
  Drafting user-facing release notes from a list of merged PRs, a git log range,
  or a changelog. Use when the user says "release notes", "what shipped this
  week", "changelog entry", "write the announcement for X", or shares a PR list.
allowed-tools:
  - Read
  - Write
  - Edit
---

# Rule: Writing release notes

## Goal

Turn a list of merged PRs into release notes a customer would actually read. The PRs say what work happened; the release notes say what changed for the user. Most release notes fail by listing the work ("Refactored billing service") instead of the change ("You can now switch plans mid-cycle without losing prorated credit"). Fix that.

## Process

1. **Receive input** — a list of merged PRs (titles + descriptions), a git log range, a draft changelog, or a Linear / Jira label.
2. **Ask clarifying questions** to set audience, tone, and grouping.
3. **Triage** — separate user-visible changes from internal work. Internal work goes in "Under the hood" or gets cut.
4. **Draft** in the structure below.
5. **Review with the user.** Revise. The first draft is usually too long.

## Clarifying Questions

Pick from these. Ask 3–4 max.

**Audience** — who reads this?
- A. End users (the people who use the product)
- B. Customers (the people who pay)
- C. Internal stakeholders
- D. Cross-team eng (other teams in the company)

**Tone** — match it to the audience and the product's voice.
- A. Plainspoken, period-ending. Like a colleague's email.
- B. Excited (real launches, big features). Use sparingly.
- C. Operational (status / fixes / maintenance).

**Length**
- 1. Headline-only (one paragraph for the changelog page)
- 2. Per-feature paragraphs (a digest email)
- 3. Full announcement (one section per feature with detail)

**Grouping**
- A. By area / surface (Billing, Dashboard, API)
- B. By impact (New, Improved, Fixed)
- C. By the named release / version

## Output Structure

```markdown
# <Release name or date>

<TL;DR — one sentence, three things max.>

## Highlights

- <Bullet — the change in one line, user-facing.>
- <Bullet>
- <Bullet>

## What's new

### <Feature name>
<One paragraph in the brand voice. Specific nouns, active verbs, what the user can now do.>

### <Next feature>
…

## Improvements

- <One-liner each, ordered by user impact.>

## Fixed

- <One-liner each. Be specific — "Fixed crash on Safari 17 when editing project name" beats "Fixed a bug".>

## Under the hood

- <Internal changes the user doesn't feel but might want to know about. Cut this section if there isn't anything.>

## Known issues

- <Things shipping with known limitations. Be honest.>
```

## Voice rules

- **List the feature, not the work.** "You can now switch plans mid-cycle" beats "Refactored the billing service".
- **Specific nouns.** "Stripe, Adyen, Braintree" beats "all major payment providers".
- **Active verbs.** "Adds", "ships", "fixes" — not "facilitates", "enables", "unlocks".
- **No marketing buzzwords.** No "unlock", "empower", "leverage", "seamless", "next-generation", "AI-powered".
- **Numbers when you have them.** "30% faster" beats "much faster".
- **One emoji per row max** if your brand allows them at all. None in headlines.
- **Period-end declarative.** No question headlines. No exclamation drama.

## Target Audience

Whoever you picked in Q1. If end users, write like a colleague explaining a change. If customers (paying), include the "why this matters for your team" thread. If internal, use the team's jargon — and skip what they already know.

## Tiny worked example

**PR list (input):**
- #842 "Refactor billing service to support mid-cycle plan changes"
- #847 "Add prorated credit calculation"
- #851 "Fix Safari 17 crash on /projects/edit"
- #855 "Bump Stripe SDK to v17"

**Output (excerpt):**
> ### Switch plans mid-cycle without losing credit
> You can now upgrade or downgrade your plan in the middle of a billing period. Any unused time on your old plan is converted to prorated credit and applied to the new one — no support ticket needed.
>
> ## Fixed
> - Editing a project name no longer crashes Safari 17.

Note what disappears: the SDK bump (irrelevant to the user) and the "refactor" framing (internal). What survives is the user-visible change with a specific verb.

## Anti-patterns

- One bullet per PR, copy-pasted from the title. PRs aren't release notes.
- "We're excited to announce…" The reader doesn't care that you're excited.
- "Multiple bug fixes and improvements". Name three of them, by impact.
- Hiding a breaking change in "Under the hood". Breaking changes get their own callout at the top.
- Release notes longer than the feature they describe. Cut by half.

## Output

- **Format:** Markdown (`.md`)
- **Location:** `tasks/release-notes/` or wherever your team keeps them.
- **Filename:** `<YYYY-MM-DD>-<release-name>.md`

## Final instructions

1. Always ask the clarifying questions first. The same PR list produces different notes for end users vs. exec audiences.
2. Read your draft aloud. If a sentence sounds like a press release, rewrite it.
3. Cut at least 30% on the second pass. Most first drafts are too long.

## Attribution

Synthesized from: `phuryn/pm-skills · release-notes` (11.6k★, MIT); voice principles from the Runtime brand skill; Aman Khan's framing of "skills encode judgment" from his Substack on [Every PM should be building skills](https://amankhan1.substack.com/p/every-pm-should-be-building-skills).

---
name: writing-stakeholder-updates
description: |
  Drafting weekly or per-meeting updates for different audiences — eng leads,
  executives, customer success, cross-team partners. Use when the user mentions
  "weekly update", "exec note", "team update", "Friday recap", "stakeholder
  email", "status report", or asks for "something to send the team".
allowed-tools:
  - Read
  - Write
  - Edit
---

# Rule: Writing stakeholder updates

## Goal

A good stakeholder update answers three things in the first 30 seconds: **what shipped, what's blocked, what I need from you.** Anything else is supporting material. The mistake most PMs make is writing the same update for every audience — exec versions read like sprint reports, eng versions read like marketing. This skill picks the right shape for the audience and resists the temptation to over-explain.

## Process

1. **Receive input** — a sprint report, a list of PRs, the team's Linear board, a transcript, or just "draft an update".
2. **Ask the audience and the time horizon.** Without those two, every other choice is wrong.
3. **Pull the three threads** — shipped, in-flight, blocked. Add risks + decisions needed.
4. **Draft** in the structure for the chosen audience.
5. **Cut by a third.** First drafts are too long.

## Clarifying Questions

**Audience** — who reads this? Pick one:
- 1. Eng leads + tech leads
- 2. Executives (VPs, founders, C-suite)
- 3. Customer success / support
- 4. Cross-team partners (other PMs, design, data)
- 5. The whole company

**Time horizon**
- A. Last week
- B. Last 2 weeks (a sprint)
- C. Last month
- D. The quarter so far

**Signal** — what's the headline?
- 1. Shipped something
- 2. Stuck and need help
- 3. Risk surfacing
- 4. Decision needed
- 5. Steady progress, no drama

**Tone**
- A. Plainspoken, period-ending (default)
- B. Formal (board-style)
- C. Conversational (slack-style)

## Output Structure — per audience

### A. Eng leads + tech leads

```markdown
**<Team / project name> — week of <date>**

**Shipped**
- <One line each. Link to PRs.>

**In flight**
- <One line. ETA if you have one.>

**Blocked / risk**
- <Specific blocker. Who can unblock and by when.>

**Decisions needed**
- <One per line, format: "Decision needed by [date]: [the question]". Tag the decider.>

**Heads up**
- <Anything else they should know but no action required.>
```

### B. Executives

```markdown
**<Team / project> — <period>**

**TL;DR.** One sentence. The thing that matters.

**Metrics**
- <Primary metric>: <current vs. target>
- <Guardrail metric>: <state>

**What moved this week**
- <2–4 bullets, each tied to a metric or a goal.>

**Risks**
- <One line per risk. Format: "Risk + mitigation + when we'll know if it's working".>

**Asks**
- <Specific. "Need <name> to approve <thing> by <date>" — not "would appreciate input".>
```

### C. Customer success / support

```markdown
**What's new for customers — <date>**

**Shipped this week**
- <Customer-visible change in one line.>

**Known issues**
- <Issue + workaround + ETA.>

**Customer-requested items**
- <Top 3 from feedback this period. Status: shipped / in flight / not on roadmap.>

**FYI**
- <Things to be aware of in customer conversations.>
```

### D. Cross-team partners

```markdown
**<Team> sync — <date>**

**What we shipped that you might care about**
- <Things with cross-team impact. Be specific about the impact.>

**What we're starting that touches your area**
- <Heads-up items. Who to talk to on our side.>

**What we need from you**
- <Direct asks. Person + thing + date.>
```

### E. Whole company

Short. Format like option B (Exec) but lighter — TL;DR + 3 bullets + asks. Slack-friendly.

## Voice rules

- **Period-end declarative.** No questions. No "thoughts?" at the end.
- **Specific names and dates.** "Need Priya's approval by Thursday" beats "need input soon".
- **Numbers over adjectives.** "Down 12% this week" beats "down significantly".
- **Active verbs.** "Shipped", "Blocked on", "Decided to" — not "facilitated", "explored".
- **Bullets are sentences, not phrases.** Two-word bullets are a coward's update.
- **No buzzwords.** No "alignment", "synergy", "leverage", "seamless".

## Risk communication

Every risk gets three lines:

1. **The risk.** "If A doesn't happen, B fails."
2. **The mitigation.** "We're doing C to reduce the chance."
3. **The trip-wire.** "We'll know if it's working by [date / signal]."

Without all three, it's not a risk — it's a worry, and exec readers will treat it as one.

## Target Audience

You picked it in Q1. Now write *only* what that audience needs. The PM error pattern is to copy-paste sections "in case it's useful". It isn't. Different audience = different doc.

## Tiny worked example

**Audience: Exec, weekly**

> **Checkout flow — week of Mar 24**
>
> **TL;DR.** Mobile checkout conversion ticked up 1.8 points after we shipped the simplified shipping selector. We're prepping a similar pass on the payment screen next week.
>
> **Metrics**
> - Mobile checkout conversion: **22.4%** (up from 20.6%, target 25% by EOQ).
> - Refund rate (guardrail): 1.1%, no change.
>
> **What moved**
> - Shipped simplified shipping selector on Tuesday (cut 3 fields to 1).
> - Cleaned up 2 prod errors on Safari that were silently failing checkout.
>
> **Risks**
> - Risk: payment-screen experiment may not show signal in 1 week if traffic dips for spring break. Mitigation: extended runway 7 days. Trip-wire: 50k sessions by Apr 7.
>
> **Asks**
> - Need legal sign-off on the 3DS copy by Friday — sent the draft to Priya yesterday.

## Anti-patterns

- The same update sent to three audiences. Pick one, write for them, send a different shape to others.
- "Things are going well" with no numbers. Pick a metric.
- A blocked-items list without dates or decision owners.
- Risks without trip-wires. They read as worry.
- Updates longer than 250 words for exec audiences. Cut.

## Output

- **Format:** Markdown (`.md`) or paste directly into Slack / email.
- **Location:** `tasks/updates/` if archived.
- **Filename:** `<YYYY-MM-DD>-<audience>.md`

## Final instructions

1. Always confirm audience and time horizon before drafting. Don't guess.
2. After drafting, count the asks. If there isn't a specific named ask, the update is a status report, not a stakeholder update.
3. Read aloud. If you wouldn't say it in a hallway conversation, rewrite it.

## Attribution

Synthesized from: `anthropics/knowledge-work-plugins · stakeholder-comms` (Apache 2.0); Ryan Nystrom (Notion EM) on async work patterns from [chatprd.ai](https://www.chatprd.ai/how-i-ai/ryan-nystrom-notion-workflows-for-engineering-velocity); Cat Wu / Anthropic team's update cadence via Lenny's; voice rules from the Runtime brand skill.

---
name: prioritizing-features
description: |
  Picking the right prioritization framework (RICE, MoSCoW, WSJF, Kano) and
  applying it to a backlog. Use when the user says "how should I prioritize",
  "score this backlog", "which framework", "what should we cut", "roadmap
  prioritization", or "RICE / MoSCoW / WSJF / Kano".
allowed-tools:
  - Read
  - Write
  - Edit
---

# Rule: Prioritizing features

## Goal

Most prioritization fails one of two ways: someone picks RICE because it's the framework they know, then spends an afternoon multiplying made-up numbers — or no framework is used and the loudest stakeholder wins. The job of this skill is to **pick the framework that fits the question being asked**, score honestly (showing the math), and recommend what to cut. The output is a defensible ordering, not a precise number.

## Process

1. **Receive input** — a backlog (any format), a strategic ask ("what do we ship next quarter?"), or a "help me decide between A and B".
2. **Ask the clarifying questions** below. The stage of work determines the framework.
3. **Recommend a framework first**, with a one-sentence why. Don't default.
4. **Score the items** transparently. Every score has an assumption next to it.
5. **Surface the sensitivity.** "If reach is off by 2x, item #4 jumps to #2." This is the most useful line in the doc.
6. **Recommend the cut.** What you'd drop, not just what you'd keep.

## Clarifying Questions

**Stage of work**
- 1. Early discovery (we don't know what to build yet)
- 2. Roadmap planning (next quarter)
- 3. Sprint backlog (next 2 weeks)
- 4. Cut list (we have too much; what goes?)

**Primary constraint**
- A. Time (a deadline is non-negotiable)
- B. Engineering capacity (people-weeks)
- C. Strategic bet (must move metric X)
- D. Customer commitment (specific accounts asked)

**How many items**
- Under 10 / 10–30 / 30+

**Confidence in the inputs**
- A. Solid (we've measured reach / effort recently)
- B. Mixed (some real numbers, some guesses)
- C. Vibes (we're guessing on all of it — say so)

## Framework picker

Use this as the recommendation table. The skill should *open* with a framework call, not assume one.

| If the question is… | Framework | Why |
|---|---|---|
| "What should we ship next quarter from this big list?" | **RICE** | Forces reach + impact + confidence onto a comparable scale. Best when items vary a lot in size. |
| "What's in scope for this release?" | **MoSCoW** | Categorical (Must / Should / Could / Won't) — fast, no false precision. |
| "Which of these will pay off soonest given fixed engineering capacity?" | **WSJF** | Cost-of-delay ÷ job size. Built for capacity-constrained roadmaps. |
| "Are we missing the basics that make customers love this?" | **Kano** | Separates table-stakes from delighters from must-haves. Use after research, not in a vacuum. |
| "Should we do A or B?" | **None — just decide.** | Two items don't need a framework. Pick the one with the bigger consequence-of-being-wrong and ship. |

## Output Structure

```markdown
# <Project / quarter> — prioritization

**Recommended framework: <name>.** <One sentence why this fits the question.>
**What changes if we change framework:** <One sentence — show you considered alternatives.>

## Inputs

- Items considered: <N>
- Source: <where they came from>
- Confidence: <A / B / C from above>

## Scored list

| # | Item | <Score components shown> | Score | Notes |
|---|---|---|---|---|
| 1 | <Item> | R 8000 · I 3 · C 0.8 · E 4 | **4800** | <One line: the key assumption.> |
| 2 | <Item> | … | … | … |

(For RICE, columns are R / I / C / E and the score = R × I × C / E. Show the math, not just the result.)
(For MoSCoW, columns are category + rationale.)
(For WSJF, columns are User-business value / Time criticality / Risk-opportunity / Job size, score = (sum of first three) / job size.)

## What I would cut

- <2–4 items from the bottom, named, with a one-line reason.> "<Item>: lowest reach, requires a new vendor relationship. Park until Q3."

## Sensitivity check

- <"If reach on item #4 is half what we estimated, it drops below the line.">
- <"If the legal review on item #2 takes 6 weeks not 2, it should slip to next quarter.">

## Recommended next step

<One paragraph. The first three items in priority order, who's the owner, when each kicks off. Specific.>

## What I'm not sure about

- <Honest list of guesses. Confidence calibration matters more than precision.>
```

## RICE quick reference

For when RICE is the chosen framework. Score each on these scales — don't invent new ones.

- **Reach (R):** Number of users / events the change touches in a chosen period (e.g. per quarter). Use a real number.
- **Impact (I):** 0.25 (minimal) · 0.5 (low) · 1 (medium) · 2 (high) · 3 (massive). Anchored — don't invent intermediate values.
- **Confidence (C):** 0.5 (low) · 0.8 (medium) · 1.0 (high). If lower than 0.5, do more research before scoring.
- **Effort (E):** Person-months (or weeks — pick one and stay consistent).
- **Score:** R × I × C / E.

The point of RICE isn't the number. It's that two PMs scoring the same item in a room together usually agree within 2x — which is good enough to order a backlog.

## WSJF quick reference

When capacity is the binding constraint:

- **Cost of Delay (CoD)** = User-business value + Time criticality + Risk reduction / Opportunity enablement.
- **WSJF score** = CoD / Job size.
- Score each component on a 1 / 2 / 3 / 5 / 8 / 13 / 20 Fibonacci scale. Higher = more.

## MoSCoW quick reference

- **Must:** the release fails without it.
- **Should:** important, but the release survives without it (with workarounds).
- **Could:** nice to have if there's time.
- **Won't:** explicitly out of this release. Document so it doesn't re-litigate.

Rule of thumb: Must items ≤ 60% of capacity. If Musts are 90% of capacity, you've called everything must, which means nothing is.

## Voice rules

- **Show the math.** A score with no decomposition is a vibe with a number bolted on.
- **State the assumption.** Every score has one — name it. "Assumes reach matches Q1 actuals."
- **Recommend a cut.** Saying yes to everything is not prioritization.
- **No precision theater.** RICE scores of 4823 vs. 4814 are noise. Round to one significant digit and move on.

## Target Audience

The reader is usually an eng lead or VP making a capacity call. They want to know *what to build first, what to drop, and why* — in that order. The framework is the supporting evidence, not the headline.

## Tiny worked example

**Backlog of 5 items, roadmap planning, mixed confidence — RICE chosen.**

| # | Item | R | I | C | E | Score | Note |
|---|---|---|---|---|---|---|---|
| 1 | SSO for enterprise tier | 800 (paying users) | 2 | 0.8 | 6 | **213** | Two largest accounts asked. Confidence high. |
| 2 | Dashboard speed pass | 12,000 (all DAU) | 1 | 0.8 | 3 | **3200** | We have measurements; this is real. |
| 3 | Mobile redesign | 8,000 | 1 | 0.5 | 12 | **333** | Confidence low — we haven't user-tested. |
| 4 | Webhook retries | 2,000 (API users) | 2 | 1.0 | 2 | **2000** | Top support ticket category. |
| 5 | Branded export themes | 400 | 0.5 | 0.8 | 4 | **40** | Nobody asked. |

> **Recommended order:** Dashboard speed → Webhooks retries → Mobile redesign (after lightweight user test) → SSO (gates two big accounts but small reach) → Cut: Branded export themes.
>
> **Sensitivity check:** If the mobile redesign's confidence ticks to 0.8 after one prototype test, it moves above SSO. Run that test before locking the quarter.

## Anti-patterns

- **Defaulting to RICE.** Pick the framework. Don't reach.
- **Scoring without a number for Reach.** "Reach: high" is not a Reach value.
- **Three-decimal precision.** RICE is for ordering, not for ranking 1st vs. 2nd by score.
- **No "cut" recommendation.** You optimized for what to keep instead of what to drop. The cut is the harder, more useful call.
- **Hidden assumptions.** A score without a note next to it is unauditable.
- **Re-litigating Won't items.** MoSCoW only works if "Won't" is enforced.

## Output

- **Format:** Markdown (`.md`)
- **Location:** `tasks/prioritization/`
- **Filename:** `<YYYY-MM-DD>-<topic>.md`

## Final instructions

1. Recommend the framework first. The framework recommendation is part of the deliverable.
2. Show the math. Every score has an assumption next to it.
3. End with the cut and the sensitivity check. Those are the lines that get used in the meeting.

## Attribution

Synthesized from: `anthropics/knowledge-work-plugins · roadmap-management` (Apache 2.0); `phuryn/pm-skills · prioritize-features` (MIT); `deanpeters/Product-Manager-Skills · prioritization-advisor` (MIT); Sean McBride's original RICE writeup at Intercom; Don Reinertsen's *Principles of Product Development Flow* (WSJF); Noriaki Kano's model; Dai Clegg's MoSCoW formulation.