Compare commits
77 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 mohitagw15856
|
01c10eb625 | ||
|
mohitagw15856
|
49137bd1b6 | ||
|
mohitagw15856
|
929fa3ad7f | ||
|
mohitagw15856
|
e366a77cf0 | ||
 mohitagw15856
|
bf65c16222 | ||
 Claude
|
beecb1cb31 | ||
|
mohitagw15856
|
8caa9c29b9 | ||
|
mohitagw15856
|
af29d30631 | ||
|
mohitagw15856
|
bfdbec17a3 | ||
|
mohitagw15856
|
48fd4dd6ad | ||
|
mohitagw15856
|
ad92de9637 | ||
|
mohitagw15856
|
450dbde74d | ||
|
mohitagw15856
|
af23bcc170 | ||
|
mohitagw15856
|
59c4510055 | ||
|
mohitagw15856
|
9274b3d378 | ||
|
mohitagw15856
|
a0ed6e52a5 | ||
|
mohitagw15856
|
84eefcabd6 | ||
|
mohitagw15856
|
7df025ffaa | ||
|
mohitagw15856
|
e5377ca61a | ||
|
mohitagw15856
|
bd38a36468 | ||
|
mohitagw15856
|
c1d47fa1ae | ||
|
mohitagw15856
|
48be8596d9 | ||
|
mohitagw15856
|
c0544fb76a | ||
|
mohitagw15856
|
ce35e8c5c0 | ||
|
mohitagw15856
|
a7ee053aac | ||
|
mohitagw15856
|
5b3eb3ea53 | ||
|
mohitagw15856
|
44d211b934 | ||
|
mohitagw15856
|
35364c7512 | ||
|
mohitagw15856
|
513e1d3ce7 | ||
|
mohitagw15856
|
d7f6c2cd05 | ||
|
mohitagw15856
|
844e97f81f | ||
|
mohitagw15856
|
b6e0cbc31b | ||
|
mohitagw15856
|
f3b9d008fe | ||
|
mohitagw15856
|
93c5ab7d71 | ||
|
mohitagw15856
|
34b0f780e6 | ||
|
mohitagw15856
|
7dbf5a47a3 | ||
|
mohitagw15856
|
f9d075ce3d | ||
|
mohitagw15856
|
81bc090869 | ||
|
mohitagw15856
|
ff46498e46 | ||
|
mohitagw15856
|
31c45072ec | ||
|
mohitagw15856
|
d650957c6a | ||
|
mohitagw15856
|
4dac8817cf | ||
|
mohitagw15856
|
6deaa51bf6 | ||
|
mohitagw15856
|
06243650b9 | ||
|
mohitagw15856
|
69a319688f | ||
|
mohitagw15856
|
254e389593 | ||
|
mohitagw15856
|
f23c3a7e10 | ||
|
mohitagw15856
|
7db88b1a2d | ||
|
mohitagw15856
|
7720d236ce | ||
|
mohitagw15856
|
14d191cda0 | ||
|
mohitagw15856
|
fd5b9daa43 | ||
|
mohitagw15856
|
adb742a187 | ||
|
mohitagw15856
|
dd33b0d416 | ||
|
mohitagw15856
|
1fafb44dc2 | ||
|
mohitagw15856
|
27d8363f28 | ||
|
mohitagw15856
|
2e17d68eaa | ||
|
mohitagw15856
|
380a1dde21 | ||
|
mohitagw15856
|
e612ba45b1 | ||
|
mohitagw15856
|
fb235be09a | ||
|
mohitagw15856
|
f9b79a48b9 | ||
|
mohitagw15856
|
7ad6ec62fa | ||
|
mohitagw15856
|
c3efe0cdef | ||
|
mohitagw15856
|
e501288bfc | ||
|
mohitagw15856
|
093d0e0061 | ||
|
mohitagw15856
|
e49327205f | ||
|
mohitagw15856
|
6af3f21689 | ||
|
mohitagw15856
|
22c9e33861 | ||
|
mohitagw15856
|
8ac9266aec | ||
|
mohitagw15856
|
05a4af1c27 | ||
|
mohitagw15856
|
e9e9f08c96 | ||
|
mohitagw15856
|
d1b06591cb | ||
|
mohitagw15856
|
6113761ecb | ||
|
mohitagw15856
|
6b42687fde | ||
|
mohitagw15856
|
4f14c7cd7c | ||
|
mohitagw15856
|
96109f1cdd | ||
|
mohitagw15856
|
cbd22b57a6 | ||
|
mohitagw15856
|
994bf95eba |
@@ -0,0 +1,196 @@
|
||||
{
|
||||
"$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
|
||||
"name": "pm-claude-skills",
|
||||
"version": "11.0.0",
|
||||
"description": "PM stands for Professional, not just Product Management. 135 Claude Skills + 4 agent templates across 23 bundles covering 16 professions — engineering, customer success, legal, finance, HR, sales, design, Figma, marketing, and more. Built by a PM, used by everyone. Building blocks for the Anthropic agent template architecture.",
|
||||
"owner": {
|
||||
"name": "Mohit Aggarwal",
|
||||
"email": "mohit15856@gmail.com"
|
||||
},
|
||||
"plugins": [
|
||||
{
|
||||
"name": "pm-essentials",
|
||||
"description": "Core PM skills: PRD Template, Meeting Notes, Stakeholder Update, User Research Synthesis, Competitive Analysis, Word Doc Tracked Changes. The essentials every PM needs first.",
|
||||
"version": "3.1.0",
|
||||
"category": "productivity",
|
||||
"source": "./plugins/pm-essentials",
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills"
|
||||
},
|
||||
{
|
||||
"name": "pm-discovery",
|
||||
"description": "Discovery & research skills: Discovery Interview Guide, Job Story Mapper, User Interview Synthesis, Assumption Mapper. Structure user research from screener to synthesis.",
|
||||
"version": "3.0.0",
|
||||
"category": "productivity",
|
||||
"source": "./plugins/pm-discovery",
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills"
|
||||
},
|
||||
{
|
||||
"name": "pm-planning",
|
||||
"description": "Planning & strategy skills: OKR Builder, Feature Prioritisation (RICE/MoSCoW/Kano/ICE), Roadmap Presentation, Pricing Strategy, RICE + Impact Matrix, Roadmap Narrative.",
|
||||
"version": "3.0.0",
|
||||
"category": "productivity",
|
||||
"source": "./plugins/pm-planning",
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills"
|
||||
},
|
||||
{
|
||||
"name": "pm-delivery",
|
||||
"description": "Sprint & delivery skills: Sprint Planning, Technical Spec, A/B Test Planner, Go-to-Market Planner, Launch Checklist, Sprint Brief, Retro Analysis, PPTX Slide Auditor.",
|
||||
"version": "3.1.0",
|
||||
"category": "productivity",
|
||||
"source": "./plugins/pm-delivery",
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills"
|
||||
},
|
||||
{
|
||||
"name": "pm-analytics",
|
||||
"description": "Data & metrics skills: Data Analysis Standard, Retention Analysis, Product Health Analysis. Structure metric deep-dives, funnel analysis, cohort studies and churn investigations.",
|
||||
"version": "3.0.0",
|
||||
"category": "productivity",
|
||||
"source": "./plugins/pm-analytics",
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills"
|
||||
},
|
||||
{
|
||||
"name": "pm-strategy",
|
||||
"description": "Strategy & stakeholder skills: Competitor Signal Tracker, Competitive Intelligence Monitor, Stakeholder Influence Mapper, Strategic Narrative Generator, Executive Update, Ambiguity Resolver.",
|
||||
"version": "3.0.0",
|
||||
"category": "productivity",
|
||||
"source": "./plugins/pm-strategy",
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills"
|
||||
},
|
||||
{
|
||||
"name": "pm-advanced",
|
||||
"description": "Advanced PM skills: AI Product Canvas, Multi-Source Signal Synthesiser, Experiment Designer, Design Handoff Brief, Stakeholder Update. For senior PMs working on complex products.",
|
||||
"version": "3.0.0",
|
||||
"category": "productivity",
|
||||
"source": "./plugins/pm-advanced",
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills"
|
||||
},
|
||||
{
|
||||
"name": "pm-rituals",
|
||||
"description": "Weekly PM ritual skill: PM Weekly Review. A 20-minute structured ritual covering metrics, shipping progress, insights, and next week's top 3 priorities.",
|
||||
"version": "3.0.0",
|
||||
"category": "productivity",
|
||||
"source": "./plugins/pm-rituals",
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills"
|
||||
},
|
||||
{
|
||||
"name": "pm-gtm",
|
||||
"description": "Marketing & GTM skills: Go-To-Market Planner, Content Calendar, Competitor Teardown, Email Campaign, SEO Content Brief, Media Pitch. Build positioning statements, messaging pillars, feature lists, use cases, launch campaigns, SEO briefs, and journalist pitches.",
|
||||
"version": "1.1.0",
|
||||
"category": "productivity",
|
||||
"source": "./plugins/pm-gtm",
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills"
|
||||
},
|
||||
{
|
||||
"name": "pm-engineering",
|
||||
"description": "Engineering & tech skills: Code Review Checklist, Incident Postmortem, API Docs Writer, Architecture Decision Record, Debugging Log Analyser, PR Description Writer, System Design Interview, Changelog Generator, Test Strategy Doc, Runbook Writer, CI/CD Playbook, SLO & Error Budget, Developer Onboarding Doc, On-Call Runbook, Security Threat Model, Performance Budget, Database Schema Design, Database Migration Plan, Technical Debt Register, RFC Writer, Capacity Planning, Load Testing Plan, Disaster Recovery Plan, Feature Flag Guide, Dependency Audit, Service Catalog Entry, Monitoring Setup Guide, Local Dev Setup, API Versioning Strategy, Infra-as-Code Review, Engineering Weekly Report, Tech Radar, Sprint Velocity Analysis, Microservices Decomposition, Engineering Hiring Rubric. 35 structured skills for engineering teams, SREs, and technical PMs.",
|
||||
"version": "4.0.0",
|
||||
"category": "productivity",
|
||||
"source": "./plugins/pm-engineering",
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills"
|
||||
},
|
||||
{
|
||||
"name": "pm-cs",
|
||||
"description": "Customer Success skills: Customer Health Scorecard, QBR Deck, Escalation Brief, Churn Analysis. Score account health with a weighted RAG framework, build structured QBR decks with value narratives, write crisp escalation briefs for at-risk accounts, and analyse churn by category and segment with prioritised interventions.",
|
||||
"version": "1.0.0",
|
||||
"category": "productivity",
|
||||
"source": "./plugins/pm-cs",
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills"
|
||||
},
|
||||
{
|
||||
"name": "pm-data",
|
||||
"description": "Data & analytics skills: Metrics Framework, SQL Query Explainer, Dashboard Brief, Chart Data Extractor. Build North Star metric trees, explain SQL, spec dashboards, and digitise chart images.",
|
||||
"version": "1.1.0",
|
||||
"category": "productivity",
|
||||
"source": "./plugins/pm-data",
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills"
|
||||
},
|
||||
{
|
||||
"name": "pm-people",
|
||||
"description": "Leadership & people skills: Performance Review, Hiring Rubric, Team Offsite Planner. Write structured reviews, build interview scorecards, and plan offsites from goals to minute-by-minute agenda.",
|
||||
"version": "1.0.0",
|
||||
"category": "productivity",
|
||||
"source": "./plugins/pm-people",
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills"
|
||||
},
|
||||
{
|
||||
"name": "pm-design",
|
||||
"description": "Design & UX skills: UX Research Plan, Design Critique, Accessibility Audit. Create research plans with discussion guides, critique designs using JTBD and Gestalt principles, audit for WCAG 2.2 compliance.",
|
||||
"version": "1.0.0",
|
||||
"category": "productivity",
|
||||
"source": "./plugins/pm-design",
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills"
|
||||
},
|
||||
{
|
||||
"name": "pm-business",
|
||||
"description": "Business & strategy skills: Investor Update, Board Deck Narrative, Job Application. Write investor updates investors actually read, structure board presentations, and tailor CVs with ATS optimisation.",
|
||||
"version": "1.0.0",
|
||||
"category": "productivity",
|
||||
"source": "./plugins/pm-business",
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills"
|
||||
},
|
||||
{
|
||||
"name": "pm-legal",
|
||||
"description": "Legal skills: Contract Review, NDA Analyser, Legal Brief, Compliance Checklist. Flag risks in contracts and NDAs, draft legal memos in IRAC format, and generate GDPR, SOC 2, FCA and other compliance checklists.",
|
||||
"version": "1.1.0",
|
||||
"category": "productivity",
|
||||
"source": "./plugins/pm-legal",
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills"
|
||||
},
|
||||
{
|
||||
"name": "pm-finance",
|
||||
"description": "Finance skills: Financial Model Narrative, Budget Variance Analysis, Investor Pitch Deck, Financial Due Diligence, Tax Planning Checklist. Turn numbers into board-ready narratives, explain variances, structure pitch decks, generate DD checklists, and review year-end tax planning opportunities.",
|
||||
"version": "1.1.0",
|
||||
"category": "productivity",
|
||||
"source": "./plugins/pm-finance",
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills"
|
||||
},
|
||||
{
|
||||
"name": "pm-hr",
|
||||
"description": "HR skills: Job Description Writer, Onboarding Plan, Employee Engagement Survey, Redundancy Consultation, Change Management Plan. Write inclusive JDs, build 30/60/90-day plans, design engagement surveys, structure redundancy processes, and manage organisational change with stakeholder analysis and adoption metrics.",
|
||||
"version": "1.1.0",
|
||||
"category": "productivity",
|
||||
"source": "./plugins/pm-hr",
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills"
|
||||
},
|
||||
{
|
||||
"name": "pm-sales",
|
||||
"description": "Sales skills: Sales Battlecard, Discovery Call Prep, Proposal Writer, Account Plan, Sales Forecasting Model. Build competitive battlecards, prepare discovery calls, write winning proposals, create account plans, and build pipeline-based revenue forecasts with scenario analysis.",
|
||||
"version": "1.1.0",
|
||||
"category": "productivity",
|
||||
"source": "./plugins/pm-sales",
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills"
|
||||
},
|
||||
{
|
||||
"name": "pm-operations",
|
||||
"description": "Operations skills: Process Documentation, SOP Writer, Vendor Evaluation, Project Status Report, Workshop Facilitation Guide. Document workflows, write audit-ready SOPs, evaluate vendors, produce RAG status reports, and design facilitated workshops with activity instructions and facilitator moves.",
|
||||
"version": "1.1.0",
|
||||
"category": "productivity",
|
||||
"source": "./plugins/pm-operations",
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills"
|
||||
},
|
||||
{
|
||||
"name": "pm-research",
|
||||
"description": "Research and healthcare skills: Clinical Case Summary, Research Protocol, Patient Communication, Literature Review. Write SBAR handovers, design research protocols, draft accessible patient communications, and structure literature reviews.",
|
||||
"version": "1.0.0",
|
||||
"category": "productivity",
|
||||
"source": "./plugins/pm-research",
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills"
|
||||
},
|
||||
{
|
||||
"name": "pm-cross",
|
||||
"description": "Cross-profession skills: Press Release, Grant Proposal, Executive Summary, Teaching Lesson Plan. Write journalist-ready press releases, structure grant applications, produce decision-ready executive summaries, and design complete lesson plans for any subject, audience, or setting.",
|
||||
"version": "1.1.0",
|
||||
"category": "productivity",
|
||||
"source": "./plugins/pm-cross",
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills"
|
||||
},
|
||||
{
|
||||
"name": "pm-figma",
|
||||
"description": "Figma skills for PMs and designers: Component Audit, Design Brief, Annotation Guide, Design Review, User Flow Planner, Variant Matrix, Spacing System, Prototype Plan, Design QA, PM Design Critique. Work smarter across the full Figma design lifecycle.",
|
||||
"version": "1.1.0",
|
||||
"category": "productivity",
|
||||
"source": "./plugins/pm-figma",
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills"
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,65 @@
|
||||
---
|
||||
name: "🐛 Bug Report"
|
||||
about: "A skill isn't triggering correctly, producing wrong output, or something else is broken"
|
||||
title: "[BUG] "
|
||||
labels: ["bug"]
|
||||
assignees: ""
|
||||
---
|
||||
|
||||
## Which skill is affected?
|
||||
|
||||
<!-- e.g. plugins/pm-gtm/skills/go-to-market -->
|
||||
|
||||
**Skill path:**
|
||||
|
||||
---
|
||||
|
||||
## What's the problem?
|
||||
|
||||
<!-- Tick all that apply -->
|
||||
|
||||
- [ ] Skill isn't triggering when it should
|
||||
- [ ] Skill is triggering when it shouldn't
|
||||
- [ ] Output is missing a section
|
||||
- [ ] Output format is wrong
|
||||
- [ ] Skill description is incorrect or misleading
|
||||
- [ ] Plugin isn't showing in the marketplace
|
||||
- [ ] Installation issue
|
||||
- [ ] Other: ___________
|
||||
|
||||
---
|
||||
|
||||
## What did you expect to happen?
|
||||
|
||||
---
|
||||
|
||||
## What actually happened?
|
||||
|
||||
<!-- Paste the output or describe what went wrong -->
|
||||
|
||||
---
|
||||
|
||||
## How to reproduce
|
||||
|
||||
<!-- Step by step:
|
||||
1. Trigger phrase used: "..."
|
||||
2. Claude Code version: ...
|
||||
3. What happened: ... -->
|
||||
|
||||
1.
|
||||
2.
|
||||
3.
|
||||
|
||||
---
|
||||
|
||||
## Environment
|
||||
|
||||
- **Claude Code version:**
|
||||
- **OS:**
|
||||
- **Install method:** marketplace / manual / symlink
|
||||
|
||||
---
|
||||
|
||||
## Any additional context?
|
||||
|
||||
<!-- Screenshots, logs, or anything else helpful -->
|
||||
@@ -0,0 +1,8 @@
|
||||
blank_issues_enabled: false
|
||||
contact_links:
|
||||
- name: 📚 Read the article series
|
||||
url: https://medium.com/product-powerhouse/claude-skills-the-ai-feature-thats-quietly-changing-how-product-managers-work-aad5d8d0640a
|
||||
about: Full background on the Claude Skills Library and how to use it
|
||||
- name: 💬 Start a Discussion
|
||||
url: https://github.com/mohitagw15856/pm-claude-skills/discussions
|
||||
about: For open-ended conversations, ideas, and community skill sharing
|
||||
@@ -0,0 +1,21 @@
|
||||
---
|
||||
name: "💬 Question or Feedback"
|
||||
about: "Ask a question about using the skills, or share feedback on the library"
|
||||
title: "[QUESTION] "
|
||||
labels: ["question"]
|
||||
assignees: ""
|
||||
---
|
||||
|
||||
## What's your question or feedback?
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
<!-- Which skill or bundle are you asking about? Any relevant details about your setup? -->
|
||||
|
||||
---
|
||||
|
||||
## What have you already tried?
|
||||
|
||||
<!-- If it's a question about getting something working — what have you attempted? -->
|
||||
@@ -0,0 +1,70 @@
|
||||
---
|
||||
name: "💡 Skill Request"
|
||||
about: "Suggest a new skill you'd like to see added to the library"
|
||||
title: "[SKILL REQUEST] "
|
||||
labels: ["skill-request"]
|
||||
assignees: ""
|
||||
---
|
||||
|
||||
## What skill are you requesting?
|
||||
|
||||
<!-- A short name for the skill, e.g. "Legal Contract Review" or "Sales Battlecard Builder" -->
|
||||
|
||||
**Skill name:**
|
||||
|
||||
---
|
||||
|
||||
## What profession or role is this for?
|
||||
|
||||
<!-- Who would use this skill day-to-day? -->
|
||||
|
||||
- [ ] Product Management
|
||||
- [ ] Marketing & GTM
|
||||
- [ ] Engineering & Tech
|
||||
- [ ] Data & Analytics
|
||||
- [ ] Leadership & People
|
||||
- [ ] Design & UX
|
||||
- [ ] Business & Strategy
|
||||
- [ ] Legal
|
||||
- [ ] Finance
|
||||
- [ ] HR
|
||||
- [ ] Sales
|
||||
- [ ] Other: ___________
|
||||
|
||||
---
|
||||
|
||||
## What workflow does this skill solve?
|
||||
|
||||
<!-- Describe the specific task or document this skill should produce.
|
||||
Be as concrete as possible — what do you do today that takes too long? -->
|
||||
|
||||
---
|
||||
|
||||
## What should the output look like?
|
||||
|
||||
<!-- What does a good output from this skill contain?
|
||||
E.g. "A structured contract review with flagged clauses, risk rating, and plain English summary" -->
|
||||
|
||||
---
|
||||
|
||||
## Example trigger phrases
|
||||
|
||||
<!-- How would you naturally ask Claude to use this skill?
|
||||
E.g. "Review this contract", "Flag the key risks in this NDA" -->
|
||||
|
||||
-
|
||||
-
|
||||
|
||||
---
|
||||
|
||||
## Are you willing to build this skill yourself?
|
||||
|
||||
- [ ] Yes — I'll raise a PR with the SKILL.md
|
||||
- [ ] Maybe — I'd like guidance first
|
||||
- [ ] No — I'm suggesting it for someone else to build
|
||||
|
||||
---
|
||||
|
||||
## Any additional context?
|
||||
|
||||
<!-- Links, examples, or anything else that would help someone build this skill -->
|
||||
@@ -0,0 +1,92 @@
|
||||
## What does this PR add or change?
|
||||
|
||||
<!-- One sentence summary -->
|
||||
|
||||
---
|
||||
|
||||
## Type of change
|
||||
|
||||
- [ ] New skill
|
||||
- [ ] Improvement to an existing skill
|
||||
- [ ] Bug fix (skill not triggering / wrong output)
|
||||
- [ ] Documentation update (README, CONTRIBUTING, etc.)
|
||||
- [ ] Marketplace / plugin config change
|
||||
- [ ] Other: ___________
|
||||
|
||||
---
|
||||
|
||||
## New skill checklist
|
||||
|
||||
<!-- If you're adding a new skill, tick all of these before requesting review.
|
||||
If this isn't a new skill PR, delete this section. -->
|
||||
|
||||
**Skill file**
|
||||
- [ ] Skill is in the correct folder: `plugins/[bundle-name]/skills/[skill-name]/SKILL.md`
|
||||
- [ ] Frontmatter includes `name` and `description` fields
|
||||
- [ ] `description` clearly states when Claude should activate this skill (trigger condition)
|
||||
- [ ] `description` clearly states what the skill produces (output description)
|
||||
|
||||
**Content quality**
|
||||
- [ ] Skill solves a real, recurring professional workflow (not a one-off task)
|
||||
- [ ] Output structure is clearly defined with sections and format
|
||||
- [ ] Required inputs are listed (what Claude should ask for if not provided)
|
||||
- [ ] Quality checks section is included
|
||||
- [ ] Example trigger phrases are included (at least 2)
|
||||
|
||||
**Safety**
|
||||
- [ ] Skill contains no prompt injection attempts or instructions to override Claude's guidelines
|
||||
- [ ] Skill does not instruct Claude to collect, store, or transmit personal data
|
||||
- [ ] Skill does not contain hardcoded credentials, API keys, or PII
|
||||
|
||||
**Testing**
|
||||
- [ ] I have tested this skill locally in Claude Code
|
||||
- [ ] The skill triggers correctly on the example trigger phrases
|
||||
- [ ] The output matches the structure defined in the SKILL.md
|
||||
|
||||
---
|
||||
|
||||
## What does this skill do?
|
||||
|
||||
<!-- 2-3 sentences. What workflow does it solve? Who is it for? -->
|
||||
|
||||
---
|
||||
|
||||
## Example output
|
||||
|
||||
<!-- Paste a real sample output from Claude when this skill was triggered, or describe what it produces.
|
||||
This is the most useful thing you can include for review. -->
|
||||
|
||||
---
|
||||
|
||||
## Which bundle does this belong in?
|
||||
|
||||
<!-- Which existing plugin bundle should this skill be added to?
|
||||
Or are you proposing a new bundle? -->
|
||||
|
||||
- [ ] pm-essentials
|
||||
- [ ] pm-discovery
|
||||
- [ ] pm-planning
|
||||
- [ ] pm-delivery
|
||||
- [ ] pm-analytics
|
||||
- [ ] pm-strategy
|
||||
- [ ] pm-advanced
|
||||
- [ ] pm-rituals
|
||||
- [ ] pm-gtm
|
||||
- [ ] pm-engineering
|
||||
- [ ] pm-data
|
||||
- [ ] pm-people
|
||||
- [ ] pm-design
|
||||
- [ ] pm-business
|
||||
- [ ] New bundle: ___________
|
||||
|
||||
---
|
||||
|
||||
## Related issue
|
||||
|
||||
<!-- If this PR addresses a skill request issue, link it here: "Closes #123" -->
|
||||
|
||||
---
|
||||
|
||||
## Anything else the reviewer should know?
|
||||
|
||||
<!-- Edge cases, limitations, or anything that might need discussion -->
|
||||
@@ -0,0 +1,39 @@
|
||||
# Code of Conduct
|
||||
|
||||
## Our Pledge
|
||||
|
||||
This is an open-source community built around sharing useful Claude Skills across professions. Everyone who contributes, raises issues, or participates in discussions is expected to make this a welcoming and constructive space.
|
||||
|
||||
We pledge to make participation in this project a harassment-free experience for everyone, regardless of age, background, disability, ethnicity, gender identity, level of experience, nationality, personal appearance, race, religion, or sexual identity.
|
||||
|
||||
## Our Standards
|
||||
|
||||
**Behaviour that helps this community thrive:**
|
||||
- Sharing skills that solve real workflows, with honest descriptions of what they do
|
||||
- Giving constructive feedback on PRs — specific, actionable, and respectful
|
||||
- Acknowledging other contributors' work
|
||||
- Being direct about limitations or gaps in a skill without being dismissive
|
||||
- Helping newcomers get their first PR merged
|
||||
|
||||
**Behaviour that is not acceptable:**
|
||||
- Harassment, personal attacks, or dismissive comments on contributions
|
||||
- Submitting skills that contain malicious instructions or prompt injection attempts
|
||||
- Spamming issues or PRs with low-effort or off-topic content
|
||||
- Claiming credit for someone else's skill file
|
||||
- Any form of discrimination
|
||||
|
||||
## Scope
|
||||
|
||||
This Code of Conduct applies to all spaces managed by this project — GitHub Issues, Pull Requests, Discussions, and any other forums linked from this repo.
|
||||
|
||||
## Reporting
|
||||
|
||||
If you experience or witness unacceptable behaviour, contact the maintainer directly at **mohit15856@gmail.com**. All reports will be reviewed and responded to promptly and confidentially.
|
||||
|
||||
## Enforcement
|
||||
|
||||
The maintainer reserves the right to remove comments, close PRs, or ban contributors who violate this Code of Conduct. Decisions will be made fairly and explained where possible.
|
||||
|
||||
## Attribution
|
||||
|
||||
This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.
|
||||
+131
-164
@@ -1,197 +1,164 @@
|
||||
# Contributing to PM Claude Skills
|
||||
# Contributing to pm-claude-skills
|
||||
|
||||
Thank you for considering contributing to PM Claude Skills! This document provides guidelines for contributing.
|
||||
Thank you for wanting to contribute. This repo grows through community submissions — every profession added makes it more useful for everyone.
|
||||
|
||||
## Ways to Contribute
|
||||
|
||||
### 1. Report Bugs 🐛
|
||||
|
||||
If you find a bug in a Skill:
|
||||
|
||||
1. Check if the issue already exists in [Issues](https://github.com/mohitagw15856/pm-claude-skills/issues)
|
||||
2. If not, create a new issue using the Bug Report template
|
||||
3. Include:
|
||||
- Which Skill has the issue
|
||||
- What you expected to happen
|
||||
- What actually happened
|
||||
- Steps to reproduce
|
||||
- Your Claude version (Pro/Team/Enterprise)
|
||||
|
||||
### 2. Request Skills 💡
|
||||
|
||||
Have an idea for a new Skill?
|
||||
|
||||
1. Check [existing issues](https://github.com/mohitagw15856/pm-claude-skills/issues?q=is%3Aissue+label%3Aenhancement) to avoid duplicates
|
||||
2. Create a new issue using the Skill Request template
|
||||
3. Describe:
|
||||
- What PM task the Skill would help with
|
||||
- How you currently do this task
|
||||
- Time you spend on it
|
||||
- Example outputs
|
||||
|
||||
### 3. Improve Documentation 📚
|
||||
|
||||
Documentation improvements are always welcome:
|
||||
|
||||
- Fix typos or unclear instructions
|
||||
- Add examples
|
||||
- Improve installation guides
|
||||
- Share your use cases
|
||||
|
||||
### 4. Submit Skills 🎁
|
||||
|
||||
Want to contribute a Skill you've created?
|
||||
|
||||
**Requirements:**
|
||||
- Skill must be PM-related
|
||||
- Include complete SKILL.md with proper frontmatter
|
||||
- Provide examples of outputs
|
||||
- Must be tested and working
|
||||
- Include documentation
|
||||
|
||||
**Process:**
|
||||
1. Fork the repository
|
||||
2. Create a new branch: `git checkout -b skill/your-skill-name`
|
||||
3. Add your Skill to `skills/your-skill-name/`
|
||||
4. Update main README.md to list your Skill
|
||||
5. Submit a Pull Request
|
||||
|
||||
### 5. Improve Existing Skills 🔧
|
||||
|
||||
Found a way to make a Skill better?
|
||||
|
||||
1. Fork the repository
|
||||
2. Make your improvements
|
||||
3. Test thoroughly
|
||||
4. Submit a Pull Request with:
|
||||
- Clear description of changes
|
||||
- Why the change improves the Skill
|
||||
- Before/after examples if applicable
|
||||
|
||||
## Skill Contribution Guidelines
|
||||
|
||||
### Structure
|
||||
|
||||
Every Skill must follow this structure:
|
||||
|
||||
```
|
||||
skill-name/
|
||||
├── SKILL.md (required)
|
||||
└── [other resources as needed]
|
||||
```
|
||||
|
||||
### SKILL.md Format
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: skill-name
|
||||
description: Clear description of what the skill does and when to use it. This is critical - Claude uses this to decide when to trigger the skill.
|
||||
---
|
||||
|
||||
# Skill Name
|
||||
## What We're Looking For
|
||||
|
||||
[Detailed instructions for using the skill]
|
||||
Good skills have three things in common:
|
||||
|
||||
## Structure/Template
|
||||
1. **They solve a recurring workflow** — not a one-off task. If you do this thing more than once a week and it follows a consistent structure, it's probably a good skill candidate.
|
||||
2. **They have a clear trigger** — Claude needs to know when to activate the skill. The `description` in your frontmatter is what Claude reads to decide if your skill is relevant. Make it specific.
|
||||
3. **They produce structured, useful output** — the output should be something you'd actually use at work, not a generic response.
|
||||
|
||||
[The format/structure the skill should follow]
|
||||
---
|
||||
|
||||
## Guidelines
|
||||
## How to Submit a Skill
|
||||
|
||||
[Best practices and tips]
|
||||
### Step 1: Fork the repo
|
||||
|
||||
## Examples
|
||||
Click **Fork** in the top right of the GitHub repo. This creates your own copy.
|
||||
|
||||
[Example outputs]
|
||||
```
|
||||
### Step 2: Clone your fork
|
||||
|
||||
### Quality Standards
|
||||
git clone https://github.com/YOUR_USERNAME/pm-claude-skills.git
|
||||
cd pm-claude-skills
|
||||
|
||||
Skills should:
|
||||
- ✅ Be well-documented and clear
|
||||
- ✅ Include concrete examples
|
||||
- ✅ Follow PM best practices
|
||||
- ✅ Save meaningful time (not trivial tasks)
|
||||
- ✅ Be tested and working
|
||||
- ✅ Be general enough for others to use
|
||||
- ❌ Not include proprietary company information
|
||||
- ❌ Not require external tools (unless clearly documented)
|
||||
|
||||
## Pull Request Process
|
||||
### Step 3: Create your skill folder
|
||||
|
||||
1. **Fork & Branch**
|
||||
```bash
|
||||
git clone https://github.com/mohitagw15856/pm-claude-skills.git
|
||||
cd pm-claude-skills
|
||||
git checkout -b feature/your-feature-name
|
||||
```
|
||||
Skills live in the `skills/` directory. Create a folder named after your skill using lowercase and hyphens:
|
||||
|
||||
2. **Make Changes**
|
||||
- Follow existing code style
|
||||
- Update documentation
|
||||
- Add examples
|
||||
mkdir skills/your-skill-name
|
||||
|
||||
3. **Test**
|
||||
- Test the Skill in Claude
|
||||
- Verify it works as expected
|
||||
- Check for edge cases
|
||||
|
||||
4. **Commit**
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "Add: Brief description of changes"
|
||||
```
|
||||
**Naming rules:**
|
||||
- Lowercase only
|
||||
- Hyphens between words (no underscores, no spaces)
|
||||
- Descriptive but concise: `legal-contract-review` not `skill-for-reviewing-legal-contracts`
|
||||
|
||||
5. **Push & Create PR**
|
||||
```bash
|
||||
git push origin feature/your-feature-name
|
||||
```
|
||||
Then create a Pull Request on GitHub
|
||||
### Step 4: Create your SKILL.md
|
||||
|
||||
6. **PR Description Should Include:**
|
||||
- What changes you made
|
||||
- Why you made them
|
||||
- How to test them
|
||||
- Screenshots/examples (if applicable)
|
||||
Every skill needs exactly one file: `SKILL.md` (uppercase, `.md` extension).
|
||||
|
||||
## Code of Conduct
|
||||
**Minimum required structure:**
|
||||
|
||||
### Our Standards
|
||||
---
|
||||
name: your-skill-name
|
||||
description: "One sentence. Use when [trigger condition]. Produces [output description]."
|
||||
---
|
||||
|
||||
- Be respectful and inclusive
|
||||
- Welcome newcomers
|
||||
- Accept constructive criticism
|
||||
- Focus on what's best for the community
|
||||
- Show empathy towards others
|
||||
# Skill Title
|
||||
|
||||
### Unacceptable Behavior
|
||||
[Your skill instructions here]
|
||||
|
||||
- Harassment or discriminatory language
|
||||
- Trolling or insulting comments
|
||||
- Personal or political attacks
|
||||
- Publishing private information
|
||||
- Unprofessional conduct
|
||||
|
||||
### Enforcement
|
||||
**The description field is the most important part.** It's what Claude reads (~100 tokens) to decide if your skill is relevant. Write it like this:
|
||||
|
||||
Violations may result in:
|
||||
1. Warning
|
||||
2. Temporary ban
|
||||
3. Permanent ban
|
||||
✅ Good: `"Write structured incident postmortems. Use when asked for a postmortem, RCA, incident report, or P1/P2 review. Produces a blameless postmortem with timeline, root cause, impact, and action items."`
|
||||
|
||||
Report violations to: [mohit15856@gmail.com]
|
||||
❌ Too vague: `"Helps with incident reports."`
|
||||
|
||||
**Full recommended structure for a quality skill:**
|
||||
|
||||
---
|
||||
name: your-skill-name
|
||||
description: "..."
|
||||
---
|
||||
|
||||
# Skill Title
|
||||
|
||||
Brief description of what this skill does.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
What Claude should ask for if the user doesn't provide it.
|
||||
|
||||
## Output Structure
|
||||
|
||||
The exact format and sections Claude should produce.
|
||||
|
||||
## Quality Checks
|
||||
|
||||
A checklist Claude runs before delivering output.
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Example phrase that would activate this skill"
|
||||
- "Another example"
|
||||
|
||||
|
||||
### Step 5: Test your skill locally
|
||||
|
||||
Before submitting:
|
||||
|
||||
1. Copy your skill folder to `~/.claude/skills/`
|
||||
2. Open Claude Code
|
||||
3. Try your example trigger phrases
|
||||
4. Verify the output matches what your SKILL.md describes
|
||||
5. Adjust and refine until it's working well
|
||||
|
||||
### Step 6: Commit and push
|
||||
|
||||
git add skills/your-skill-name/SKILL.md
|
||||
git commit -m "feat: add [skill-name] skill for [profession/use case]"
|
||||
git push origin main
|
||||
|
||||
|
||||
### Step 7: Open a Pull Request
|
||||
|
||||
Go to your fork on GitHub and click **"Compare & pull request"**.
|
||||
|
||||
In your PR description, include:
|
||||
- **What the skill does** (1–2 sentences)
|
||||
- **Who it's for** (profession or role)
|
||||
- **Why you built it** (what workflow pain does it solve?)
|
||||
- **Example output** (paste a sample or screenshot — helps with review)
|
||||
|
||||
---
|
||||
|
||||
## Review Process
|
||||
|
||||
- PRs are reviewed weekly (usually Fridays)
|
||||
- Feedback will be left as PR comments — usually requesting a description improvement or output structure refinement
|
||||
- Once approved, your skill is merged and added to the README
|
||||
- Your GitHub handle is added to the Contributors section
|
||||
|
||||
---
|
||||
|
||||
## What Gets Rejected
|
||||
|
||||
- Skills with vague descriptions that would trigger on too many unrelated tasks
|
||||
- Skills that just wrap a single simple prompt (a skill should have structure and logic)
|
||||
- Duplicate skills — check the existing skills list before submitting
|
||||
- Skills that require external API keys or services not everyone has access to (unless clearly documented)
|
||||
|
||||
---
|
||||
|
||||
## Skills Wishlist
|
||||
|
||||
These have been requested but not yet built. Pick one up if you have the expertise:
|
||||
|
||||
| Skill | Use case |
|
||||
|---|---|
|
||||
| `legal-contract-review` | Flag key clauses and risks in contracts |
|
||||
| `financial-model-narrative` | Turn spreadsheet outputs into board-ready narrative |
|
||||
| `hr-job-description` | Write inclusive, structured JDs from a role brief |
|
||||
| `onboarding-plan` | 30/60/90-day plan for new hires |
|
||||
| `press-release` | Structured press releases from product announcements |
|
||||
| `seo-content-brief` | Content briefs with keyword strategy and outline |
|
||||
| `grant-proposal` | Structure grant applications for nonprofits and researchers |
|
||||
| `sales-battlecard` | Competitive battlecards for sales teams |
|
||||
|
||||
Suggest a new skill: [Open an issue](../../issues/new) with the label `skill-request`.
|
||||
|
||||
---
|
||||
|
||||
## Questions?
|
||||
|
||||
- 💬 Start a [Discussion](https://github.com/mohitagw15856/pm-claude-skills/discussions)
|
||||
- ✉️ Email: [mohit15856@gmail.com]
|
||||
- 🐦 Twitter: [@yourhandle]
|
||||
Open a [Discussion](../../discussions) or raise an [Issue](../../issues). Happy to help you get a skill PR-ready.
|
||||
|
||||
## Recognition
|
||||
---
|
||||
|
||||
Contributors will be:
|
||||
- Listed in the project README
|
||||
- Credited in the Skill they contributed
|
||||
- Mentioned in release notes
|
||||
|
||||
Thank you for contributing! 🙏
|
||||
*Thank you for contributing. Every skill added here saves someone an hour they'd rather spend on something else.*
|
||||
|
||||
+1
-2
@@ -40,10 +40,9 @@ Get your first PM Skill working in 5 minutes.
|
||||
|
||||
Start a new conversation and try:
|
||||
|
||||
```
|
||||
Help me write a PRD for a mobile app feature
|
||||
that lets users save articles for later reading
|
||||
```
|
||||
|
||||
|
||||
Claude should automatically use the PRD Template Skill and create a structured PRD.
|
||||
|
||||
|
||||
@@ -1,266 +1,677 @@
|
||||
# Product Management Claude Skills
|
||||
# 🧠 PM Claude Skills — 135 Skills for Every Profession
|
||||
|
||||
**Transform your PM workflow with specialized Claude Skills for common product management tasks.**
|
||||
[](https://github.com/mohitagw15856/pm-claude-skills/stargazers)
|
||||
[](https://github.com/mohitagw15856/pm-claude-skills)
|
||||
[](https://github.com/mohitagw15856/pm-claude-skills/releases)
|
||||
[](https://github.com/mohitagw15856/pm-claude-skills#-quick-install-2-minutes)
|
||||
[](LICENSE)
|
||||
[](https://github.com/sponsors/mohitagw15856)
|
||||
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
[](https://github.com/mohitagw15856/pm-claude-skills/stargazers)
|
||||
> **PM stands for Professional, not just Product Management.**
|
||||
> 135 Claude Skills + 4 agent templates across 16 professions. Built by a PM, used by everyone.
|
||||
|
||||
A community-built library of Claude Skills for professionals across every field — product management, engineering, customer success, marketing, design, legal, finance, HR, sales, operations, research, and more. Each skill is a structured SKILL.md file that teaches Claude how to produce professional-grade outputs for your specific workflows.
|
||||
|
||||
> 📖 **Background**: Built across a four-part Medium series:
|
||||
> - [Part 1 — How Skills changed my PM workflow](https://medium.com/product-powerhouse/claude-skills-the-ai-feature-thats-quietly-changing-how-product-managers-work-aad5d8d0640a)
|
||||
> - [Part 2 — The complete 12-skill toolkit](https://medium.com/@mohit15856/12-claude-skills-for-product-managers-the-complete-toolkit-with-skill-files-for-jira-figma-fcc73a4c1e58)
|
||||
> - [Part 3 — Building Skills the right way (official guide)](https://medium.com/@mohit15856/claude-skills-advanced-guide-what-3-months-of-daily-pm-use-actually-taught-me-18324d6ef7bc)
|
||||
> - [Part 4 — Advanced skills based on what top companies want](https://medium.com/product-powerhouse/claude-skills-the-ai-feature-thats-quietly-changing-how-product-managers-work-aad5d8d0640a)
|
||||
>
|
||||
> Product Management Skills for Claude AI — 18 skills across the full PM lifecycle. Save 10+ hours per week.
|
||||
**🆕 Latest release (v11.0.0):** The full 500-star milestone is now complete — 21 remaining engineering skills shipped. pm-engineering is now the largest bundle in the library with 35 skills. 135 skills across 16 professions.
|
||||
---
|
||||
|
||||
## 🚀 Quick Install (2 minutes)
|
||||
|
||||
## What Are These Skills?
|
||||
In Claude Code, run:
|
||||
|
||||
Claude Skills are reusable, specialized procedures that teach Claude your exact workflows. Instead of re-explaining your PRD format or meeting notes structure every time, you create a Skill once and Claude automatically applies it whenever relevant.
|
||||
/plugin marketplace add mohitagw15856/pm-claude-skills
|
||||
|
||||
Think of Skills as "onboarding guides" for Claude—they package your best practices, templates, and processes so Claude consistently delivers outputs the way you want them.
|
||||
Or install by profession:
|
||||
|
||||
## 🎯 Who Is This For?
|
||||
claude plugin install pm-essentials@pm-claude-skills # Core PM + Word tracked changes
|
||||
|
||||
- **Product Managers** looking to automate repetitive documentation tasks
|
||||
- **PM Teams** wanting to standardize processes and share best practices
|
||||
- **Anyone** tired of reformatting Claude's outputs to match their standards
|
||||
claude plugin install pm-delivery@pm-claude-skills # Delivery + PowerPoint auditor
|
||||
|
||||
## ⚡ Quick Start (5 Minutes)
|
||||
claude plugin install pm-engineering@pm-claude-skills # Engineering (35 skills) 🆕
|
||||
|
||||
1. **Prerequisites**: You need Claude Pro, Team, or Enterprise account
|
||||
2. **Enable Code Execution**: Settings → Features → Enable "Code Execution and File Creation"
|
||||
3. **Install Your First Skill**:
|
||||
- Download the [`prd-template`](skills/prd-template) folder
|
||||
- Zip the folder (it should contain SKILL.md and any other files)
|
||||
- Rename the .zip to .skill (e.g., `prd-template.skill`)
|
||||
- Go to claude.ai → Settings → Skills → Upload Skill
|
||||
- Try it: "Help me write a PRD for a mobile app onboarding feature"
|
||||
claude plugin install pm-cs@pm-claude-skills # Customer Success 🆕
|
||||
|
||||
That's it! Claude now knows your PRD format.
|
||||
claude plugin install pm-data@pm-claude-skills # Data + chart data extractor
|
||||
|
||||
## 📦 Available Skills
|
||||
claude plugin install pm-legal@pm-claude-skills # Legal
|
||||
|
||||
### Free Essential Skills (Included)
|
||||
claude plugin install pm-finance@pm-claude-skills # Finance
|
||||
|
||||
| Skill | Purpose | Time Saved | Folder |
|
||||
|-------|---------|------------|--------|
|
||||
| **PRD Template** | Standardized product requirements | 2-3 hrs/PRD | [View](skills/prd-template) |
|
||||
| **Meeting Notes** | Structured meeting documentation | 15-30 min/meeting | [View](skills/meeting-notes) |
|
||||
| **Stakeholder Update** | Executive status updates | 30-45 min/update | [View](skills/stakeholder-update) |
|
||||
| **User Research Synthesis** | Analyze and synthesize research findings | 2-3 hrs/study | [View](skills/user-research-synthesis) |
|
||||
| **Competitive Analysis** | Structured competitive assessments | 1-2 hrs/analysis | [View](skills/competitive-analysis) |
|
||||
claude plugin install pm-hr@pm-claude-skills # HR
|
||||
|
||||
### Discovery & User Research
|
||||
| **User Interview Synthesis** | Synthesise transcripts into structured findings | Notion | [View](skills/user-interview-synthesis) |
|
||||
| **Assumption Mapper** | Risk-rate hidden assumptions in any PRD | Miro | [View](skills/assumption-mapper) |
|
||||
claude plugin install pm-sales@pm-claude-skills # Sales
|
||||
|
||||
### Roadmapping & Prioritisation
|
||||
| Skill | Purpose | Tool | Folder |
|
||||
|-------|---------|------|--------|
|
||||
| **RICE Prioritisation** | Score and rank initiatives objectively | Jira | [View](skills/rice-prioritisation) |
|
||||
| **Roadmap Narrative** | Turn ranked lists into strategic narratives | Notion, Miro | [View](skills/roadmap-narrative) |
|
||||
| **RICE + Impact Matrix** | RICE scoring + strategic alignment combined | Miro, Jira | [View](skills/rice-impact-matrix) |
|
||||
claude plugin install pm-operations@pm-claude-skills # Operations
|
||||
|
||||
### Sprint & Delivery
|
||||
| Skill | Purpose | Tool | Folder |
|
||||
|-------|---------|------|--------|
|
||||
| **Sprint Brief** | Generate sprint briefs from Jira data | Jira, Slack | [View](skills/sprint-brief) |
|
||||
| **Retro Analysis** | Data-grounded retrospective briefs | Jira, Miro | [View](skills/retro-analysis) |
|
||||
claude plugin install pm-research@pm-claude-skills # Research & Healthcare
|
||||
|
||||
### Data & Metrics
|
||||
| Skill | Purpose | Tool | Folder |
|
||||
|-------|---------|------|--------|
|
||||
| **Product Health Analysis** | Interpret metrics and surface signals | Analytics | [View](skills/product-health-analysis) |
|
||||
claude plugin install pm-cross@pm-claude-skills # Cross-profession
|
||||
|
||||
### Strategy & Competitive Intel
|
||||
| Skill | Purpose | Tool | Folder |
|
||||
|-------|---------|------|--------|
|
||||
| **Competitor Signal Tracker** | Analyse competitor moves strategically | Notion | [View](skills/competitor-signal-tracker) |
|
||||
claude plugin install pm-figma@pm-claude-skills # Figma
|
||||
|
||||
### Stakeholder Communication
|
||||
| Skill | Purpose | Tool | Folder |
|
||||
|-------|---------|------|--------|
|
||||
| **PRD Template** | Standardized product requirements | — | [View](skills/prd-template) |
|
||||
| **Meeting Notes** | Structured meeting documentation | — | [View](skills/meeting-notes) |
|
||||
| **Stakeholder Update** | Executive status updates | — | [View](skills/stakeholder-update) |
|
||||
| **Executive Update** | Sharp executive briefings | Slack, Teams | [View](skills/executive-update) |
|
||||
|
||||
### Go-to-Market & Launch
|
||||
| Skill | Purpose | Tool | Folder |
|
||||
|-------|---------|------|--------|
|
||||
| **Launch Readiness** | Pre-launch go/no-go assessment | Notion, Jira, Slack | [View](skills/launch-readiness) |
|
||||
Or clone and symlink for auto-updates:
|
||||
|
||||
### Cross-functional Collaboration
|
||||
| Skill | Purpose | Tool | Folder |
|
||||
|-------|---------|------|--------|
|
||||
| **User Research Synthesis** | Analyze and synthesize research findings | Notion | [View](skills/user-research-synthesis) |
|
||||
| **Competitive Analysis** | Structured competitive assessments | — | [View](skills/competitive-analysis) |
|
||||
| **Design Handoff Brief** | PM-to-designer structured briefs | Figma, Notion | [View](skills/design-handoff-brief) |
|
||||
|
||||
### 🧠 Advanced Skills (Part 4 — Role-Based Capabilities)
|
||||
| Skill | Purpose | Tool | Folder |
|
||||
|-------|---------|------|--------|
|
||||
| **Competitive Intelligence Monitor** | Weekly diff-based competitor tracking | Notion, OpenClaw | [View](skills/competitive-intelligence-monitor) |
|
||||
| **Experiment Designer** | A/B test design + results interpretation | Analytics | [View](skills/experiment-designer) |
|
||||
| **Stakeholder Influence Mapper** | Influence strategy + tailored talking points | Slack | [View](skills/stakeholder-influence-mapper) |
|
||||
| **Ambiguity Resolver** | Structures vague briefs into actionable problem statements | Notion | [View](skills/ambiguity-resolver) |
|
||||
| **Multi-Source Signal Synthesiser** | Reconciles user signals across all research channels | Notion, OpenClaw | [View](skills/multi-source-signal-synthesiser) |
|
||||
| **Strategic Narrative Generator** | Roadmap-to-strategy storytelling for executives | Notion | [View](skills/strategic-narrative-generator) |
|
||||
|
||||
|
||||
|
||||
Want a specific Skill? [Request it here](https://github.com/mohitagw15856/pm-claude-skills/issues/new?template=skill-request.md)
|
||||
|
||||
## 💡 Real Results
|
||||
|
||||
> "These Skills have become indispensable. I used to spend 3-4 hours every Friday on stakeholder updates. Now it takes 20 minutes to compile everything and let Claude format it. Game-changer."
|
||||
> — **Mohit Aggarwal, Senior PM**
|
||||
|
||||
**Time savings per week:**
|
||||
- PRD creation: -2.5 hours
|
||||
- Meeting notes: -1.5 hours
|
||||
- Stakeholder updates: -2.0 hours
|
||||
- Research synthesis: -2.5 hours
|
||||
- **Total: ~8-9 hours/week back in your schedule**
|
||||
|
||||
## 📚 Documentation
|
||||
|
||||
- [Installation Guide](docs/installation.md) - Step-by-step setup
|
||||
- [Customization Guide](docs/customization.md) - Adapt Skills to your workflow
|
||||
- [Troubleshooting](docs/troubleshooting.md) - Common issues and fixes
|
||||
- [Creating Your Own Skills](docs/creating-skills.md) - Build custom Skills
|
||||
|
||||
## 🛠️ Installation
|
||||
|
||||
### Method 1: Download Individual Skills (Easiest)
|
||||
|
||||
1. Navigate to the skill folder (e.g., `skills/prd-template`)
|
||||
2. Download all files in that folder
|
||||
3. Create a zip file containing those files
|
||||
4. Rename from `.zip` to `.skill`
|
||||
5. Upload to Claude via Settings → Skills
|
||||
|
||||
### Method 2: Clone the Repo
|
||||
|
||||
bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/mohitagw15856/pm-claude-skills.git
|
||||
cd pm-claude-skills
|
||||
|
||||
# Package a skill (creates .skill file)
|
||||
cd skills/prd-template
|
||||
zip -r ../../prd-template.skill .
|
||||
cd ../..
|
||||
|
||||
# Now upload prd-template.skill to Claude
|
||||
|
||||
|
||||
### Method 3: Direct Download (When Available)
|
||||
|
||||
Check the [Releases](https://github.com/mohitagw15856/pm-claude-skills/releases) page for pre-packaged `.skill` files.
|
||||
|
||||
## 🎓 How to Use
|
||||
|
||||
1. **Upload a Skill**: Follow installation instructions above
|
||||
2. **Just ask Claude**: Claude will automatically recognize when to use the Skill
|
||||
- "Help me write a PRD for X"
|
||||
- "Take notes from this meeting transcript"
|
||||
- "Create a competitive analysis of X, Y, Z"
|
||||
3. **No special commands needed**: Skills activate automatically based on context
|
||||
|
||||
## 🔧 Customization
|
||||
|
||||
Every company has different formats and processes. These Skills are designed to be customized:
|
||||
|
||||
1. Download the Skill folder
|
||||
2. Edit the `SKILL.md` file to match your standards
|
||||
3. Add your company's examples to the instructions
|
||||
4. Re-package and upload
|
||||
|
||||
See the [Customization Guide](docs/customization.md) for detailed instructions.
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
Found a bug? Want to suggest an improvement? Contributions are welcome!
|
||||
|
||||
- 🐛 [Report an Issue](https://github.com/mohitagw15856/pm-claude-skills/issues/new?template=bug-report.md)
|
||||
- 💡 [Request a Skill](https://github.com/mohitagw15856/pm-claude-skills/issues/new?template=skill-request.md)
|
||||
- 🔀 [Submit a Pull Request](https://github.com/mohitagw15856/pm-claude-skills/pulls)
|
||||
- 💬 [Join Discussions](https://github.com/mohitagw15856/pm-claude-skills/discussions)
|
||||
|
||||
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
|
||||
|
||||
## ⭐ Show Your Support
|
||||
|
||||
If these Skills save you time, please:
|
||||
1. ⭐ Star this repository
|
||||
2. 📢 Share with fellow PMs
|
||||
3. 🐛 Report bugs or suggest improvements
|
||||
4. ✍️ Write about your experience
|
||||
|
||||
## 📈 Roadmap
|
||||
|
||||
**Q1 2026:**
|
||||
- [ ] Add Data Analysis Standard Skill
|
||||
- [ ] Add Roadmap Presentation Skill
|
||||
- [ ] Create video tutorials
|
||||
- [ ] Pre-packaged .skill files in Releases
|
||||
|
||||
**Q2 2026:**
|
||||
- [ ] Domain-specific Skills (SaaS PM, B2B PM, Growth PM)
|
||||
- [ ] Team collaboration Skills
|
||||
- [ ] Notion/Confluence template packs
|
||||
|
||||
**Long-term:**
|
||||
- [ ] Interactive Skill builder tool
|
||||
- [ ] Integration examples with PM tools
|
||||
- [ ] Community-contributed Skills library
|
||||
|
||||
## 📄 License
|
||||
|
||||
This project is licensed under the MIT License - see [LICENSE](LICENSE) for details.
|
||||
|
||||
You're free to use, modify, and distribute these Skills. Attribution appreciated but not required.
|
||||
|
||||
## 🙋 FAQ
|
||||
|
||||
**Q: Do I need a paid Claude account?**
|
||||
A: Yes, Skills require Claude Pro, Team, or Enterprise.
|
||||
|
||||
**Q: Can I customize these Skills for my team?**
|
||||
A: Absolutely! See our [Customization Guide](docs/customization.md).
|
||||
|
||||
**Q: Do Skills work with the Claude API?**
|
||||
A: Yes! Skills work in claude.ai, Claude Code, and via the API.
|
||||
|
||||
**Q: What if a Skill doesn't work?**
|
||||
A: Check [Troubleshooting](docs/troubleshooting.md) or [open an issue](https://github.com/mohitagw15856/pm-claude-skills/issues).
|
||||
|
||||
**Q: How do I create my own Skills?**
|
||||
A: See [Creating Your Own Skills](docs/creating-skills.md) for a complete guide.
|
||||
|
||||
**Q: Can I use these commercially?**
|
||||
A: Yes! MIT license allows commercial use.
|
||||
|
||||
## 🔗 Links
|
||||
|
||||
- 📝 [Original Medium Article](https://medium.com/product-powerhouse/claude-skills-the-ai-feature-thats-quietly-changing-how-product-managers-work-aad5d8d0640a)
|
||||
- 💼 [Connect on LinkedIn](www.linkedin.com/in/mohitaggarwal4)
|
||||
- ✉️ [Email me](mailto:mohit15856@gmail.com)
|
||||
- Writing these up and refining them took a fair few evenings. If they saved you some time, a [coffee](https://buymeacoffee.com/mohit15856) is always appreciated
|
||||
|
||||
## 🙏 Acknowledgments
|
||||
|
||||
Thank you to everyone who read and shared my Medium article, and to the Anthropic team for building such a powerful feature.
|
||||
|
||||
Special thanks to the early testers who provided feedback on these Skills.
|
||||
git clone https://github.com/mohitagw15856/pm-claude-skills.git ~/pm-claude-skills
|
||||
mkdir -p ~/.claude/skills
|
||||
ln -s ~/pm-claude-skills/skills/* ~/.claude/skills/
|
||||
|
||||
---
|
||||
|
||||
**Made with ☕ by [Mohit Aggarwal](https://mohit-pm.netlify.app/)**
|
||||
## 🎬 See It in Action
|
||||
|
||||
*Helping product managers work smarter with AI*
|
||||
**Debugging Log Analyser** — paste a stack trace or error log, get a structured root cause diagnosis with probable cause, affected code path, a specific fix, and next debugging steps.
|
||||
|
||||
⭐ **Star this repo to get updates as new Skills are added!**
|
||||
**PR Description Writer** — share your diff or commit list, get a reviewer-friendly PR description with summary, changes made, testing steps, and reviewer notes.
|
||||
|
||||
**Sprint Planning Skill** — paste your sprint goals and backlog items, get a complete structured sprint plan with capacity, commitments, risks, and a day-one kickoff agenda.
|
||||
|
||||
> 📹 Drop a demo in [Discussions](../../discussions) and we'll feature it here.
|
||||
|
||||
---
|
||||
|
||||
## 🤖 Building Blocks for Agent Templates
|
||||
|
||||
On May 5, 2026, Anthropic [released their first agent templates](https://www.anthropic.com/news/finance-agents) — pre-packaged Claude agents that combine **skills, connectors, and subagents** into ready-to-run workflows for financial services.
|
||||
|
||||
This library is the largest open-source collection of professional skills available — covering 15 professions beyond financial services. **The 106 skills here are the building blocks for agent templates outside of finance.**
|
||||
|
||||
### What is an agent template?
|
||||
|
||||
An agent template packages three things into one runnable workflow:
|
||||
|
||||
| Component | What it is | Example from this library |
|
||||
|---|---|---|
|
||||
| **Skills** | Markdown files that teach Claude how to produce structured professional outputs | `sprint-planning`, `contract-review`, `investor-update` |
|
||||
| **Connectors** | Governed access to your team's data sources | Linear, Jira, Slack, Google Drive, Notion |
|
||||
| **Subagents** | Focused Claude models for sub-tasks within the larger workflow | Capacity analyst, risk scorer, comparables selector |
|
||||
|
||||
A skill alone gives Claude a structured output format. An agent template gives Claude a complete workflow — pulling data, running specialised analysis, producing the output, and routing it where it needs to go.
|
||||
|
||||
### How to use this library to build your own agent template
|
||||
|
||||
Pick a recurring workflow on your team. Identify which existing skills cover the structured outputs that workflow needs. Add the connectors that let Claude reach the data. Add subagents for the analytical sub-tasks. That's the template.
|
||||
|
||||
Examples of agent templates this library supports:
|
||||
|
||||
| Template | Skills used | Connectors needed | Subagents |
|
||||
|---|---|---|---|
|
||||
| **PM Sprint Agent** | sprint-planning, sprint-brief, retro, project-status-report | Linear or Jira, Slack | Capacity analyst, risk scorer |
|
||||
| **Legal Contract Review Agent** | contract-review, nda-analyser, compliance-checklist | Google Drive or SharePoint | Clause-by-clause risk scorer |
|
||||
| **PM Discovery Agent** | discovery-interview-guide, user-interview-synthesis, assumption-mapper | Granola or Otter, Notion | Theme synthesiser |
|
||||
| **Sales Pursuit Agent** | sales-battlecard, discovery-call-prep, proposal-writer, account-plan | Salesforce or HubSpot, Gong | Competitive intel analyst |
|
||||
| **HR Onboarding Agent** | onboarding-plan, job-description-writer, change-management-plan | Workday or BambooHR, Slack | First-week scheduler |
|
||||
| **Finance Board Pack Agent** | investor-update, board-deck-narrative, financial-model-narrative | NetSuite or Xero, Google Drive | KPI variance analyst |
|
||||
| **Marketing Launch Agent** | go-to-market, content-calendar, email-campaign, media-pitch | HubSpot, Notion | Channel strategist |
|
||||
|
||||
|
||||
### Available agent templates
|
||||
|
||||
The pm-claude-skills library now includes four working agent templates, each built from existing skills in this library combined with subagents and connectors. All four follow the architecture Anthropic introduced for [financial services agent templates](https://www.anthropic.com/news/finance-agents) on May 5, 2026.
|
||||
|
||||
| Template | What it does | Skills used | Connectors | Time saved |
|
||||
|---|---|---|---|---|
|
||||
| **[PM Sprint Agent](./templates/pm-sprint-agent/)** | End-to-end sprint planning — pulls backlog, calculates capacity, drafts plan, scores risks | sprint-planning, sprint-brief | Linear, Jira | 90 min → 90 sec |
|
||||
| **[PM Discovery Agent](./templates/pm-discovery-agent/)** | Customer discovery synthesis — reads interview notes, finds themes, scores assumption confidence | user-interview-synthesis, job-story-mapper | Notion, Google Drive | 1 day → 5 min |
|
||||
| **[PM Stakeholder Comms Agent](./templates/pm-stakeholder-comms-agent/)** | Audience-tailored stakeholder updates — exec, investor, cross-functional, or board | executive-update, investor-update, stakeholder-update, board-deck-narrative | Linear, Jira, Google Drive | 90 min → 1 min |
|
||||
| **[PM Launch Agent](./templates/pm-launch-agent/)** | End-to-end launch coordination — content for every channel, calendar, metrics, checklist | go-to-market, content-calendar, media-pitch, email-campaign, launch-checklist | Notion (optional) | 4-6 hours → 3 min |
|
||||
|
||||
Each template includes:
|
||||
- Working orchestration script
|
||||
- Two or more focused subagents
|
||||
- Connector configurations with documented setup
|
||||
- Working examples (input + output)
|
||||
- Smoke test for verifying installations
|
||||
|
||||
### How to install a template
|
||||
|
||||
All templates are part of the main library — installing the marketplace gives you all four.
|
||||
|
||||
/plugin marketplace add mohitagw15856/pm-claude-skills
|
||||
|
||||
|
||||
Then navigate to the template you want and follow its README:
|
||||
|
||||
cd templates/pm-sprint-agent # or pm-discovery-agent, etc.
|
||||
cat README.md # full setup instructions
|
||||
|
||||
|
||||
### Building your own template
|
||||
|
||||
If you want to build a template for a workflow not covered above — Legal Contract Review, Sales Pursuit, Finance Board Pack, HR Onboarding, Marketing Campaign — see the [template contribution guide](./templates/CONTRIBUTING.md).
|
||||
|
||||
The pattern is consistent: pick a multi-step workflow, identify which existing skills cover the structured outputs, add connectors for data access, and define subagents for specialised analysis. The four templates above are reference implementations.
|
||||
|
||||
|
||||
It combines four skills, two connectors, and two subagents into a single workflow that handles end-to-end sprint planning.
|
||||
|
||||
Documentation, working orchestration script, and example outputs are included in the template folder.
|
||||
|
||||
More templates will follow. If you want to contribute one, see the [template contribution guide](./templates/CONTRIBUTING.md).
|
||||
|
||||
---
|
||||
|
||||
## 🆕 What's New in v10.0.0
|
||||
|
||||
**Two star milestones unlocked — 8 new skills shipped:**
|
||||
|
||||
**Customer Success bundle (250 ⭐ milestone):**
|
||||
|
||||
| Skill | Bundle | What It Does |
|
||||
|---|---|---|
|
||||
| **Customer Health Scorecard** 🆕 | pm-cs | Weighted health score across adoption, engagement, outcomes, support, and commercial — with RAG status and renewal forecast |
|
||||
| **QBR Deck** 🆕 | pm-cs | Slide-by-slide quarterly business review structure with talking points, value narrative, and mutual commitments |
|
||||
| **Escalation Brief** 🆕 | pm-cs | Structured escalation brief for at-risk accounts — root cause, business impact, resolution plan, and decision required |
|
||||
| **Churn Analysis** 🆕 | pm-cs | Churn rate breakdown by category and segment, early warning signals, and prioritised interventions |
|
||||
|
||||
**Engineering expansion (500 ⭐ milestone):**
|
||||
|
||||
| Skill | Bundle | What It Does |
|
||||
|---|---|---|
|
||||
| **CI/CD Playbook** 🆕 | pm-engineering | Complete pipeline playbook covering every stage, rollback procedures, secrets management, and on-call responsibilities |
|
||||
| **SLO & Error Budget** 🆕 | pm-engineering | SLI definitions, SLO targets, error budget calculation, burn rate alerts, and error budget policy |
|
||||
| **Developer Onboarding Doc** 🆕 | pm-engineering | Everything a new engineer needs in their first week — architecture, local setup, testing, deployment, and key contacts |
|
||||
| **On-Call Runbook** 🆕 | pm-engineering | Per-alert response procedures, escalation matrix, diagnostic cheat sheet, and handoff template |
|
||||
|
||||
The library now includes **114 skills** across **16 professions** + 4 working agent templates.
|
||||
|
||||
|
||||
| Skill | Bundle | What It Does |
|
||||
|---|---|---|
|
||||
| **Debugging Log Analyser** 🆕 | pm-engineering | Parse stack traces and error logs into a structured root cause diagnosis with a specific fix |
|
||||
| **PR Description Writer** 🆕 | pm-engineering | Write reviewer-friendly PR descriptions from a diff, commit list, or change summary |
|
||||
| **System Design Interview** 🆕 | pm-engineering | Structure complete system design answers with capacity estimates, component deep-dives, and trade-offs |
|
||||
| **Changelog Generator** 🆕 | pm-engineering | Convert git commits into a polished, user-facing changelog following Keep a Changelog format |
|
||||
| **Test Strategy Doc** 🆕 | pm-engineering | Write a complete test strategy with risk assessment, test types, coverage targets, and P0/P1 test cases |
|
||||
| **Runbook Writer** 🆕 | pm-engineering | Write operational runbooks for deployments, incidents, and maintenance with exact commands and rollback steps |
|
||||
|
||||
The `pm-engineering` bundle now has **10 skills** — the most complete engineering toolkit in the library.
|
||||
|
||||
**Read the full story:** [Part 14 — I Rebuilt All 93 Skills and Added 7 More: What 100 Skills Taught Me About What Makes a Great Skill](https://medium.com/product-powerhouse/a-pull-request-made-me-rebuild-all-93-of-my-claude-skills-then-i-added-7-more-16d5fe3e7f85)
|
||||
|
||||
---
|
||||
|
||||
## 📖 v6.0.0 — 100 Skills Milestone
|
||||
|
||||
**7 skills added:**
|
||||
|
||||
| Skill | Bundle | What It Does |
|
||||
|---|---|---|
|
||||
| **Teaching Lesson Plan** | pm-cross | Structured lesson plans for any subject, audience, or setting — with objectives, activities, and formative assessment |
|
||||
| **SEO Content Brief** | pm-gtm | Complete SEO briefs with search intent analysis, competitor gaps, content outline, and on-page requirements |
|
||||
| **Media Pitch** | pm-gtm | Story-first journalist pitches with angle development framework and pitch rules |
|
||||
| **Change Management Plan** | pm-hr | Full change plan covering stakeholder analysis, communication strategy, training, and adoption metrics |
|
||||
| **Workshop Facilitation Guide** | pm-operations | Complete facilitation guides with activity instructions, decision protocols, and facilitator moves |
|
||||
| **Sales Forecasting Model** | pm-sales | Pipeline-based forecast with stage model, scenario analysis, assumption log, and activity sanity check |
|
||||
| **Tax Planning Checklist** | pm-finance | Year-end tax planning review framework across income, pension, CGT, business reliefs, and ISAs |
|
||||
|
||||
---
|
||||
|
||||
## 📚 The Article Series
|
||||
|
||||
This repo was built alongside a published article series. Read the full story:
|
||||
|
||||
| Part | Title | Link |
|
||||
|---|---|---|
|
||||
| Part 1 | Claude Skills: The AI Feature That's Quietly Changing How PMs Work | [Read →](https://medium.com/product-powerhouse/claude-skills-the-ai-feature-thats-quietly-changing-how-product-managers-work-aad5d8d0640a) |
|
||||
| Part 2 | Claude Skills vs Prompts: How PMs and Developers Can 10x Their AI Productivity | [Read →](https://medium.com/@mohit15856/claude-skills-vs-prompts-how-pms-and-developers-can-10x-their-ai-productivity-facb5eed5b12) |
|
||||
| Part 3 | 12 Claude Skills for Product Managers: The Complete Toolkit | [Read →](https://medium.com/@mohit15856/12-claude-skills-for-product-managers-the-complete-toolkit-with-skill-files-for-jira-figma-fcc73a4c1e58) |
|
||||
| Part 4 | Claude Skills: Advanced Guide — What 3 Months of Daily PM Use Actually Taught Me | [Read →](https://medium.com/@mohit15856/claude-skills-advanced-guide-what-3-months-of-daily-pm-use-actually-taught-me-18324d6ef7bc) |
|
||||
| Part 5 | What Google, Meta and Anthropic Want From PMs — And the Claude Skills That Deliver It | [Read →](https://medium.com/@mohit15856/what-google-meta-and-anthropic-want-from-pms-and-the-claude-skills-that-deliver-it-b0f2b6cd9340) |
|
||||
| Part 6 | I Tested Anthropic's Skill Creator Plugin on My Own Skills | [Read →](https://medium.com/all-about-claude/i-tested-anthropics-skill-creator-plugin-on-my-own-skills-here-s-what-i-found-23ad406b0825) |
|
||||
| Part 7 | 33 Claude Skills for PMs Are Now in the Claude Code Marketplace | [Read →](https://medium.com/product-powerhouse/33-claude-skills-for-pms-are-now-in-the-claude-code-marketplace-heres-how-to-install-them-7968ab6bb1e1) |
|
||||
| Part 8 | I Added 20 New Claude Skills Beyond Product Management | [Read →](https://medium.com/product-powerhouse/i-built-20-new-claude-skills-for-every-profession-heres-the-full-library-50278e00bf72) |
|
||||
| Part 9 | 80 Claude Skills for Every Profession — Lawyers, Doctors, Finance, HR, Sales and More | [Read →](https://medium.com/@mohit15856/80-claude-skills-for-every-profession-lawyers-doctors-finance-hr-sales-and-more-3dfde9ec0033) |
|
||||
| Part 10 | A Day in the Life With 80 Claude Skills | [Read →](https://medium.com/@mohit15856/a-day-in-the-life-with-80-claude-skills-what-actually-gets-triggered-7caf9f5c159e) |
|
||||
| Part 11 | 10 Figma Claude Skills for PMs and Designers | [Read →](https://medium.com/@mohit15856/10-figma-claude-skills-for-pms-and-designers-the-complete-figma-toolkit-784441d07a78)|
|
||||
| Part 12 | I Built the Same Skills Library for ChatGPT — Here's What's Different | [Read →](https://medium.com/product-powerhouse/i-built-the-same-skills-library-for-chatgpt-heres-what-s-different-a9305f9c20b9) |
|
||||
| Part 13 | I Re-Tested My 90 Claude Skills on Opus 4.7 — Here's What Got Better | [Read →](https://medium.com/all-about-claude/i-re-tested-my-90-claude-skills-on-opus-4-7-heres-what-actually-got-better-dd4b9369329e)|
|
||||
| Part 14 | I Rebuilt All 93 Skills and Added 7 More: What 100 Skills Taught Me About What Makes a Great Skill | [Read →](https://medium.com/product-powerhouse/a-pull-request-made-me-rebuild-all-93-of-my-claude-skills-then-i-added-7-more-16d5fe3e7f85) |
|
||||
| Part 15 | I’m a Product Manager. I Just Shipped 6 Engineering Skills to My Open-Source Claude Library. | [Read →](https://medium.com/product-powerhouse/im-a-product-manager-i-just-shipped-6-engineering-skills-to-my-open-source-claude-library-8745aaa2ecf9) |
|
||||
| Part 16 | Anthropic Just Released 10 Agent Templates. Here’s the First One I Built Using My 106 Skills. | [Read →](https://medium.com/product-powerhouse/anthropic-just-released-10-agent-templates-heres-the-first-one-i-built-using-my-106-skills-a6708f9bd3ea) |
|
||||
|
||||
---
|
||||
|
||||
## 🗂️ All 135 Skills
|
||||
|
||||
### 🛠️ Product Management (Skills 1–34)
|
||||
**Bundles:** `pm-essentials` · `pm-discovery` · `pm-planning` · `pm-delivery` · `pm-analytics` · `pm-strategy` · `pm-advanced` · `pm-rituals`
|
||||
|
||||
> The original toolkit covering the full PM lifecycle — discovery, prioritisation, delivery, strategy, stakeholder comms, and weekly rituals. Now includes Word tracked changes and PowerPoint slide auditing.
|
||||
|
||||
| # | Skill | What It Does |
|
||||
|---|---|---|
|
||||
| 1–6 | **pm-essentials** | PRD Template, Meeting Notes, Stakeholder Update, User Research Synthesis, Competitive Analysis, **Word Doc Tracked Changes** 🆕 |
|
||||
| 7–10 | **pm-discovery** | Discovery Interview Guide, Job Story Mapper, User Interview Synthesis, Assumption Mapper |
|
||||
| 11–16 | **pm-planning** | OKR Builder, Feature Prioritisation (RICE/MoSCoW/Kano/ICE), Roadmap Presentation, Pricing Strategy |
|
||||
| 17–24 | **pm-delivery** | Sprint Planning, Technical Spec, A/B Test Planner, Go-to-Market Planner, Launch Checklist, Sprint Brief, Retro, **PPTX Slide Auditor** 🆕 |
|
||||
| 25–27 | **pm-analytics** | Data Analysis Standard, Retention Analysis, Product Health Analysis |
|
||||
| 28–33 | **pm-strategy** | Competitor Signal Tracker, Competitive Intelligence Monitor, Stakeholder Influence Mapper, Strategic Narrative, Executive Update, Ambiguity Resolver |
|
||||
| 34 | **pm-advanced** | AI Product Canvas, Multi-Source Signal Synthesiser, Experiment Designer, Design Handoff Brief |
|
||||
|
||||
> See [Part 7 article](https://medium.com/product-powerhouse/33-claude-skills-for-pms-are-now-in-the-claude-code-marketplace-heres-how-to-install-them-7968ab6bb1e1) for full PM skills detail.
|
||||
|
||||
---
|
||||
|
||||
### 📣 Marketing & GTM (Skills 35–40)
|
||||
**Bundle:** `pm-gtm`
|
||||
|
||||
| # | Skill | Folder | What It Does |
|
||||
|---|---|---|---|
|
||||
| 35 | **Go-To-Market** | `skills/go-to-market/` | Positioning statements, messaging pillars, feature/benefit mapping, role-specific use cases |
|
||||
| 36 | **Content Calendar** | `skills/content-calendar/` | Multi-channel content calendars with opening hooks, formats, and repurposing map |
|
||||
| 37 | **Competitor Teardown** | `skills/competitor-teardown/` | Full competitive analysis: positioning map, feature comparison, messaging gaps, SWOT, recommendations |
|
||||
| 38 | **Email Campaign** | `skills/email-campaign/` | Sequenced email campaigns with subject lines, preview text, body copy, and CTAs |
|
||||
| 39 | **SEO Content Brief** 🆕 | `skills/seo-content-brief/` | Complete SEO briefs with search intent, competitor gap analysis, content outline, and on-page requirements |
|
||||
| 40 | **Media Pitch** 🆕 | `skills/media-pitch/` | Story-first journalist pitches with angle development framework and pitch writing rules |
|
||||
|
||||
---
|
||||
|
||||
### 👩💻 Engineering & Tech (Skills 41–75)
|
||||
**Bundle:** `pm-engineering`
|
||||
|
||||
| # | Skill | Folder | What It Does |
|
||||
|---|---|---|---|
|
||||
| 41 | **Code Review Checklist** | `skills/code-review-checklist/` | Tailored PR review checklists by language, type, and risk level |
|
||||
| 42 | **Incident Postmortem** | `skills/incident-postmortem/` | Blameless postmortems with timeline, RCA, impact, and action items |
|
||||
| 43 | **API Docs Writer** | `skills/api-docs-writer/` | Developer-facing API docs: endpoints, parameters, response schemas, code examples |
|
||||
| 44 | **Architecture Decision Record** | `skills/architecture-decision-record/` | ADRs with context, options considered, decision, consequences, and risks |
|
||||
| 45 | **Debugging Log Analyser** | `skills/debugging-log-analyser/` | Parse stack traces and error logs into a structured root cause diagnosis with a specific fix |
|
||||
| 46 | **PR Description Writer** | `skills/pr-description-writer/` | Write reviewer-friendly PR descriptions from a diff, commit list, or change summary |
|
||||
| 47 | **System Design Interview** | `skills/system-design-interview/` | Structure complete system design answers with capacity estimates, component deep-dives, and trade-offs |
|
||||
| 48 | **Changelog Generator** | `skills/changelog-generator/` | Convert git commits into a polished, user-facing changelog following Keep a Changelog format |
|
||||
| 49 | **Test Strategy Doc** | `skills/test-strategy-doc/` | Write a complete test strategy with risk assessment, test types, coverage targets, and P0/P1 test cases |
|
||||
| 50 | **Runbook Writer** | `skills/runbook-writer/` | Write operational runbooks for deployments, incidents, and maintenance with exact commands and rollback steps |
|
||||
| 51 | **CI/CD Playbook** | `skills/cicd-playbook/` | Complete pipeline playbook covering every stage, rollback procedures, secrets management, and on-call responsibilities |
|
||||
| 52 | **SLO & Error Budget** | `skills/slo-error-budget/` | SLI definitions, SLO targets, error budget calculation, burn rate alerts, and error budget policy |
|
||||
| 53 | **Developer Onboarding Doc** | `skills/developer-onboarding-doc/` | Everything a new engineer needs in their first week — architecture, local setup, testing, deployment, and key contacts |
|
||||
| 54 | **On-Call Runbook** | `skills/oncall-runbook/` | Per-alert response procedures, escalation matrix, diagnostic cheat sheet, and handoff template |
|
||||
| 55 | **Security Threat Model** 🆕 | `skills/security-threat-model/` | STRIDE-based threat model with asset register, trust boundaries, per-component threat enumeration, risk scores, and mitigations |
|
||||
| 56 | **Performance Budget** 🆕 | `skills/performance-budget/` | Performance budgets for Core Web Vitals and backend latency SLOs with CI enforcement and breach response policy |
|
||||
| 57 | **Database Schema Design** 🆕 | `skills/database-schema-design/` | Database schema documentation with ER diagram, DDL definitions, index strategy, and access pattern analysis |
|
||||
| 58 | **Database Migration Plan** 🆕 | `skills/database-migration-plan/` | Safe zero-downtime migration plan using expand-contract pattern with per-step rollback and data validation queries |
|
||||
| 59 | **Technical Debt Register** 🆕 | `skills/technical-debt-register/` | Debt inventory with business impact scoring, effort estimates, priority matrix, and quarterly resolution roadmap |
|
||||
| 60 | **RFC Writer** 🆕 | `skills/rfc-writer/` | Engineering Request for Comments covering problem, proposed solution, alternatives-with-rejection-reasons, and rollout plan |
|
||||
| 61 | **Capacity Planning** 🆕 | `skills/capacity-planning/` | Traffic forecasts, resource requirements per tier, scaling strategy, cost projections, and infrastructure action roadmap |
|
||||
| 62 | **Load Testing Plan** 🆕 | `skills/load-testing-plan/` | Load test plan with scenario definitions (baseline/stress/spike/soak), k6/Locust skeleton, thresholds, and CI gates |
|
||||
| 63 | **Disaster Recovery Plan** 🆕 | `skills/disaster-recovery-plan/` | DR plan with RPO/RTO targets, per-scenario runbooks, backup procedures, game day testing, and communication templates |
|
||||
| 64 | **Feature Flag Guide** 🆕 | `skills/feature-flag-guide/` | Feature flag lifecycle playbook — taxonomy, rollout strategy, monitoring requirements, cleanup policy, and governance |
|
||||
| 65 | **Dependency Audit** 🆕 | `skills/dependency-audit/` | Dependency audit for CVE vulnerabilities, license compliance, outdated packages, and 30-day remediation plan |
|
||||
| 66 | **Service Catalog Entry** 🆕 | `skills/service-catalog-entry/` | Microservice catalog entry with ownership, SLAs, API contract, data classification, and operational runbook links |
|
||||
| 67 | **Monitoring Setup Guide** 🆕 | `skills/monitoring-setup-guide/` | Four golden signals applied to a service, alert rules spec, structured log schema, tracing setup, and dashboard layout |
|
||||
| 68 | **Local Dev Setup** 🆕 | `skills/local-dev-setup/` | Local development setup guide — prerequisites, env vars, dependencies, test commands, and 5 common failure fixes |
|
||||
| 69 | **API Versioning Strategy** 🆕 | `skills/api-versioning-strategy/` | API versioning scheme, lifecycle policy, breaking change classification table, deprecation process, and migration guide template |
|
||||
| 70 | **Infra-as-Code Review** 🆕 | `skills/infra-as-code-review/` | IaC review for Terraform/CloudFormation/Pulumi — security, naming, state, cost, and drift risk with severity-classified findings |
|
||||
| 71 | **Engineering Weekly Report** 🆕 | `skills/engineering-weekly-report/` | Weekly engineering status in a consistent format — shipped/in-progress/blocked, metrics, decisions, risks, and next week |
|
||||
| 72 | **Tech Radar** 🆕 | `skills/tech-radar/` | ThoughtWorks-format technology radar with Adopt/Trial/Assess/Hold quadrants, per-blip rationale, and maintenance process |
|
||||
| 73 | **Sprint Velocity Analysis** 🆕 | `skills/sprint-velocity-analysis/` | Velocity trend analysis, completion rate patterns, blocker frequency, improvement recommendations, and capacity forecast |
|
||||
| 74 | **Microservices Decomposition** 🆕 | `skills/microservices-decomposition/` | Domain-driven service boundary design with bounded context map, communication patterns, data ownership, and strangler fig migration plan |
|
||||
| 75 | **Engineering Hiring Rubric** 🆕 | `skills/engineering-hiring-rubric/` | Technical interview rubric with level expectations, coding scorecard, system design guide, behavioural question bank, and debrief template |
|
||||
|
||||
---
|
||||
|
||||
### 🤝 Customer Success (Skills 76–79)
|
||||
**Bundle:** `pm-cs`
|
||||
|
||||
> 250 ⭐ milestone unlocked. Install:
|
||||
|
||||
claude plugin install pm-cs@pm-claude-skills
|
||||
|
||||
|
||||
| # | Skill | Folder | What It Does |
|
||||
|---|---|---|---|
|
||||
| 76 | **Customer Health Scorecard** | `skills/cs-health-scorecard/` | Weighted health score across adoption, engagement, outcomes, support, and commercial — RAG status and renewal forecast |
|
||||
| 77 | **QBR Deck** | `skills/qbr-deck/` | Slide-by-slide quarterly business review with talking points, value narrative, and mutual commitments |
|
||||
| 78 | **Escalation Brief** | `skills/cs-escalation-brief/` | Structured brief for at-risk accounts — root cause, business impact, resolution plan, and decision required |
|
||||
| 79 | **Churn Analysis** | `skills/churn-analysis/` | Churn breakdown by category and segment, early warning signals, and prioritised interventions |
|
||||
|
||||
---
|
||||
|
||||
### 📊 Data & Analytics (Skills 80–83)
|
||||
**Bundle:** `pm-data`
|
||||
|
||||
| # | Skill | Folder | What It Does |
|
||||
|---|---|---|---|
|
||||
| 80 | **Metrics Framework** | `skills/metrics-framework/` | North Star + metric tree, dashboard tiers, counter-metrics |
|
||||
| 81 | **SQL Query Explainer** | `skills/sql-query-explainer/` | Explain, optimise, write, and document SQL in plain English |
|
||||
| 82 | **Dashboard Brief** | `skills/dashboard-brief/` | Complete dashboard spec: KPIs, charts, filters, layout, data requirements |
|
||||
| 83 | **Chart Data Extractor** | `skills/chart-data-extractor/` | Extract pixel-level data from chart images into structured data tables |
|
||||
|
||||
---
|
||||
|
||||
### 🧑💼 Leadership & People (Skills 84–86)
|
||||
**Bundle:** `pm-people`
|
||||
|
||||
| # | Skill | Folder | What It Does |
|
||||
|---|---|---|---|
|
||||
| 84 | **Performance Review** | `skills/performance-review/` | Structured reviews from bullet-point notes — self, manager, peer, and upward |
|
||||
| 85 | **Hiring Rubric** | `skills/hiring-rubric/` | Interview scorecards with competencies, behavioural questions, and panel guide |
|
||||
| 86 | **Team Offsite Planner** | `skills/team-offsite-planner/` | Full offsite agenda, session facilitation notes, and logistics checklist |
|
||||
|
||||
---
|
||||
|
||||
### 🎨 Design & UX (Skills 87–89)
|
||||
**Bundle:** `pm-design`
|
||||
|
||||
| # | Skill | Folder | What It Does |
|
||||
|---|---|---|---|
|
||||
| 87 | **UX Research Plan** | `skills/ux-research-plan/` | Research plans with screener, discussion guide, and synthesis framework |
|
||||
| 88 | **Design Critique** | `skills/design-critique/` | Structured feedback using JTBD, Gestalt principles, and Nielsen's heuristics |
|
||||
| 89 | **Accessibility Audit** | `skills/accessibility-audit/` | WCAG 2.2 audit with prioritised remediation and quick wins |
|
||||
|
||||
---
|
||||
|
||||
### 🏢 Business & Strategy (Skills 90–92)
|
||||
**Bundle:** `pm-business`
|
||||
|
||||
| # | Skill | Folder | What It Does |
|
||||
|---|---|---|---|
|
||||
| 90 | **Investor Update** | `skills/investor-update/` | Monthly/quarterly investor updates: metrics, highlights, challenges, and asks |
|
||||
| 91 | **Board Deck Narrative** | `skills/board-deck-narrative/` | Slide-by-slide board presentation structure with narrative beats and talking points |
|
||||
| 92 | **Job Application** | `skills/job-application/` | Tailored CV summary, ATS keyword optimisation, and cover letter for any JD |
|
||||
|
||||
---
|
||||
|
||||
### ⚖️ Legal (Skills 93–96)
|
||||
**Bundle:** `pm-legal`
|
||||
|
||||
> ⚠️ All legal skills include a disclaimer. Not a substitute for qualified legal advice.
|
||||
|
||||
| # | Skill | Folder | What It Does |
|
||||
|---|---|---|---|
|
||||
| 93 | **Contract Review** | `skills/contract-review/` | Structured review with key terms, flagged clauses, risk rating, and plain English summary |
|
||||
| 94 | **NDA Analyser** | `skills/nda-analyser/` | Clause-by-clause NDA analysis with risk flags and negotiation checklist |
|
||||
| 95 | **Legal Brief** | `skills/legal-brief/` | Legal memos and argument outlines in IRAC format (Issue, Rule, Application, Conclusion) |
|
||||
| 96 | **Compliance Checklist** | `skills/compliance-checklist/` | GDPR, SOC 2, ISO 27001, FCA, HIPAA compliance checklists with prioritised gap analysis |
|
||||
|
||||
---
|
||||
|
||||
### 💰 Finance (Skills 97–101)
|
||||
**Bundle:** `pm-finance`
|
||||
|
||||
| # | Skill | Folder | What It Does |
|
||||
|---|---|---|---|
|
||||
| 97 | **Financial Model Narrative** | `skills/financial-model-narrative/` | Turns P&L and model outputs into board-ready written narratives |
|
||||
| 98 | **Budget Variance Analysis** | `skills/budget-variance-analysis/` | Variance table with root cause commentary and management summary |
|
||||
| 99 | **Investor Pitch Deck** | `skills/investor-pitch-deck/` | Slide-by-slide pitch deck structure with what each slide must prove |
|
||||
| 100 | **Financial Due Diligence** | `skills/financial-due-diligence/` | DD document request list, analytical questions, and red flags checklist |
|
||||
| 101 | **Tax Planning Checklist** | `skills/tax-planning-checklist/` | Year-end tax planning framework across income, pension, CGT, business reliefs, and ISAs |
|
||||
|
||||
---
|
||||
|
||||
### 👥 HR (Skills 102–106)
|
||||
**Bundle:** `pm-hr`
|
||||
|
||||
| # | Skill | Folder | What It Does |
|
||||
|---|---|---|---|
|
||||
| 102 | **Job Description Writer** | `skills/job-description-writer/` | Inclusive, structured JDs with built-in language review and salary range nudge |
|
||||
| 103 | **Onboarding Plan** | `skills/onboarding-plan/` | 30/60/90-day plans with week-by-week structure, milestones, and manager checklist |
|
||||
| 104 | **Employee Engagement Survey** | `skills/employee-engagement-survey/` | Survey design + results analysis mode with eNPS and action planning template |
|
||||
| 105 | **Redundancy Consultation** | `skills/redundancy-consultation/` | Process timeline, at-risk letter, consultation script, and confirmation letter — UK law |
|
||||
| 106 | **Change Management Plan** | `skills/change-management-plan/` | Full change plan covering stakeholder analysis, communication strategy, training, and adoption metrics |
|
||||
|
||||
---
|
||||
|
||||
### 🤝 Sales (Skills 107–111)
|
||||
**Bundle:** `pm-sales`
|
||||
|
||||
| # | Skill | Folder | What It Does |
|
||||
|---|---|---|---|
|
||||
| 107 | **Sales Battlecard** | `skills/sales-battlecard/` | One-page competitive battlecard with objection responses and landmine questions |
|
||||
| 108 | **Discovery Call Prep** | `skills/discovery-call-prep/` | Call brief with research summary, hypothesis, structured questions, and success criteria |
|
||||
| 109 | **Proposal Writer** | `skills/proposal-writer/` | Commercial proposals structured around the prospect's problem, not the product |
|
||||
| 110 | **Account Plan** | `skills/account-plan/` | Strategic account plan with relationship map, whitespace analysis, risks, and 90-day actions |
|
||||
| 111 | **Sales Forecasting Model** | `skills/sales-forecasting-model/` | Pipeline-based forecast with stage model, scenario analysis, assumption log, and activity sanity check |
|
||||
|
||||
---
|
||||
|
||||
### ⚙️ Operations (Skills 112–116)
|
||||
**Bundle:** `pm-operations`
|
||||
|
||||
| # | Skill | Folder | What It Does |
|
||||
|---|---|---|---|
|
||||
| 112 | **Process Documentation** | `skills/process-documentation/` | Clear process docs with steps, roles, edge cases — followable by a new starter |
|
||||
| 113 | **SOP Writer** | `skills/sop-writer/` | Formal, audit-ready SOPs with version control, quality checks, and non-conformance process |
|
||||
| 114 | **Vendor Evaluation** | `skills/vendor-evaluation/` | Weighted vendor scorecard, RFP questions, reference check template, and recommendation |
|
||||
| 115 | **Project Status Report** | `skills/project-status-report/` | RAG status reports with milestone progress, issues, risks, and decisions required |
|
||||
| 116 | **Workshop Facilitation Guide** | `skills/workshop-facilitation-guide/` | Complete facilitation guides with activity instructions, decision protocols, and facilitator moves |
|
||||
|
||||
---
|
||||
|
||||
### 🏥 Research & Healthcare (Skills 117–120)
|
||||
**Bundle:** `pm-research`
|
||||
|
||||
> ⚠️ Healthcare skills are for documentation and educational purposes only. All clinical content must be reviewed by a qualified professional.
|
||||
|
||||
| # | Skill | Folder | What It Does |
|
||||
|---|---|---|---|
|
||||
| 117 | **Clinical Case Summary** | `skills/clinical-case-summary/` | SBAR handovers, SOAP notes, and case reports for educational and documentation use |
|
||||
| 118 | **Research Protocol** | `skills/research-protocol/` | Complete study protocols with objectives, methodology, ethics, and analysis plan |
|
||||
| 119 | **Patient Communication** | `skills/patient-communication/` | Plain English patient letters, leaflets, and results communications at Grade 6 reading level |
|
||||
| 120 | **Literature Review** | `skills/literature-review/` | Thematically organised literature reviews with synthesis, critical analysis, and gap identification |
|
||||
|
||||
---
|
||||
|
||||
### 🌐 Cross-Profession (Skills 121–124)
|
||||
**Bundle:** `pm-cross`
|
||||
|
||||
| # | Skill | Folder | What It Does |
|
||||
|---|---|---|---|
|
||||
| 121 | **Press Release** | `skills/press-release/` | Journalist-ready press releases with headline rules, boilerplate, and journalist test |
|
||||
| 122 | **Grant Proposal** | `skills/grant-proposal/` | Complete grant applications aligned to funder priorities with budget narrative |
|
||||
| 123 | **Executive Summary** | `skills/executive-summary/` | Decision-ready executive summaries with bottom line upfront, adapted for any audience |
|
||||
| 124 | **Teaching Lesson Plan** | `skills/teaching-lesson-plan/` | Complete lesson plans for any subject, audience, or setting — with objectives, activities, and formative assessment |
|
||||
|
||||
---
|
||||
|
||||
### 🖼️ Figma (Skills 125–134)
|
||||
**Bundle:** `pm-figma`
|
||||
|
||||
| # | Skill | Folder | What It Does |
|
||||
|---|---|---|---|
|
||||
| 125 | **Figma Component Audit** | `skills/figma-component-audit/` | Audit component library for naming issues, coverage gaps, and variant completeness |
|
||||
| 126 | **Figma Design Brief** | `skills/figma-design-brief/` | Convert PRDs and feature requests into structured Figma design briefs |
|
||||
| 127 | **Figma Annotation Guide** | `skills/figma-annotation-guide/` | Generate complete developer handoff annotations covering all states and edge cases |
|
||||
| 128 | **Figma Design Review** | `skills/figma-design-review/` | PM design review against requirements with explicit approval status |
|
||||
| 129 | **Figma User Flow Planner** | `skills/figma-user-flow-planner/` | Map all screens, states, and decision points before opening Figma |
|
||||
| 130 | **Figma Variant Matrix** | `skills/figma-variant-matrix/` | Define all component variants, properties, and states before building |
|
||||
| 131 | **Figma Spacing System** | `skills/figma-spacing-system/` | Design a complete spacing scale, grid, and token system |
|
||||
| 132 | **Figma Prototype Plan** | `skills/figma-prototype-plan/` | Plan prototype scope, interactions, and test task scripts for user testing |
|
||||
| 133 | **Figma Design QA** | `skills/figma-design-qa/` | Pre-handoff QA checklist covering file hygiene, states, accessibility, and handoff readiness |
|
||||
| 134 | **Figma Design Critique (PM)** | `skills/figma-design-critique-pm/` | PM-perspective design critique focused on product outcomes, not aesthetics |
|
||||
|
||||
claude plugin install pm-figma@pm-claude-skills
|
||||
|
||||
|
||||
---
|
||||
|
||||
### 📅 PM Rituals (Skill 135)
|
||||
**Bundle:** `pm-rituals`
|
||||
|
||||
| # | Skill | Folder | What It Does |
|
||||
|---|---|---|---|
|
||||
| 135 | **PM Weekly Review** | `skills/pm-weekly-review/` | Weekly PM review and planning ritual — metrics, shipping progress, blockers, and next week's priorities |
|
||||
|
||||
---
|
||||
|
||||
## ❤️ Sponsor This Work
|
||||
|
||||
Building and maintaining 135 skills across 23 bundles takes real time — testing skills against new model releases, building new ones from community requests, writing the article series, and keeping documentation current.
|
||||
|
||||
If these skills save you time at work, consider sponsoring:
|
||||
|
||||
**[💖 Become a Sponsor →](https://github.com/sponsors/mohitagw15856)**
|
||||
|
||||
Sponsorships from $5/month (coffee tier) up to $500/month (sustaining sponsor with logo placement). Every sponsor directly funds:
|
||||
|
||||
- New skills based on community votes in [SKILL_REQUEST.md](SKILL_REQUEST.md)
|
||||
- Updates to existing skills when new Claude models ship
|
||||
- Continued free, ad-free Medium articles documenting what works
|
||||
- Quality improvements across the library
|
||||
|
||||
Higher tiers include custom skill development for your team, direct access for support, and logo placement in this README. See the [sponsor page](https://github.com/sponsors/mohitagw15856) for full tier details.
|
||||
|
||||
---
|
||||
|
||||
## 🤝 Contributing — Add Your Skill
|
||||
|
||||
This is an open-source community library. If you've built a skill that saves you time, share it here.
|
||||
|
||||
**Found a bug?** [Open a bug report →](../../issues/new?template=bug-report.md) — use the template so it's easy to triage.
|
||||
|
||||
**How to contribute:**
|
||||
|
||||
1. Fork this repo
|
||||
2. Create a new folder: `skills/your-skill-name/`
|
||||
3. Add a `SKILL.md` file following the template below
|
||||
4. Raise a pull request with a short description of what the skill does and why you built it
|
||||
|
||||
**SKILL.md template:**
|
||||
---
|
||||
name: your-skill-name
|
||||
description: "One sentence. Use when [trigger condition]. Produces [output description]."
|
||||
---
|
||||
|
||||
# Skill Title
|
||||
|
||||
[Instructions for Claude to follow when this skill is invoked]
|
||||
|
||||
|
||||
**What makes a good skill:**
|
||||
- Solves a recurring professional workflow (not a one-off task)
|
||||
- Has a clear trigger description so Claude knows when to activate it
|
||||
- Produces consistent, structured output
|
||||
- Works without needing extensive setup or context
|
||||
|
||||
**Skills wishlist** (most requested — up for grabs):
|
||||
|
||||
| Skill | Profession | Use Case |
|
||||
|---|---|---|
|
||||
| `grant-report` | Non-profit | Funder progress reports against grant objectives |
|
||||
| `architectural-spec` | Architecture | Project specifications and technical drawing briefs |
|
||||
| `clinical-guideline-summary` | Healthcare | Plain English summaries of clinical guidelines |
|
||||
| `pitch-deck-feedback` | Startup | Investor-perspective critique of a pitch deck |
|
||||
| `board-minutes` | Governance | Formal board meeting minutes from discussion notes |
|
||||
|
||||
Have a skill idea? Add it to [SKILL_REQUEST.md](SKILL_REQUEST.md), [open an issue](../../issues), or raise it in [Discussions](../../discussions). Most-voted requests get built first.
|
||||
|
||||
**Contributors** get credited in this README and in the article series. 🙌
|
||||
|
||||
---
|
||||
|
||||
## 📦 All Plugin Bundles
|
||||
|
||||
Install the whole library or just the bundles you need:
|
||||
|
||||
# Install everything
|
||||
/plugin marketplace add mohitagw15856/pm-claude-skills
|
||||
|
||||
# Install by profession
|
||||
claude plugin install pm-essentials@pm-claude-skills
|
||||
|
||||
claude plugin install pm-discovery@pm-claude-skills
|
||||
|
||||
claude plugin install pm-planning@pm-claude-skills
|
||||
|
||||
claude plugin install pm-delivery@pm-claude-skills
|
||||
|
||||
claude plugin install pm-analytics@pm-claude-skills
|
||||
|
||||
claude plugin install pm-strategy@pm-claude-skills
|
||||
|
||||
claude plugin install pm-advanced@pm-claude-skills
|
||||
|
||||
claude plugin install pm-rituals@pm-claude-skills
|
||||
|
||||
claude plugin install pm-gtm@pm-claude-skills
|
||||
|
||||
claude plugin install pm-engineering@pm-claude-skills # Engineering (35 skills)
|
||||
|
||||
claude plugin install pm-cs@pm-claude-skills # Customer Success (4 skills) 🆕
|
||||
|
||||
claude plugin install pm-data@pm-claude-skills
|
||||
|
||||
claude plugin install pm-people@pm-claude-skills
|
||||
|
||||
claude plugin install pm-design@pm-claude-skills
|
||||
|
||||
claude plugin install pm-business@pm-claude-skills
|
||||
|
||||
claude plugin install pm-legal@pm-claude-skills
|
||||
|
||||
claude plugin install pm-finance@pm-claude-skills
|
||||
|
||||
claude plugin install pm-hr@pm-claude-skills
|
||||
|
||||
claude plugin install pm-sales@pm-claude-skills
|
||||
|
||||
claude plugin install pm-operations@pm-claude-skills
|
||||
|
||||
claude plugin install pm-research@pm-claude-skills
|
||||
|
||||
claude plugin install pm-cross@pm-claude-skills
|
||||
|
||||
claude plugin install pm-figma@pm-claude-skills
|
||||
|
||||
---
|
||||
|
||||
## 🤖 Companion Repository — ChatGPT Custom GPTs
|
||||
|
||||
If you use ChatGPT instead of Claude Code, there's a companion repo with the same professional frameworks built as Custom GPT system prompts:
|
||||
|
||||
**[professional-gpt-library](https://github.com/mohitagw15856/professional-gpt-library)** — 10 starter GPTs across 8 professions, MIT licence.
|
||||
|
||||
Read the full breakdown: [Part 12 — I Built the Same Skills Library for ChatGPT](https://medium.com/product-powerhouse/i-built-the-same-skills-library-for-chatgpt-heres-what-s-different-a9305f9c20b9)
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Custom Skills for Your Team
|
||||
|
||||
The 114 skills in this library are built for general professional workflows. But the most powerful version of Claude Skills is one built specifically for *your* team — your templates, your terminology, your processes, your quality standards.
|
||||
|
||||
**What custom skills look like in practice:**
|
||||
|
||||
- A law firm's contract review skill trained on their specific clause library and risk tolerance
|
||||
- A SaaS company's sprint brief skill that knows their engineering conventions and definition of done
|
||||
- A finance team's board pack skill that follows their exact narrative structure and slide format
|
||||
- An HR team's job description skill that reflects their values language and includes their specific benefits
|
||||
|
||||
The difference between a generic skill and one built for your context is significant. Generic skills eliminate the blank page. Custom skills eliminate the rework.
|
||||
|
||||
**If you want skills built for your team's specific workflows — [get in touch](mailto:mohit15856@gmail.com).**
|
||||
|
||||
Include a brief description of your team, the workflows you want to automate, and the tools you use. I'll come back to you within 48 hours.
|
||||
|
||||
---
|
||||
|
||||
## 📖 How Skills Work
|
||||
|
||||
Skills are markdown files that Claude reads dynamically. When you describe a task, Claude scans available skill descriptions (~100 tokens) and loads the full skill only when relevant. This means:
|
||||
|
||||
- Skills are efficient — they only use tokens when triggered
|
||||
- Multiple skills can coexist without slowing Claude down
|
||||
- Personal skills (`~/.claude/skills/`) work across all your projects
|
||||
- Plugin skills install via the Claude Code marketplace with one command
|
||||
|
||||
Learn more: [Anthropic's Skills documentation](https://code.claude.com/docs/en/skills)
|
||||
|
||||
---
|
||||
|
||||
## ⭐ Star Milestones
|
||||
|
||||
Stars unlock the next wave of skills. Here's the roadmap:
|
||||
|
||||
| Milestone | Unlocks | Status |
|
||||
|---|---|---|
|
||||
| 100 ⭐ | 10 Figma skills + quality rebuild across all 93 skills | ✅ Shipped (v6.0.0) |
|
||||
| 250 ⭐ | 10 Customer Success skills (health scorecard, QBR deck, escalation brief, churn analysis) | ✅ Unlocked — coming in next release |
|
||||
| 500 ⭐ | 25 Engineering skills (CI/CD playbooks, SLO templates, onboarding docs, debugging patterns, threat models, capacity planning, DR plans, and more) | ✅ Shipped — pm-engineering now 35 skills (v11.0.0) |
|
||||
| 1000 ⭐ | Full Startup Founder kit (fundraising memo, pitch critique, co-founder equity split) | 🔒 Locked |
|
||||
|
||||
**[⭐ Star this repo to unlock the next milestone →](https://github.com/mohitagw15856/pm-claude-skills)**
|
||||
|
||||
Want a specific skill built? [Vote or request in SKILL_REQUEST.md](SKILL_REQUEST.md).
|
||||
|
||||
---
|
||||
|
||||
*Built and maintained by [Mohit Aggarwal](https://medium.com/@mohit15856) | [Product Notes publication](https://medium.com/product-powerhouse) | [💖 Sponsor my work](https://github.com/sponsors/mohitagw15856)*
|
||||
|
||||
+55
@@ -0,0 +1,55 @@
|
||||
# Security Policy
|
||||
|
||||
## Overview
|
||||
|
||||
This repository contains Claude Skill files — plain markdown instruction files that teach Claude how to perform professional tasks. There are no backend services, APIs, authentication systems, or databases in this repo.
|
||||
|
||||
That said, security matters here in two specific ways: **skill file safety** and **prompt injection risks**.
|
||||
|
||||
## Supported Versions
|
||||
|
||||
| Version | Supported |
|
||||
|---|---|
|
||||
| v4.0.0 (latest) | ✅ Active |
|
||||
| v3.0.0 | ✅ Security fixes only |
|
||||
| < v3.0.0 | ❌ No longer supported |
|
||||
|
||||
## Skill File Safety
|
||||
|
||||
All skills in this repo are reviewed before merging to ensure they:
|
||||
|
||||
- Do not contain instructions designed to manipulate Claude into ignoring its guidelines
|
||||
- Do not attempt prompt injection (e.g. hidden instructions to override system behaviour)
|
||||
- Do not instruct Claude to request, store, or transmit personal or sensitive data
|
||||
- Do not contain malicious commands disguised as skill instructions
|
||||
- Do not include hardcoded credentials, API keys, or personally identifiable information
|
||||
|
||||
**If you are installing skills from this repo:** skills are plain text markdown files. They do not execute code, make network requests, or access your file system on their own. Review any skill file before installing if you have concerns.
|
||||
|
||||
## Reporting a Vulnerability
|
||||
|
||||
If you discover a skill file in this repo that contains malicious instructions, a prompt injection attempt, or any content that could cause harm to users of Claude Code, please report it **privately** before raising a public issue.
|
||||
|
||||
**How to report:**
|
||||
|
||||
Email: **mohit15856@gmail.com**
|
||||
Subject line: `[SECURITY] pm-claude-skills — <brief description>`
|
||||
|
||||
Include:
|
||||
- The skill file path (e.g. `plugins/pm-gtm/skills/go-to-market/SKILL.md`)
|
||||
- A description of the issue
|
||||
- Why you believe it is a security concern
|
||||
|
||||
**Response time:** You will receive an acknowledgement within 48 hours and a resolution or update within 7 days.
|
||||
|
||||
Please do not open a public GitHub Issue for security vulnerabilities — use the email above. Public disclosure before a fix is in place puts other users at risk.
|
||||
|
||||
## Community Contributions
|
||||
|
||||
All pull requests adding new skill files are reviewed for the safety criteria listed above before merging. If you are submitting a skill, ensure it:
|
||||
|
||||
- Only contains instructions relevant to the stated professional workflow
|
||||
- Does not include any attempt to override Claude's built-in guidelines
|
||||
- Does not ask Claude to collect or relay user data
|
||||
|
||||
See [CONTRIBUTING.md](CONTRIBUTING.md) for full contribution guidelines.
|
||||
@@ -0,0 +1,65 @@
|
||||
# Skill Requests — Community Voting Board
|
||||
|
||||
Have an idea for a skill? Add it here or upvote existing requests by leaving a 👍 reaction on the issue.
|
||||
|
||||
---
|
||||
|
||||
## How to Request a Skill
|
||||
|
||||
1. [Open an issue](https://github.com/mohitagw15856/pm-claude-skills/issues/new) with the label `skill-request`
|
||||
2. Include:
|
||||
- **Skill name** (what you'd call it)
|
||||
- **Profession** (who uses this)
|
||||
- **Trigger** (when would you invoke it — e.g. "when I need to write X")
|
||||
- **Output** (what should Claude produce)
|
||||
3. Drop a 👍 on existing requests you'd use — most-voted get built first
|
||||
|
||||
---
|
||||
|
||||
## Milestone Unlocks
|
||||
|
||||
Stars drive the roadmap. Here's what's queued:
|
||||
|
||||
| Milestone | Unlocks |
|
||||
|---|---|
|
||||
| ✅ 100 ⭐ | 10 Figma skills + quality rebuild across all skills (v6.0.0) |
|
||||
| 🔒 250 ⭐ | 10 Customer Success skills (health scorecard, QBR deck, escalation brief, churn analysis) |
|
||||
| 🔒 500 ⭐ | 25 more Engineering skills (CI/CD playbooks, debugging deep-dives, onboarding docs, SLO templates) |
|
||||
| 🔒 1000 ⭐ | Full Startup Founder kit (fundraising memo, pitch critique, co-founder agreement framework) |
|
||||
|
||||
**[Star this repo →](https://github.com/mohitagw15856/pm-claude-skills)**
|
||||
|
||||
---
|
||||
|
||||
## Requested Skills (Open)
|
||||
|
||||
Add a request by opening an issue — these are current top asks from the community:
|
||||
|
||||
| Skill | Profession | Requested By | Votes |
|
||||
|---|---|---|---|
|
||||
| `customer-health-scorecard` | Customer Success | [@mohitagw15856](https://github.com/mohitagw15856) | — |
|
||||
| `qbr-deck-writer` | Customer Success | [@mohitagw15856](https://github.com/mohitagw15856) | — |
|
||||
| `escalation-brief` | Customer Success | [@mohitagw15856](https://github.com/mohitagw15856) | — |
|
||||
| `fundraising-memo` | Startup / Founder | [@mohitagw15856](https://github.com/mohitagw15856) | — |
|
||||
| `youtube-script-writer` | Content Creator | [@mohitagw15856](https://github.com/mohitagw15856) | — |
|
||||
| `newsletter-issue-writer` | Content Creator | [@mohitagw15856](https://github.com/mohitagw15856) | — |
|
||||
| `analytics-event-taxonomy` | Data / Analytics | [@mohitagw15856](https://github.com/mohitagw15856) | — |
|
||||
| `kpi-tree-builder` | Data / Analytics | [@mohitagw15856](https://github.com/mohitagw15856) | — |
|
||||
| `dissertation-chapter-planner` | Academic | [@mohitagw15856](https://github.com/mohitagw15856) | — |
|
||||
| `board-minutes` | Governance | Community | — |
|
||||
|
||||
> **To vote:** React with 👍 on the linked issue. To add a new request, open an issue with label `skill-request`.
|
||||
|
||||
---
|
||||
|
||||
## Recently Shipped
|
||||
|
||||
| Version | Skills Added |
|
||||
|---|---|
|
||||
| v7.0.0 | Debugging Log Analyser, PR Description Writer, System Design Interview, Changelog Generator, Test Strategy Doc, Runbook Writer |
|
||||
| v6.0.0 | Teaching Lesson Plan, SEO Content Brief, Media Pitch, Change Management Plan, Workshop Facilitation Guide, Sales Forecasting Model, Tax Planning Checklist |
|
||||
| v5.0.0 | 10 Figma skills |
|
||||
|
||||
---
|
||||
|
||||
*Maintained by [Mohit Aggarwal](https://github.com/mohitagw15856)*
|
||||
@@ -0,0 +1,136 @@
|
||||
# Examples: pm-figma Skills
|
||||
|
||||
## What this bundle does
|
||||
10 Figma skills covering the full design lifecycle for product managers and designers — from planning what to design, through building components and prototypes, to QA before handoff.
|
||||
|
||||
---
|
||||
|
||||
## figma-component-audit
|
||||
|
||||
### Example 1 — Messy legacy library
|
||||
|
||||
**You say:**
|
||||
> "Audit our Figma component library. We have buttons, inputs, cards, modals, and navigation components but the naming is all over the place and developers keep asking for states we haven't designed."
|
||||
|
||||
**Claude produces:**
|
||||
|
||||
**Audit Summary**
|
||||
|
||||
| Dimension | Status | Score |
|
||||
|---|---|---|
|
||||
| Naming consistency | 🔴 Poor | 3/10 |
|
||||
| Component coverage | 🟡 Partial | 6/10 |
|
||||
| Variant completeness | 🔴 Poor | 4/10 |
|
||||
| Overall health | 🟡 Partial | 5/10 |
|
||||
|
||||
**Issue: Mixed capitalisation conventions**
|
||||
- What's happening: `button-primary`, `Button/Primary`, `btn_primary` all exist in the same library
|
||||
- Fix: Adopt PascalCase for components (`Button`), lowercase slash-separated for variants (`type/primary`, `size/large`, `state/default`)
|
||||
- Before: `btn_primary_large_hover` → After: `Button` with variants `type/primary`, `size/large`, `state/hover`
|
||||
|
||||
**Missing states developers are asking for:**
|
||||
| Component | Missing | Priority |
|
||||
|---|---|---|
|
||||
| Button | Active/pressed state | 🔴 High |
|
||||
| Input | Error state with helper text | 🔴 High |
|
||||
| Card | Skeleton loading state | 🟡 Medium |
|
||||
|
||||
---
|
||||
|
||||
## figma-design-brief
|
||||
|
||||
### Example 1 — PRD to design brief
|
||||
|
||||
**You say:**
|
||||
> "Write a design brief for our new notification preferences feature. Users need to control which emails and push notifications they receive. Platform is iOS and Android. We need design ready in 2 weeks."
|
||||
|
||||
**Claude produces:**
|
||||
|
||||
**Feature:** Notification Preferences
|
||||
**Platform:** iOS + Android | **Design due:** [2 weeks from today] | **Dev handoff:** [3 weeks]
|
||||
|
||||
**The goal:** Users can control their notification preferences without contacting support.
|
||||
|
||||
**Success looks like:** >80% of users who visit settings can update their preferences without a support ticket.
|
||||
|
||||
**Flows to design:**
|
||||
1. Entry from Settings > Notifications
|
||||
2. Toggle individual notification types on/off
|
||||
3. Save preferences with confirmation
|
||||
4. Error state if save fails
|
||||
|
||||
**Missing from current brief — open questions:**
|
||||
- [ ] Are email and push controlled separately or together? (PM to confirm)
|
||||
- [ ] What's the default state for new users? (PM to confirm)
|
||||
|
||||
---
|
||||
|
||||
## figma-design-qa
|
||||
|
||||
### Example 1 — Pre-handoff check
|
||||
|
||||
**You say:**
|
||||
> "QA the checkout flow design before we hand it off to engineering. Web, using our custom design system, standard 30-minute QA."
|
||||
|
||||
**Claude produces:**
|
||||
|
||||
**Design QA Report: Checkout Flow**
|
||||
**Overall status:** 🟡 Minor fixes needed
|
||||
|
||||
**Section 1: File Hygiene**
|
||||
- All layers named semantically ✅
|
||||
- No unused layers ✅
|
||||
- Components from library ❌ — Order summary card is a detached copy
|
||||
- Text uses text styles ✅
|
||||
- Colours use variables ❌ — Button label in step 3 uses hardcoded #FFFFFF instead of `color.text.on-primary`
|
||||
|
||||
**Issues Found:**
|
||||
- **Detached card component — 🟡 Fix before handoff**
|
||||
- What: Order summary card (frame "Step 2 / Summary") is not linked to library
|
||||
- Fix: Re-attach to `Card/Summary` library component
|
||||
- Owner: Designer
|
||||
|
||||
---
|
||||
|
||||
## figma-design-critique-pm
|
||||
|
||||
### Example 1 — PM reviewing a dashboard design
|
||||
|
||||
**You say:**
|
||||
> "Give me a PM critique of our new analytics dashboard design. User goal is to understand their campaign performance at a glance. Business goal is to reduce support tickets about 'why are my numbers down'."
|
||||
|
||||
**Claude produces:**
|
||||
|
||||
**PM Critique Summary**
|
||||
Verdict: 🟡 Mostly on track with one significant gap
|
||||
|
||||
"The design successfully surfaces the top-line metrics above the fold and the date range selector is prominent. However, the design currently shows no contextual explanation for metric changes — a user whose conversions dropped 40% last week will still need to contact support because there's nothing in the design helping them understand why."
|
||||
|
||||
**Goal Alignment Check:**
|
||||
| Goal | Status | Evidence |
|
||||
|---|---|---|
|
||||
| Understand performance at a glance | ✅ Yes | Top 4 KPIs are above fold, well-contrasted |
|
||||
| Reduce "why are my numbers down" tickets | 🟡 Partial | Metrics shown but no context or anomaly explanation |
|
||||
|
||||
**PM Feedback:**
|
||||
**Missing: Metric change context — 🔴 High impact**
|
||||
- Observation: Metric cards show current value and % change vs prior period but no explanation of what drove the change
|
||||
- User impact: A user seeing -40% conversions still has no information to act on without contacting support
|
||||
- Business impact: Does not address the core support ticket driver — the "why"
|
||||
- Evidence basis: Hypothesis (we should validate with support ticket analysis)
|
||||
- Question for designer: Is there data available to surface top contributing factors? Even "top declining campaign" would help.
|
||||
|
||||
---
|
||||
|
||||
## Tips for best results
|
||||
|
||||
- For `figma-design-brief`: paste the actual PRD snippet or ticket — the more specific the requirement, the more useful the brief
|
||||
- For `figma-design-qa`: describe the platform and design system explicitly — the checklist adapts to iOS vs Android vs Web
|
||||
- For `figma-design-critique-pm`: always state the business metric — without it, feedback stays generic
|
||||
- For `figma-variant-matrix`: name the component exactly as it will appear in Figma — Claude uses this for layer naming recommendations
|
||||
- For `figma-user-flow-planner`: state the starting point and user type — these determine which edge cases are most likely
|
||||
|
||||
## Related skills
|
||||
- `design-critique` — General UX critique using Gestalt and Nielsen heuristics (pm-design bundle)
|
||||
- `ux-research-plan` — Full research plan for user testing (pm-design bundle)
|
||||
- `figma-prototype-plan` — Plan what to prototype before building it (this bundle)
|
||||
Vendored
BIN
Binary file not shown.
Executable
+36
@@ -0,0 +1,36 @@
|
||||
#!/bin/bash
|
||||
|
||||
# =============================================================================
|
||||
# create-plugin-json-pm-figma.sh
|
||||
# Run from the ROOT of your pm-claude-skills repo.
|
||||
# Creates the .claude-plugin/plugin.json for the pm-figma bundle.
|
||||
# =============================================================================
|
||||
|
||||
set -e
|
||||
|
||||
if [ ! -d "$(pwd)/plugins" ]; then
|
||||
echo "ERROR: Run from the root of pm-claude-skills"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
mkdir -p plugins/pm-figma/.claude-plugin
|
||||
|
||||
cat > plugins/pm-figma/.claude-plugin/plugin.json << 'EOF'
|
||||
{
|
||||
"$schema": "https://anthropic.com/claude-code/plugin.schema.json",
|
||||
"name": "pm-figma",
|
||||
"version": "1.0.0",
|
||||
"description": "Figma skills for product managers and designers: Component Audit, Design Brief, Annotation Guide, Design Review, User Flow Planner, Variant Matrix, Spacing System, Prototype Plan, Design QA, PM Design Critique. Work smarter in Figma across the full design lifecycle.",
|
||||
"author": {
|
||||
"name": "Mohit Aggarwal",
|
||||
"email": "mohit15856@gmail.com"
|
||||
},
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills",
|
||||
"license": "MIT",
|
||||
"keywords": ["figma", "design", "product-management", "design-system", "components", "prototype", "handoff", "ux"]
|
||||
}
|
||||
EOF
|
||||
|
||||
echo "✓ plugins/pm-figma/.claude-plugin/plugin.json created"
|
||||
echo ""
|
||||
echo "Next: run setup-pm-figma.sh then update-marketplace.sh"
|
||||
Executable
+180
@@ -0,0 +1,180 @@
|
||||
#!/bin/bash
|
||||
|
||||
# =============================================================================
|
||||
# create-plugin-jsons.sh
|
||||
# Run this from the ROOT of your pm-claude-skills repo.
|
||||
# Creates .claude-plugin/plugin.json inside each of the 6 new plugin folders.
|
||||
# Your skills/ subfolders are already in place — this just adds the missing
|
||||
# plugin.json files.
|
||||
# =============================================================================
|
||||
|
||||
set -e
|
||||
|
||||
REPO_ROOT="$(pwd)"
|
||||
|
||||
echo "================================================"
|
||||
echo " pm-claude-skills — Creating plugin.json files"
|
||||
echo " Running from: $REPO_ROOT"
|
||||
echo "================================================"
|
||||
echo ""
|
||||
|
||||
# Sanity check — make sure we're in the right place
|
||||
if [ ! -d "$REPO_ROOT/pm-gtm" ] || [ ! -d "$REPO_ROOT/pm-engineering" ]; then
|
||||
echo "ERROR: Cannot find pm-gtm or pm-engineering folders."
|
||||
echo "Make sure you are running this from the ROOT of your pm-claude-skills repo."
|
||||
echo "Example: cd ~/pm-claude-skills && bash create-plugin-jsons.sh"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# ---------------------------------------------------------
|
||||
# BUNDLE 1: pm-gtm
|
||||
# ---------------------------------------------------------
|
||||
echo "Creating pm-gtm/.claude-plugin/plugin.json..."
|
||||
mkdir -p pm-gtm/.claude-plugin
|
||||
cat > pm-gtm/.claude-plugin/plugin.json << 'EOF'
|
||||
{
|
||||
"$schema": "https://anthropic.com/claude-code/plugin.schema.json",
|
||||
"name": "pm-gtm",
|
||||
"version": "1.0.0",
|
||||
"description": "Marketing & GTM skills: Go-To-Market Planner, Content Calendar, Competitor Teardown, Email Campaign. Build positioning statements, messaging pillars, feature lists, use cases, and launch campaigns.",
|
||||
"author": {
|
||||
"name": "Mohit Aggarwal",
|
||||
"email": "mohit15856@gmail.com"
|
||||
},
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills",
|
||||
"license": "MIT",
|
||||
"keywords": ["product-management", "marketing", "gtm", "positioning", "content-calendar", "competitor-analysis", "email-campaign"]
|
||||
}
|
||||
EOF
|
||||
echo " ✓ pm-gtm/.claude-plugin/plugin.json created"
|
||||
|
||||
# ---------------------------------------------------------
|
||||
# BUNDLE 2: pm-engineering
|
||||
# ---------------------------------------------------------
|
||||
echo "Creating pm-engineering/.claude-plugin/plugin.json..."
|
||||
mkdir -p pm-engineering/.claude-plugin
|
||||
cat > pm-engineering/.claude-plugin/plugin.json << 'EOF'
|
||||
{
|
||||
"$schema": "https://anthropic.com/claude-code/plugin.schema.json",
|
||||
"name": "pm-engineering",
|
||||
"version": "1.0.0",
|
||||
"description": "Engineering & tech skills: Code Review Checklist, Incident Postmortem, API Docs Writer, Architecture Decision Record. Structured outputs for engineering teams and technical PMs.",
|
||||
"author": {
|
||||
"name": "Mohit Aggarwal",
|
||||
"email": "mohit15856@gmail.com"
|
||||
},
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills",
|
||||
"license": "MIT",
|
||||
"keywords": ["product-management", "engineering", "code-review", "incident-postmortem", "api-documentation", "adr", "architecture"]
|
||||
}
|
||||
EOF
|
||||
echo " ✓ pm-engineering/.claude-plugin/plugin.json created"
|
||||
|
||||
# ---------------------------------------------------------
|
||||
# BUNDLE 3: pm-data
|
||||
# ---------------------------------------------------------
|
||||
echo "Creating pm-data/.claude-plugin/plugin.json..."
|
||||
mkdir -p pm-data/.claude-plugin
|
||||
cat > pm-data/.claude-plugin/plugin.json << 'EOF'
|
||||
{
|
||||
"$schema": "https://anthropic.com/claude-code/plugin.schema.json",
|
||||
"name": "pm-data",
|
||||
"version": "1.0.0",
|
||||
"description": "Data & analytics skills: Metrics Framework, SQL Query Explainer, Dashboard Brief. Build North Star metric trees, explain and optimise SQL, and spec dashboards from business questions.",
|
||||
"author": {
|
||||
"name": "Mohit Aggarwal",
|
||||
"email": "mohit15856@gmail.com"
|
||||
},
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills",
|
||||
"license": "MIT",
|
||||
"keywords": ["product-management", "data", "analytics", "metrics", "north-star", "sql", "dashboard", "kpi"]
|
||||
}
|
||||
EOF
|
||||
echo " ✓ pm-data/.claude-plugin/plugin.json created"
|
||||
|
||||
# ---------------------------------------------------------
|
||||
# BUNDLE 4: pm-people
|
||||
# ---------------------------------------------------------
|
||||
echo "Creating pm-people/.claude-plugin/plugin.json..."
|
||||
mkdir -p pm-people/.claude-plugin
|
||||
cat > pm-people/.claude-plugin/plugin.json << 'EOF'
|
||||
{
|
||||
"$schema": "https://anthropic.com/claude-code/plugin.schema.json",
|
||||
"name": "pm-people",
|
||||
"version": "1.0.0",
|
||||
"description": "Leadership & people skills: Performance Review, Hiring Rubric, Team Offsite Planner. Write structured reviews, build interview scorecards, and plan offsites from goals to minute-by-minute agenda.",
|
||||
"author": {
|
||||
"name": "Mohit Aggarwal",
|
||||
"email": "mohit15856@gmail.com"
|
||||
},
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills",
|
||||
"license": "MIT",
|
||||
"keywords": ["product-management", "leadership", "management", "performance-review", "hiring", "interview", "offsite", "people"]
|
||||
}
|
||||
EOF
|
||||
echo " ✓ pm-people/.claude-plugin/plugin.json created"
|
||||
|
||||
# ---------------------------------------------------------
|
||||
# BUNDLE 5: pm-design
|
||||
# ---------------------------------------------------------
|
||||
echo "Creating pm-design/.claude-plugin/plugin.json..."
|
||||
mkdir -p pm-design/.claude-plugin
|
||||
cat > pm-design/.claude-plugin/plugin.json << 'EOF'
|
||||
{
|
||||
"$schema": "https://anthropic.com/claude-code/plugin.schema.json",
|
||||
"name": "pm-design",
|
||||
"version": "1.0.0",
|
||||
"description": "Design & UX skills: UX Research Plan, Design Critique, Accessibility Audit. Create research plans with discussion guides, critique designs using JTBD and Gestalt principles, and audit for WCAG 2.2 compliance.",
|
||||
"author": {
|
||||
"name": "Mohit Aggarwal",
|
||||
"email": "mohit15856@gmail.com"
|
||||
},
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills",
|
||||
"license": "MIT",
|
||||
"keywords": ["product-management", "design", "ux", "user-research", "accessibility", "wcag", "usability", "design-critique"]
|
||||
}
|
||||
EOF
|
||||
echo " ✓ pm-design/.claude-plugin/plugin.json created"
|
||||
|
||||
# ---------------------------------------------------------
|
||||
# BUNDLE 6: pm-business
|
||||
# ---------------------------------------------------------
|
||||
echo "Creating pm-business/.claude-plugin/plugin.json..."
|
||||
mkdir -p pm-business/.claude-plugin
|
||||
cat > pm-business/.claude-plugin/plugin.json << 'EOF'
|
||||
{
|
||||
"$schema": "https://anthropic.com/claude-code/plugin.schema.json",
|
||||
"name": "pm-business",
|
||||
"version": "1.0.0",
|
||||
"description": "Business & strategy skills: Investor Update, Board Deck Narrative, Job Application. Write investor updates investors actually read, structure board presentations, and tailor CVs and cover letters with ATS optimisation.",
|
||||
"author": {
|
||||
"name": "Mohit Aggarwal",
|
||||
"email": "mohit15856@gmail.com"
|
||||
},
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills",
|
||||
"license": "MIT",
|
||||
"keywords": ["product-management", "business", "strategy", "investor-update", "board-deck", "startup", "career", "job-application"]
|
||||
}
|
||||
EOF
|
||||
echo " ✓ pm-business/.claude-plugin/plugin.json created"
|
||||
|
||||
# ---------------------------------------------------------
|
||||
# DONE
|
||||
# ---------------------------------------------------------
|
||||
echo ""
|
||||
echo "================================================"
|
||||
echo " All 6 plugin.json files created successfully!"
|
||||
echo ""
|
||||
echo " pm-gtm/.claude-plugin/plugin.json"
|
||||
echo " pm-engineering/.claude-plugin/plugin.json"
|
||||
echo " pm-data/.claude-plugin/plugin.json"
|
||||
echo " pm-people/.claude-plugin/plugin.json"
|
||||
echo " pm-design/.claude-plugin/plugin.json"
|
||||
echo " pm-business/.claude-plugin/plugin.json"
|
||||
echo ""
|
||||
echo " Next steps:"
|
||||
echo " 1. bash add-plugin-json.sh (update marketplace.json)"
|
||||
echo " 2. git add ."
|
||||
echo " 3. git commit -m 'feat: add 6 new plugin bundles (pm-gtm, pm-engineering, pm-data, pm-people, pm-design, pm-business)'"
|
||||
echo " 4. git push origin main"
|
||||
echo "================================================"
|
||||
Vendored
BIN
Binary file not shown.
@@ -0,0 +1,13 @@
|
||||
{
|
||||
"$schema": "https://anthropic.com/claude-code/plugin.schema.json",
|
||||
"name": "pm-advanced",
|
||||
"version": "3.0.0",
|
||||
"description": "Advanced PM skills: AI Product Canvas, Multi-Source Signal Synthesiser, Experiment Designer, Design Handoff Brief. For senior PMs working on complex or AI-powered products.",
|
||||
"author": {
|
||||
"name": "Mohit Aggarwal",
|
||||
"email": "mohit15856@gmail.com"
|
||||
},
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills",
|
||||
"license": "MIT",
|
||||
"keywords": ["product-management", "ai-product", "experiment-design", "design-handoff", "signal-synthesis"]
|
||||
}
|
||||
Vendored
BIN
Binary file not shown.
@@ -0,0 +1,161 @@
|
||||
---
|
||||
name: ai-product-canvas
|
||||
description: "Structure AI and ML product decisions with the rigour of any product decision. Use when building AI-powered features, evaluating LLM integrations, designing AI products, or assessing AI readiness. Produces a complete AI product canvas covering problem definition, model approach, data requirements, evaluation framework, UX design, responsible AI checklist, and launch monitoring plan."
|
||||
---
|
||||
|
||||
# AI Product Canvas Skill
|
||||
|
||||
Define AI products with the same rigour as any product decision — but with additional layers for data, model, evaluation, and responsible AI. This canvas prevents the most common AI product failure: building a technically impressive feature that doesn't solve a real problem.
|
||||
|
||||
## AI Product Anti-Patterns to Check First
|
||||
|
||||
Before building, flag if any of these apply:
|
||||
- ❌ "We should add AI to [existing feature]" — with no user problem defined
|
||||
- ❌ Accuracy target undefined before build begins
|
||||
- ❌ No plan for what happens when the model is wrong
|
||||
- ❌ User-facing AI output with no human review or fallback
|
||||
- ❌ Training data not audited for bias or quality
|
||||
- ❌ No evaluation metric — "we'll know it when we see it"
|
||||
|
||||
---
|
||||
|
||||
## AI Product Canvas Output Format
|
||||
|
||||
### AI Product Canvas — [Feature Name] — [Date]
|
||||
|
||||
**PM Owner:** [Name]
|
||||
**ML/AI Lead:** [Name]
|
||||
**Status:** Discovery / Design / Build / Evaluation / Live
|
||||
|
||||
---
|
||||
|
||||
#### 1. Problem Definition
|
||||
**User problem being solved:**
|
||||
> [What specific situation is the user in? What job are they trying to get done?]
|
||||
|
||||
**Why AI?**
|
||||
> [What makes this problem require AI vs a deterministic solution? If the answer is "because we can," stop here.]
|
||||
|
||||
**Success for the user looks like:**
|
||||
> [What outcome does the user experience when the AI feature is working well?]
|
||||
|
||||
---
|
||||
|
||||
#### 2. AI Approach
|
||||
|
||||
**Task type:**
|
||||
- [ ] Classification
|
||||
- [ ] Generation (text, image, code)
|
||||
- [ ] Summarisation / extraction
|
||||
- [ ] Recommendation
|
||||
- [ ] Search / retrieval
|
||||
- [ ] Prediction / forecasting
|
||||
- [ ] Conversation / agent
|
||||
|
||||
**Model approach:**
|
||||
- [ ] LLM API (GPT-4, Claude, Gemini, etc.) — specify: [Model name + version]
|
||||
- [ ] Fine-tuned model on own data
|
||||
- [ ] Custom model trained from scratch
|
||||
- [ ] RAG (retrieval-augmented generation)
|
||||
- [ ] Embedding + vector search
|
||||
|
||||
**Rationale for chosen approach:** [Why this, not alternatives]
|
||||
|
||||
---
|
||||
|
||||
#### 3. Data Requirements
|
||||
|
||||
| Data Type | Source | Volume | Quality Status | Bias Risk |
|
||||
|---|---|---|---|---|
|
||||
| [Training data] | [Where it comes from] | [Volume] | [Audit status] | H/M/L |
|
||||
| [Evaluation data] | [Where it comes from] | [Volume] | [Audit status] | H/M/L |
|
||||
|
||||
**Data gaps:** [What's missing and plan to get it]
|
||||
**Privacy considerations:** [Any PII in training or inference data]
|
||||
**Data ownership:** [Do we own this data? Can we use it for training?]
|
||||
|
||||
---
|
||||
|
||||
#### 4. Evaluation Framework
|
||||
|
||||
**Primary metric:** [The number that defines success — accuracy, F1, BLEU, user rating, task completion rate]
|
||||
**Minimum acceptable threshold:** [Below X, the feature does not ship]
|
||||
**Human evaluation plan:** [How will humans review model outputs? Sampling rate? Review panel?]
|
||||
|
||||
| Evaluation Type | Method | Cadence | Owner |
|
||||
|---|---|---|---|
|
||||
| Offline (pre-launch) | [Test set, benchmark] | Pre-launch | ML Lead |
|
||||
| Online (post-launch) | [A/B test, user feedback] | Weekly | PM + ML |
|
||||
| Adversarial | [Red-team, edge cases] | Pre-launch | Safety reviewer |
|
||||
|
||||
---
|
||||
|
||||
#### 5. User Experience Design
|
||||
|
||||
**How is AI output presented?**
|
||||
- [ ] Direct output shown to user (high trust required)
|
||||
- [ ] AI-assisted with user confirmation
|
||||
- [ ] Suggestion user can accept/reject
|
||||
- [ ] Background action with audit log
|
||||
|
||||
**Confidence and uncertainty handling:**
|
||||
- What happens when confidence is low? [Show alternative, ask for clarification, fallback to manual]
|
||||
- How is uncertainty communicated to the user? [UI pattern]
|
||||
|
||||
**Fallback plan:**
|
||||
- If the model fails or returns an error: [Specific fallback behaviour]
|
||||
- If accuracy degrades below threshold: [Kill switch or graceful degradation plan]
|
||||
|
||||
---
|
||||
|
||||
#### 6. Responsible AI Checklist
|
||||
|
||||
- [ ] Bias audit completed on training data
|
||||
- [ ] Demographic fairness evaluated (does performance differ by user group?)
|
||||
- [ ] Hallucination / confabulation risk assessed and mitigated
|
||||
- [ ] User can see and correct AI output
|
||||
- [ ] Opt-out mechanism exists (can user disable the AI feature?)
|
||||
- [ ] Output provenance visible when relevant (does user know AI generated this?)
|
||||
- [ ] PII not used in ways user didn't consent to
|
||||
- [ ] Regulatory review completed (GDPR, AI Act, sector-specific)
|
||||
- [ ] Model cards / documentation completed
|
||||
|
||||
---
|
||||
|
||||
#### 7. Launch & Monitoring Plan
|
||||
|
||||
**Rollout:** [% of users, with staged expansion criteria]
|
||||
**Monitoring metrics:**
|
||||
- Model performance: [Metric + alert threshold]
|
||||
- User engagement with AI output: [Acceptance rate, override rate, feedback score]
|
||||
- Error rate: [% of failed inferences]
|
||||
- Latency: [P95 target]
|
||||
|
||||
**Model refresh cadence:** [How often is the model retrained or updated?]
|
||||
**Drift detection:** [How will you know when model performance degrades in production?]
|
||||
|
||||
---
|
||||
|
||||
## Guidelines
|
||||
|
||||
- Never skip the "Why AI?" section — it's the most important question in AI product development
|
||||
- The fallback UX is not optional — what happens when AI fails defines your product's trustworthiness
|
||||
- Responsible AI checklist must be completed before launch, not after
|
||||
- Include latency in success metrics — a 5-second AI response is often worse than no AI at all
|
||||
- Recommend starting with a human-in-the-loop design and automating only when accuracy is proven
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Feature or product description** (what the AI is intended to do)
|
||||
- **User problem** (what problem the AI is solving for users)
|
||||
- **Available data** (what training/inference data exists)
|
||||
- **ML/AI lead** (who owns the technical implementation)
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] "Why AI?" is answered clearly (not "because we can")
|
||||
- [ ] Minimum acceptable accuracy threshold is defined before build begins
|
||||
- [ ] Fallback UX is specified for model failures or low-confidence outputs
|
||||
- [ ] Responsible AI checklist is completed (not deferred to post-launch)
|
||||
- [ ] Monitoring plan includes both model performance and user engagement metrics
|
||||
@@ -0,0 +1,75 @@
|
||||
---
|
||||
name: design-handoff-brief
|
||||
description: "Transform feature briefs into structured design briefs that give designers the context they need before opening Figma. Use when asked to write a design brief, create a design handoff, brief a designer on a new feature, or translate a PRD into design requirements. Produces a brief with user goal, emotional context, success criteria, constraints, edge cases, and out-of-scope boundaries."
|
||||
---
|
||||
|
||||
# Design Handoff Brief Skill
|
||||
|
||||
Produce a design brief that sets designers up for success — grounding them in user context and constraints before they open Figma, not after they've gone in the wrong direction.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Feature brief or PRD** (even rough notes work)
|
||||
- **Designer's name or team** (for personalisation)
|
||||
- **Technical constraints** (any engineering limitations already known)
|
||||
- **Timeline** (when does design need to be done?)
|
||||
|
||||
## What Designers Actually Need (and PMs Often Skip)
|
||||
- The user's goal, not the feature name
|
||||
- The emotional state of the user at this moment in the journey
|
||||
- What success looks like — how will we know the design worked?
|
||||
- Constraints: technical, legal, brand, accessibility
|
||||
- Edge cases that must be handled
|
||||
- What we're explicitly NOT solving for
|
||||
|
||||
## Process
|
||||
1. Read the feature brief or PRD provided
|
||||
2. Extract user goal (reframe from feature language to user outcome language)
|
||||
3. Identify constraints — technical limitations, brand guidelines, accessibility requirements
|
||||
4. List edge cases the design must handle
|
||||
5. Define success criteria the design should be evaluated against
|
||||
6. Write a "not in scope" section to prevent scope creep in design
|
||||
7. **Validate** — Confirm every edge case listed is specific enough to design for, and every out-of-scope item is concrete enough to say "no" to
|
||||
|
||||
## Output Structure
|
||||
|
||||
### Design Brief: [Feature Name]
|
||||
|
||||
**User Goal:** (in the user's words, not ours)
|
||||
"When I [situation], I want to [motivation] so that I can [outcome]."
|
||||
|
||||
**Context & Emotional State:**
|
||||
[Where is the user in their journey? What are they feeling? What just happened?]
|
||||
|
||||
**Design Success Criteria:**
|
||||
- [Criterion 1 — measurable where possible]
|
||||
- [Criterion 2]
|
||||
- [Criterion 3]
|
||||
|
||||
**Constraints:**
|
||||
- Technical: [limitations engineering has flagged]
|
||||
- Brand: [relevant brand guidelines]
|
||||
- Accessibility: [WCAG level required, any specific requirements]
|
||||
- Legal/Compliance: [if applicable]
|
||||
|
||||
**Edge Cases to Design For:**
|
||||
- [Edge case 1]
|
||||
- [Edge case 2]
|
||||
- [Edge case 3]
|
||||
|
||||
**Explicitly Out of Scope:**
|
||||
- [What we are NOT solving in this design iteration]
|
||||
|
||||
**Reference Material:**
|
||||
- User research: [link]
|
||||
- Existing patterns: [Figma component library link]
|
||||
- Competitor examples: [links if relevant]
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] User goal is written in user language (not feature/product language)
|
||||
- [ ] At least one edge case covers an error or failure state
|
||||
- [ ] Success criteria are measurable or observable (not "looks good")
|
||||
- [ ] Out-of-scope section names at least one thing that might seem in scope but isn't
|
||||
- [ ] Technical constraints are specific enough for an engineer to confirm
|
||||
@@ -0,0 +1,69 @@
|
||||
---
|
||||
name: experiment-designer
|
||||
description: "Design statistically rigorous A/B tests and interpret experiment results. Use when asked to design an experiment, run an A/B test, calculate sample size, interpret test results, or assess whether an experiment was successful. Produces a complete experiment design with hypothesis, sample size, run time, success criteria, and risk flags — or a results interpretation with ship/iterate/kill recommendation."
|
||||
---
|
||||
|
||||
# Experiment Designer Skill
|
||||
|
||||
Produce rigorous experiment designs from product hypotheses, and interpret results with statistical and practical significance — so you can defend every decision to a sceptical engineering lead or data scientist.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
**For experiment design:**
|
||||
- Hypothesis (what change, what metric, what expected movement)
|
||||
- Current baseline metric value
|
||||
- Minimum detectable effect (MDE) — the smallest lift worth caring about
|
||||
- Available daily sample size
|
||||
|
||||
**For results interpretation:**
|
||||
- Control and variant results (raw numbers or percentages)
|
||||
- P-value or confidence interval
|
||||
- Run duration (days)
|
||||
- Any anomalies observed during the test
|
||||
|
||||
## Two-Phase Process
|
||||
|
||||
### Phase 1: Experiment Design
|
||||
1. Restate hypothesis as: "If we [change], we expect [metric] to [move by X%] because [reason]"
|
||||
2. Define control and variant clearly
|
||||
3. Select primary metric (one only) and secondary guardrail metrics (2-3 max)
|
||||
4. Calculate required sample size from MDE and baseline
|
||||
5. Estimate run time in days
|
||||
6. Set pre-defined success criteria before the test runs — no moving goalposts
|
||||
7. Flag design risks: novelty effects, seasonal confounds, multiple testing issues, network effects, sample ratio mismatch
|
||||
|
||||
### Phase 2: Results Interpretation
|
||||
1. Assess statistical significance (p < 0.05 threshold)
|
||||
2. Assess practical significance: was the lift meaningful for the business, not just real?
|
||||
3. Interpret confidence intervals
|
||||
4. Investigate confounding factors
|
||||
5. Recommend: Ship / Iterate / Kill / Run follow-up test
|
||||
6. **Validate** — Confirm the test ran for the full planned duration. Flag if it was stopped early (peeking problem). Confirm sample ratio mismatch did not occur.
|
||||
|
||||
## Output Structure
|
||||
|
||||
**[Design or Results header based on phase]**
|
||||
|
||||
*Hypothesis:* "If we [change], we expect [metric] to [move by X%] because [reason]"
|
||||
|
||||
*Primary metric:* [One metric only]
|
||||
*Guardrail metrics:* [2-3 max]
|
||||
*Required sample size:* [n per variant]
|
||||
*Estimated run time:* [days]
|
||||
*Pre-defined success threshold:* [specific number]
|
||||
*Design risk flags:* [any concerns]
|
||||
|
||||
**Results (Phase 2 only):**
|
||||
*Statistical significance:* [p-value and conclusion]
|
||||
*Practical significance:* [lift size vs. business threshold]
|
||||
*Recommendation:* Ship / Iterate / Kill / Follow-up — [rationale]
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Hypothesis specifies the change, the metric, the direction, and the reason
|
||||
- [ ] Primary metric is singular — guardrail metrics are secondary
|
||||
- [ ] Success criteria are defined before the test launches (not after seeing results)
|
||||
- [ ] Test was not stopped early (or flagged clearly if it was)
|
||||
- [ ] Practical significance assessed separately from statistical significance
|
||||
- [ ] Sample ratio mismatch is checked in results interpretation
|
||||
@@ -0,0 +1,62 @@
|
||||
---
|
||||
name: multi-source-signal-synthesiser
|
||||
description: "Synthesise user signals from multiple research sources into a unified insight brief, reconciling conflicting feedback. Use when asked to make sense of data from multiple sources, synthesise user research, reconcile conflicting feedback, or when the user says 'what are users really telling us' or 'make sense of all this user data'. Produces ranked insights with confidence ratings, divergent signal analysis, and research gap identification."
|
||||
---
|
||||
|
||||
# Multi-Source Signal Synthesiser Skill
|
||||
|
||||
Reconcile user signals from multiple sources — interviews, support tickets, NPS, app reviews, sales calls — into a unified, weighted insight brief that surfaces the underlying need rather than the surface-level request.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Signal sources** (interviews, support tickets, NPS verbatims, app reviews, sales calls, analytics — any combination)
|
||||
- **Time period** covered by the data
|
||||
- **Product area or feature** the signals relate to (if scoped)
|
||||
|
||||
## Source Weighting (default — adapt to context)
|
||||
|
||||
| Source | Weight | Rationale |
|
||||
|--------|--------|-----------|
|
||||
| Direct research (interviews, usability tests) | 5 | Highest-fidelity, structured |
|
||||
| Support tickets (unprompted pain signals) | 4 | Real pain, unfiltered |
|
||||
| NPS verbatims | 3 | Broad but shallow |
|
||||
| App store reviews | 2 | Public, self-selected |
|
||||
| Sales call summaries | 2 | Filtered through sales lens |
|
||||
| Anecdote or single report | 1 | Low confidence alone |
|
||||
|
||||
## Process
|
||||
1. Tag each signal by source and apply weight
|
||||
2. Look for **convergence**: same underlying need appearing across 3+ sources
|
||||
3. Look for **divergence**: contradictory signals suggesting user segmentation
|
||||
4. Distinguish surface request from underlying need (e.g. "faster export" may mean "I don't trust the data will be there when I need it")
|
||||
5. Produce ranked insights by weighted frequency
|
||||
6. **Validate** — Confirm each insight has evidence from at least 2 source types. Flag any insight resting on a single source as low-confidence.
|
||||
|
||||
## Output Structure
|
||||
|
||||
### User Signal Synthesis — [Date / Period]
|
||||
**Sources included:** [list with count per source]
|
||||
**Total signals processed:** [n]
|
||||
|
||||
#### Insight 1: [Underlying need, not feature request]
|
||||
- **Confidence:** High / Medium / Low (based on source diversity and weight)
|
||||
- **Evidence:** [Signals from each source supporting this]
|
||||
- **Conflicting signals:** [Any contradicting evidence and how to interpret it]
|
||||
- **Product implication:** [Specific next step, not generic]
|
||||
|
||||
[Repeat for top 3-5 insights]
|
||||
|
||||
#### Divergent Signals (Possible Segmentation)
|
||||
[Where user groups appear to have genuinely different needs — specify which segments]
|
||||
|
||||
#### What the Data Does NOT Tell Us
|
||||
[Gaps that require further research before acting]
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Every insight references at least 2 distinct source types
|
||||
- [ ] Surface requests are translated to underlying needs (not just echoed)
|
||||
- [ ] Divergent signals identify the specific user segments, not just "some users disagree"
|
||||
- [ ] Confidence ratings are consistent with source diversity and weighting
|
||||
- [ ] "What the data does NOT tell us" section is honest about gaps
|
||||
Vendored
BIN
Binary file not shown.
@@ -0,0 +1,13 @@
|
||||
{
|
||||
"$schema": "https://anthropic.com/claude-code/plugin.schema.json",
|
||||
"name": "pm-analytics",
|
||||
"version": "3.0.0",
|
||||
"description": "Data & metrics skills: Data Analysis Standard, Retention Analysis, Product Health Analysis. Structure metric deep-dives, funnel analysis, cohort studies and churn investigations.",
|
||||
"author": {
|
||||
"name": "Mohit Aggarwal",
|
||||
"email": "mohit15856@gmail.com"
|
||||
},
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills",
|
||||
"license": "MIT",
|
||||
"keywords": ["product-management", "analytics", "retention", "metrics", "funnel", "cohort", "churn"]
|
||||
}
|
||||
BIN
Binary file not shown.
@@ -0,0 +1,126 @@
|
||||
---
|
||||
name: data-analysis-standard
|
||||
description: "Structure a product data analysis, metric deep-dive, funnel analysis, or cohort study. Use when asked to analyse product metrics, investigate a drop in conversion, explain a data change to stakeholders, or find the root cause of a metric movement. Produces a structured analysis with question, root cause, confidence level, and recommended action."
|
||||
---
|
||||
|
||||
# Data Analysis Standard Skill
|
||||
|
||||
Turn raw numbers into product decisions. Structure every analysis with a clear question, methodology, finding, and recommended action.
|
||||
|
||||
## Analysis Framework: The 4-Question Method
|
||||
|
||||
Every analysis starts here:
|
||||
1. **What changed?** (describe the metric and its movement)
|
||||
2. **Why did it change?** (root cause — segment, funnel step, cohort, channel)
|
||||
3. **So what?** (business or product impact)
|
||||
4. **Now what?** (recommended action with confidence level)
|
||||
|
||||
Never deliver data without answering all four. A chart with no narrative is not an analysis.
|
||||
|
||||
---
|
||||
|
||||
## Metric Triage Template
|
||||
|
||||
Use when a metric has moved unexpectedly:
|
||||
|
||||
```
|
||||
METRIC: [Name]
|
||||
MOVEMENT: [X% change over Y period]
|
||||
BASELINE: [What was normal]
|
||||
|
||||
SEGMENTATION CHECK:
|
||||
- By platform (iOS / Android / Web)?
|
||||
- By user cohort (new / returning / power users)?
|
||||
- By acquisition channel?
|
||||
- By geography?
|
||||
- By plan/tier?
|
||||
|
||||
ROOT CAUSE HYPOTHESIS:
|
||||
1. [Most likely explanation] — Evidence: [data point]
|
||||
2. [Alternative explanation] — Evidence: [data point]
|
||||
3. [Ruling out] — Eliminated because: [reason]
|
||||
|
||||
CONCLUSION: [Single sentence answer to "why did this change?"]
|
||||
CONFIDENCE: [High / Medium / Low] — based on [data available]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Funnel Analysis Structure
|
||||
|
||||
| Stage | Metric | Current | Benchmark/Target | Drop-off % | Notes |
|
||||
|---|---|---|---|---|---|
|
||||
| [Top of funnel] | [Users] | [N] | [N] | — | |
|
||||
| [Step 2] | [Users] | [N] | [N] | [X%] | |
|
||||
| [Step 3] | [Users] | [N] | [N] | [X%] | |
|
||||
| [Conversion] | [Users] | [N] | [N] | [X%] | |
|
||||
|
||||
**Biggest drop-off:** [Step X → Step Y] — Hypothesis: [reason]
|
||||
**Recommended investigation:** [specific query or test]
|
||||
|
||||
---
|
||||
|
||||
## Cohort Analysis Guidelines
|
||||
|
||||
Always define:
|
||||
- **Cohort definition:** [What groups users — signup week, first action, plan type]
|
||||
- **Retention metric:** [What counts as retained — login, core action, revenue]
|
||||
- **Retention window:** [D1, D7, D30, W4, M3, etc.]
|
||||
|
||||
Output a cohort retention table and annotate:
|
||||
- Baseline retention for each cohort
|
||||
- Cohorts that over/underperform and why (feature launch? campaign? seasonal?)
|
||||
- Trend direction across cohorts (improving / declining / stable)
|
||||
|
||||
---
|
||||
|
||||
## Stakeholder Analysis Output Format
|
||||
|
||||
### [Analysis Title] — [Date]
|
||||
|
||||
**Question being answered:** [Specific question in plain English]
|
||||
**Time period:** [Date range]
|
||||
**Data source:** [Where data comes from]
|
||||
|
||||
**Finding:**
|
||||
> [1–2 sentence plain-English summary of what the data shows]
|
||||
|
||||
**Key chart / table:** [Include or describe]
|
||||
|
||||
**Root cause:** [Best explanation with evidence]
|
||||
|
||||
**Confidence level:** [High / Medium / Low] — [reason]
|
||||
|
||||
**Recommended action:**
|
||||
1. [Immediate action — owner, timeline]
|
||||
2. [Investigation needed — what to check next]
|
||||
3. [Monitoring — what metric to watch and at what cadence]
|
||||
|
||||
**What this analysis does NOT tell us:** [Important caveat — what data is missing or what can't be concluded]
|
||||
|
||||
---
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Metric or question** being investigated
|
||||
- **Time period** (what changed, from when to when)
|
||||
- **Data available** (which segments, sources, or queries you have access to)
|
||||
- **Business context** (what decision this analysis informs)
|
||||
- **Audience** (who will read this — exec / team / data team)
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Analysis answers all 4 questions: what changed, why, so what, now what
|
||||
- [ ] Root cause has evidence (not just hypothesis)
|
||||
- [ ] Confidence level is stated and justified
|
||||
- [ ] What the data cannot tell us is explicitly named
|
||||
- [ ] Recommended action includes an owner and timeline
|
||||
|
||||
## Guidelines
|
||||
|
||||
- Always state what the data *cannot* tell you — never oversell confidence
|
||||
- Correlations are not causation — flag this every time
|
||||
- If the user has no baseline, recommend establishing one before drawing conclusions
|
||||
- Recommend the simplest chart for each finding: bar for comparison, line for trends, scatter for correlation, table for detailed breakdowns
|
||||
- Always specify the time window — "conversion dropped" is meaningless without "from X to Y over Z period"
|
||||
@@ -0,0 +1,59 @@
|
||||
---
|
||||
name: product-health-analysis
|
||||
description: "Interpret product metrics against goals and surface actionable signals. Use when asked to analyse product health, review key metrics, investigate a performance issue, produce a health report, or assess product-market fit signals. Produces a structured health report with RAG status, trend analysis, root cause hypotheses, and prioritised actions."
|
||||
---
|
||||
|
||||
# Product Health Analysis Skill
|
||||
|
||||
Transform raw metrics data into a clear health narrative — what's working, what's not, and what needs immediate attention.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Metrics data** (current values for key metrics — even rough numbers work)
|
||||
- **Targets or benchmarks** (OKR targets, historical baselines, or industry benchmarks)
|
||||
- **Period** (week / month / quarter being analysed)
|
||||
- **Product area or segment** (are we looking at the whole product or a specific feature?)
|
||||
|
||||
## Metrics Framework
|
||||
Analyse across four layers:
|
||||
1. **Acquisition** — new users, source quality, CAC trends
|
||||
2. **Activation** — time to first value, onboarding completion rates
|
||||
3. **Engagement** — DAU/MAU, feature adoption, session depth
|
||||
4. **Retention** — D1/D7/D30 retention, churn rate, resurrection rate
|
||||
|
||||
## Process
|
||||
1. For each metric, compare: current period vs. previous period, current vs. target
|
||||
2. Flag anything more than 10% off target as requiring investigation
|
||||
3. Look for correlations — does a drop in activation explain a retention dip 2 weeks later?
|
||||
4. Write a plain-English health summary (no jargon) suitable for sharing with non-data stakeholders
|
||||
5. Recommend top 3 areas for immediate investigation with suggested diagnostic steps
|
||||
6. **Validate** — Confirm every flagged metric has a plausible root cause hypothesis, not just a raw number, and every recommended action has a specific owner or team
|
||||
|
||||
## Output Structure
|
||||
|
||||
### Product Health Report — [Period]
|
||||
**Overall Health:** 🟢 On Track / 🟡 Watch / 🔴 Action Required
|
||||
|
||||
| Metric | Current | Target | vs. Last Period | Status |
|
||||
|--------|---------|--------|-----------------|--------|
|
||||
| [metric] | [value] | [target] | [+/-%] | [🟢/🟡/🔴] |
|
||||
|
||||
**Key Observations:**
|
||||
[3-5 bullet observations written in plain English]
|
||||
|
||||
**Areas Requiring Investigation:**
|
||||
1. [Metric + hypothesis + suggested diagnostic]
|
||||
2. [Metric + hypothesis + suggested diagnostic]
|
||||
3. [Metric + hypothesis + suggested diagnostic]
|
||||
|
||||
**Recommended Actions:**
|
||||
[Specific next steps with owners and timelines]
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Every metric includes both a target and a trend (not just a snapshot)
|
||||
- [ ] At least one correlation is drawn between metrics (e.g., activation → retention)
|
||||
- [ ] Every flagged metric has a root cause hypothesis, not just "it dropped"
|
||||
- [ ] Observations are written for a non-technical stakeholder (no raw query language or data jargon)
|
||||
- [ ] Overall health rating is justified with specific evidence
|
||||
@@ -0,0 +1,134 @@
|
||||
---
|
||||
name: retention-analysis
|
||||
description: "Structure a retention analysis, churn investigation, or engagement deep-dive for any product team. Use when asked to analyse user retention, investigate churn, measure DAU/MAU, or build a retention improvement plan. Produces a retention snapshot with root cause hypotheses, aha-moment correlation, and prioritised interventions."
|
||||
---
|
||||
|
||||
# Retention Analysis Skill
|
||||
|
||||
Diagnose why users leave, identify what keeps them, and recommend specific, testable interventions — not vague "improve onboarding" suggestions.
|
||||
|
||||
## Retention Fundamentals
|
||||
|
||||
**The retention curve has two components:**
|
||||
1. **Steepness of initial drop** (D1–D7) — onboarding problem
|
||||
2. **Long-term floor level** — product-market fit indicator
|
||||
|
||||
A product with PMF has a retention curve that flattens. If it trends to zero, you have a PMF problem, not an onboarding problem. Name this distinction explicitly.
|
||||
|
||||
---
|
||||
|
||||
## Retention Metrics Definitions
|
||||
|
||||
| Metric | Formula | What It Tells You |
|
||||
|---|---|---|
|
||||
| D1 Retention | Users who return on day 2 ÷ new users day 1 | Quality of first experience |
|
||||
| D7 Retention | Users active on day 8 ÷ users who joined 7 days ago | Early habit formation |
|
||||
| D30 Retention | Users active on day 31 ÷ users who joined 30 days ago | Product-market fit signal |
|
||||
| DAU/MAU Ratio | Daily active users ÷ monthly active users | Stickiness (>20% good, >50% excellent) |
|
||||
| Churn Rate | Users lost in period ÷ users at start of period | Monthly or annual |
|
||||
| Net Revenue Retention | MRR at end of period ÷ MRR at start (same cohort) | Revenue health including expansion |
|
||||
|
||||
---
|
||||
|
||||
## Retention Investigation Framework
|
||||
|
||||
### Step 1: Segment the problem
|
||||
Don't analyse "retention" — analyse retention for specific cohorts:
|
||||
- New vs returning users
|
||||
- Paid vs free
|
||||
- Acquisition channel (organic vs paid vs referral)
|
||||
- Onboarding path completed vs not
|
||||
- Feature usage (power users vs lurkers)
|
||||
|
||||
### Step 2: Find the inflection points
|
||||
Where does the drop happen? D1? D7? Month 3?
|
||||
- D1 drop → First session experience
|
||||
- D7 drop → Habit loop not formed
|
||||
- D30 drop → Value not delivered at depth
|
||||
- Month 3+ drop → Boredom, competition, or lifecycle event
|
||||
|
||||
### Step 3: Identify the "aha moment" correlation
|
||||
Which early behaviour predicts long-term retention?
|
||||
- Run correlation: users who did [X] in first 7 days vs 30-day retention
|
||||
- Common patterns: connected an integration, invited a teammate, completed a core action N times
|
||||
|
||||
### Step 4: Qualify the churn
|
||||
Interview churned users — never skip this. Survey data alone is insufficient.
|
||||
- "What was the trigger that led you to cancel/stop?"
|
||||
- "What were you trying to accomplish that you couldn't?"
|
||||
- "What would need to change for you to come back?"
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
### Retention Analysis — [Product/Segment] — [Date]
|
||||
|
||||
**Question:** [Specific retention question being answered]
|
||||
**Period Analysed:** [Date range]
|
||||
**Segment:** [Which users]
|
||||
|
||||
---
|
||||
|
||||
**Current Retention Snapshot:**
|
||||
|
||||
| Metric | Current | Industry Benchmark | Status |
|
||||
|---|---|---|---|
|
||||
| D1 Retention | [X%] | 25–40% | 🔴/🟡/🟢 |
|
||||
| D7 Retention | [X%] | 10–25% | 🔴/🟡/🟢 |
|
||||
| D30 Retention | [X%] | 5–15% | 🔴/🟡/🟢 |
|
||||
| DAU/MAU | [X%] | 10–20% typical | 🔴/🟡/🟢 |
|
||||
|
||||
**Retention Curve Shape:** [Flattening / Still declining / Trending to zero]
|
||||
**PMF Signal:** [Strong / Weak / Absent — based on curve shape]
|
||||
|
||||
---
|
||||
|
||||
**Root Cause Hypotheses:**
|
||||
|
||||
| Hypothesis | Evidence | Confidence | Test |
|
||||
|---|---|---|---|
|
||||
| [Cause] | [Data point] | H/M/L | [How to validate] |
|
||||
|
||||
**"Aha Moment" Correlation:**
|
||||
Users who [specific action] in first [N] days retain at [X%] vs [Y%] for those who don't.
|
||||
|
||||
---
|
||||
|
||||
**Recommended Interventions:**
|
||||
|
||||
| Intervention | Target Drop | Expected Lift | Effort | Priority |
|
||||
|---|---|---|---|---|
|
||||
| [Specific change] | D1 / D7 / D30 | [X%] | S/M/L | 1/2/3 |
|
||||
|
||||
**Monitoring Plan:**
|
||||
- Metric to track: [X]
|
||||
- Review cadence: [Weekly / Monthly]
|
||||
- Alert threshold: [If X drops below Y, investigate immediately]
|
||||
|
||||
---
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Product and business model** (SaaS / consumer app / marketplace / other)
|
||||
- **Current retention metrics** (D1, D7, D30 if available)
|
||||
- **Segment to analyse** (all users / paid / free / a specific cohort)
|
||||
- **Key question to answer** (why is retention dropping? what drives retention?)
|
||||
- **Available data** (analytics events, churn surveys, interview notes)
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Retention curve shape is diagnosed (flattening vs trending to zero = PMF vs onboarding)
|
||||
- [ ] Cohorts are segmented before analysis (not all users lumped together)
|
||||
- [ ] "Aha moment" correlation is identified or flagged as unknown
|
||||
- [ ] Interventions are specific (not "improve onboarding")
|
||||
- [ ] Churned user interviews are recommended (not just data analysis)
|
||||
- [ ] Monitoring plan includes an alert threshold
|
||||
|
||||
## Guidelines
|
||||
|
||||
- Never recommend "improve onboarding" without specifying *what* to change and *why*
|
||||
- Benchmark against industry — consumer apps, SaaS, and marketplaces have very different retention norms
|
||||
- If DAU/MAU is below 5%, that's a PMF conversation, not a retention tactics conversation
|
||||
- Always recommend talking to churned users — no amount of data replaces understanding the *reason*
|
||||
Vendored
BIN
Binary file not shown.
@@ -0,0 +1,13 @@
|
||||
{
|
||||
"$schema": "https://anthropic.com/claude-code/plugin.schema.json",
|
||||
"name": "pm-business",
|
||||
"version": "1.0.0",
|
||||
"description": "Business & strategy skills: Investor Update, Board Deck Narrative, Job Application. Write investor updates investors actually read, structure board presentations, and tailor CVs and cover letters with ATS optimisation.",
|
||||
"author": {
|
||||
"name": "Mohit Aggarwal",
|
||||
"email": "mohit15856@gmail.com"
|
||||
},
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills",
|
||||
"license": "MIT",
|
||||
"keywords": ["product-management", "business", "strategy", "investor-update", "board-deck", "startup", "career", "job-application"]
|
||||
}
|
||||
@@ -0,0 +1,157 @@
|
||||
---
|
||||
name: board-deck-narrative
|
||||
description: "Build the storyline and slide structure for a board presentation. Use when asked to create a board deck, board presentation narrative, board meeting slides, or quarterly board update. Produces a complete slide-by-slide structure with narrative beats, talking points, and slide content guidance."
|
||||
---
|
||||
|
||||
# Board Deck Narrative Skill
|
||||
|
||||
This skill builds the complete narrative and slide structure for a board presentation — from opening framing to closing asks. It produces slide-by-slide content guidance, not just a list of topics.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Company stage and context** (Seed / Series A / Growth — and where you are in the year)
|
||||
- **Board meeting type** (Regular quarterly / Annual / Special / Fundraise-related)
|
||||
- **Key themes for this meeting** (e.g. strong growth quarter / pivoting strategy / hiring challenge / fundraise update)
|
||||
- **Key metrics to feature**
|
||||
- **Decisions needed from the board** (if any)
|
||||
- **Time available** (e.g. 60 min / 90 min)
|
||||
- **Audience** (investors only / investors + independent directors / mixed)
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# Board Deck Narrative: [Company] — [Quarter/Period]
|
||||
|
||||
**Meeting type:** [Regular quarterly / Special]
|
||||
**Time:** [X minutes]
|
||||
**Narrative theme:** [The one-sentence story of this quarter — e.g. "We hit our revenue target, but activation is the problem we need to solve together."]
|
||||
|
||||
---
|
||||
|
||||
## Opening Frame (Slide 1–2)
|
||||
|
||||
**Slide 1: Title**
|
||||
- Company name, quarter, date
|
||||
- One-sentence framing of the meeting's narrative arc
|
||||
|
||||
**Slide 2: Agenda**
|
||||
- List of sections + time allocation
|
||||
- Flag which sections need board input vs. are informational
|
||||
|
||||
*Presenter note: Board members are busy. Tell them in the first 2 minutes what you need from them today. It changes how they listen.*
|
||||
|
||||
---
|
||||
|
||||
## Business Performance (Slides 3–6, ~15 min)
|
||||
|
||||
**Slide 3: Scorecard / KPI Dashboard**
|
||||
- Content: Key metrics vs. targets for the quarter. No more than 6 metrics.
|
||||
- Format: Traffic-light table (Green / Amber / Red against plan)
|
||||
- Narrative: [1–2 sentences — the headline story of the quarter in numbers]
|
||||
- *Don't hide reds. Boards lose trust when they discover hidden problems later.*
|
||||
|
||||
**Slide 4: Revenue / Growth Deep Dive**
|
||||
- Content: Revenue breakdown by segment, cohort retention, growth drivers
|
||||
- Key message: [What the data shows about the health of growth]
|
||||
- Call out: [Any trend that needs board context or discussion]
|
||||
|
||||
**Slide 5: Unit Economics**
|
||||
- Content: CAC, LTV, payback period, gross margin — vs. last quarter and vs. plan
|
||||
- Flag: Any metric moving in the wrong direction and what's causing it
|
||||
|
||||
**Slide 6: Operational Highlights**
|
||||
- Content: 3–5 bullet points of the most significant things that happened this quarter
|
||||
- Format: Each bullet = outcome, not activity. ("Signed 3 enterprise contracts worth £400K ARR" not "Continued enterprise sales motion")
|
||||
|
||||
---
|
||||
|
||||
## Strategic Update (Slides 7–9, ~15 min)
|
||||
|
||||
**Slide 7: Strategy Snapshot**
|
||||
- Content: Where you said you'd be vs. where you are against the annual plan
|
||||
- Narrative: [Honest assessment — what's on track, what's shifted and why]
|
||||
|
||||
**Slide 8: Key Strategic Decision or Update**
|
||||
- Content: The one strategic topic that most needs board input this meeting
|
||||
- Format: Context → Options considered → Recommendation → Question for board
|
||||
- *This is the highest-value 10 minutes of the meeting. Frame it as a real question.*
|
||||
|
||||
**Slide 9: Product & Roadmap (if relevant)**
|
||||
- Content: Top 3 product bets this quarter — what shipped, what's coming, why these bets
|
||||
- Tailored for: What the board needs to understand to support strategic decisions, not a sprint review
|
||||
|
||||
---
|
||||
|
||||
## People & Organisation (Slide 10, ~5 min)
|
||||
|
||||
**Slide 10: Team Update**
|
||||
- Content: Headcount (start vs. end of quarter), key hires made, open roles, any org changes
|
||||
- Flag: Any people risks or leadership gaps the board should know about
|
||||
- *Don't skip this slide. Board members often have network value here.*
|
||||
|
||||
---
|
||||
|
||||
## Financial Update (Slides 11–12, ~10 min)
|
||||
|
||||
**Slide 11: P&L Summary**
|
||||
- Content: Revenue, gross margin, opex by category, EBITDA/net burn — actual vs. budget
|
||||
- Include: Year-to-date vs. annual plan
|
||||
|
||||
**Slide 12: Cash & Runway**
|
||||
- Content: Cash on hand, monthly burn rate, runway at current burn
|
||||
- Include: Scenario if burn increases (e.g. key hire made), scenario if growth accelerates
|
||||
- Flag immediately: If runway is < 18 months — this needs board awareness and planning
|
||||
|
||||
---
|
||||
|
||||
## Closing & Asks (Slides 13–14, ~10 min)
|
||||
|
||||
**Slide 13: Priorities for Next Quarter**
|
||||
- Content: Top 3–5 priorities and what success looks like for each
|
||||
- Format: Priority | What we're doing | How we'll know it worked
|
||||
- *Keeps board accountability consistent across meetings*
|
||||
|
||||
**Slide 14: Board Asks**
|
||||
- Content: Specific things you need from board members before next meeting
|
||||
- Format: Each ask = specific, named if possible ("Looking for an intro to [Company] — [Board member X], do you have a connection?")
|
||||
- *A board meeting without specific asks is a missed opportunity*
|
||||
|
||||
---
|
||||
|
||||
## Appendix (Optional)
|
||||
|
||||
- Detailed cohort analysis
|
||||
- Competitive landscape update
|
||||
- Full P&L
|
||||
- Team org chart
|
||||
- Any supporting data referenced in the main deck
|
||||
|
||||
*Appendix slides are available but not presented. Board members who want detail can ask.*
|
||||
|
||||
---
|
||||
|
||||
## Narrative Principles
|
||||
|
||||
- **Lead with honesty.** If it was a hard quarter, say so in the first slide. Don't bury bad news after the wins.
|
||||
- **One slide = one idea.** If a slide has two messages, split it.
|
||||
- **Fewer slides, more depth.** A 14-slide deck presented well beats a 35-slide deck rushed through.
|
||||
- **Every slide has a "so what."** A slide that just shows data without a takeaway wastes board time.
|
||||
- **Leave time for discussion.** Board value is in the conversation, not the presentation. Aim to spend 40% of the meeting presenting and 60% in discussion.
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Opening frame states the meeting's narrative theme
|
||||
- [ ] Scorecard slide uses traffic-light format (not just green metrics)
|
||||
- [ ] Strategic decision slide frames a real question for the board
|
||||
- [ ] Financial slide includes runway explicitly
|
||||
- [ ] Board asks are specific and actionable
|
||||
- [ ] Deck is ≤ 15 slides (excluding appendix)
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Build a board deck structure for our Q[N] board meeting"
|
||||
- "Help me create the narrative for our board presentation"
|
||||
- "Write the slide structure for our annual board review"
|
||||
- "Design a board deck for [specific context — e.g. fundraise update]"
|
||||
@@ -0,0 +1,127 @@
|
||||
---
|
||||
name: investor-update
|
||||
description: "Write a structured monthly or quarterly investor update. Use when asked to write an investor update, investor newsletter, board update, or startup progress report for investors. Produces a clear, credible update with highlights, metrics, challenges, and asks — in the format investors actually want to read."
|
||||
---
|
||||
|
||||
# Investor Update Skill
|
||||
|
||||
This skill writes a complete investor update — structured for clarity, honest about challenges, and specific about asks. Output follows the format preferred by most early-stage and growth investors.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Company name and stage** (Seed / Series A / Series B / etc.)
|
||||
- **Period covered** (month or quarter)
|
||||
- **Key metrics this period** (revenue, MRR, users, churn, burn, runway — whatever's relevant)
|
||||
- **Biggest wins**
|
||||
- **Biggest challenges or misses**
|
||||
- **Specific asks from investors** (intros, advice, talent, partnerships)
|
||||
- **What's coming next period**
|
||||
- **Tone** (formal / conversational — most investors prefer conversational)
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
**[Company Name] — [Month/Quarter] Update**
|
||||
*[Date]*
|
||||
|
||||
---
|
||||
|
||||
Hi [Investor names or "all"],
|
||||
|
||||
[One or two sentence opener — a specific highlight or honest framing of the period. Don't open with "Hope you're well." Open with the most important thing that happened.]
|
||||
|
||||
---
|
||||
|
||||
## The Numbers
|
||||
|
||||
| Metric | This Period | Last Period | Change |
|
||||
|---|---|---|---|
|
||||
| [MRR / ARR] | [Value] | [Value] | [+/- %] |
|
||||
| [Active users / customers] | | | |
|
||||
| [Churn rate] | | | |
|
||||
| [Burn rate] | | | |
|
||||
| [Runway] | | | |
|
||||
| [Other key metric] | | | |
|
||||
|
||||
[1–2 sentences of narrative on the numbers — what's the story behind the movement? Don't just repeat the table.]
|
||||
|
||||
---
|
||||
|
||||
## Highlights
|
||||
|
||||
**[Highlight 1 — 4–6 word title]**
|
||||
[2–4 sentences. What happened. Why it matters. Be specific — name the customer, the number, the milestone.]
|
||||
|
||||
**[Highlight 2]**
|
||||
[2–4 sentences]
|
||||
|
||||
**[Highlight 3 — optional]**
|
||||
|
||||
---
|
||||
|
||||
## Challenges
|
||||
|
||||
[This section is what separates trustworthy updates from self-promotional ones. Investors know you have challenges. Being direct builds trust.]
|
||||
|
||||
**[Challenge 1]**
|
||||
[2–4 sentences. What the problem is. What you've tried. What you're doing about it. Don't spin — investors see through it.]
|
||||
|
||||
**[Challenge 2 — if applicable]**
|
||||
|
||||
---
|
||||
|
||||
## Focus for Next [Month/Quarter]
|
||||
|
||||
[3–5 bullet points. What you're concentrating on next period and why. Keep it tight — not an exhaustive roadmap.]
|
||||
|
||||
- [Priority 1]
|
||||
- [Priority 2]
|
||||
- [Priority 3]
|
||||
|
||||
---
|
||||
|
||||
## Asks
|
||||
|
||||
[Be specific. "Let me know if you can help" is not an ask. These should be actionable items an investor can act on immediately.]
|
||||
|
||||
1. **[Ask type: e.g. Intro]** — [Specific request. e.g. "Looking for an intro to procurement leads at mid-market SaaS companies. Happy to share a warm intro note."]
|
||||
2. **[Ask type: e.g. Advice]** — [Specific question you want input on]
|
||||
3. **[Ask type: e.g. Talent]** — [Specific hire you're looking for — title, key requirements]
|
||||
|
||||
---
|
||||
|
||||
[Closing line — 1 sentence. Forward-looking or a genuine thanks. Not "as always, let me know if you have questions."]
|
||||
|
||||
[Signature]
|
||||
[Name]
|
||||
[Company]
|
||||
[One way to reply — email / Calendly / reply to this thread]
|
||||
|
||||
---
|
||||
|
||||
## Writing Rules
|
||||
|
||||
- Updates should take an investor 3–4 minutes to read. If it's longer, trim it.
|
||||
- Never lead with process ("This month we focused on...") — lead with outcomes
|
||||
- Challenges section must be honest. A missing challenges section signals the founder isn't self-aware or isn't being transparent.
|
||||
- Metrics table must include comparison to last period — a number without context is meaningless
|
||||
- Asks must be specific enough that an investor knows within 5 seconds if they can help
|
||||
- No jargon or buzzwords ("synergies," "crushing it," "hockey stick") — plain language only
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Opens with a specific highlight or honest framing (not a pleasantry)
|
||||
- [ ] Numbers include period-over-period comparison
|
||||
- [ ] Challenges section is present and honest
|
||||
- [ ] Asks are specific and actionable
|
||||
- [ ] Total length is skimmable in 3–4 minutes
|
||||
- [ ] No spin or buzzwords
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Write an investor update for [month/quarter]"
|
||||
- "Draft a monthly update for our investors based on these notes: [paste notes]"
|
||||
- "Help me write a board update for Q[N]"
|
||||
- "Write our Series A investor newsletter"
|
||||
@@ -0,0 +1,128 @@
|
||||
---
|
||||
name: job-application
|
||||
description: "Tailor a CV and cover letter to a specific job description. Use when asked to write a cover letter, tailor a CV or resume, optimise for ATS, match a job description, or prepare a job application. Produces an ATS-optimised tailored CV summary and a personalised cover letter."
|
||||
---
|
||||
|
||||
# Job Application Skill
|
||||
|
||||
This skill tailors a CV and cover letter to a specific job description — optimising for ATS keyword matching while keeping the writing human and compelling. It also flags gaps between the candidate's profile and the role requirements.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Job description** (paste in full)
|
||||
- **Current CV / resume** (paste or describe key experience, roles, and skills)
|
||||
- **The specific thing that excites them about this role** (used in the cover letter — must be genuine)
|
||||
- **Any particular strengths to emphasise** (optional)
|
||||
- **Any gaps they're worried about** (optional — helps address them proactively)
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
## Part 1: JD Analysis
|
||||
|
||||
Before writing anything, analyse the job description and output:
|
||||
|
||||
### Must-Have Requirements
|
||||
[List explicit requirements from the JD — qualifications, years of experience, specific skills]
|
||||
|
||||
### Key Themes in the JD
|
||||
[3–5 themes that repeat or are emphasised — these are the keywords and priorities the hiring manager cares about most]
|
||||
|
||||
### ATS Keywords to Include
|
||||
[List 10–15 specific keywords and phrases from the JD that should appear in the CV and cover letter. Include: tools, methodologies, job titles, skills]
|
||||
|
||||
### Gaps Assessment
|
||||
[Honest comparison between the candidate's profile and the JD requirements. Flag: "Strong match" / "Partial match — can be positioned as X" / "Gap — address in cover letter or don't apply"]
|
||||
|
||||
---
|
||||
|
||||
## Part 2: Tailored CV Summary / Profile Section
|
||||
|
||||
Rewrite or create the candidate's CV summary/profile section (the 3–5 lines at the top of a CV) specifically for this role:
|
||||
|
||||
**Rules:**
|
||||
- Open with the job title or a near-match (ATS reward)
|
||||
- Include 2–3 keywords from the JD naturally
|
||||
- Reference years of experience in the relevant area
|
||||
- End with a forward-looking line connecting their background to what this role needs
|
||||
- Keep to 60–80 words maximum
|
||||
|
||||
**Tailored CV Summary:**
|
||||
[Write the summary]
|
||||
|
||||
---
|
||||
|
||||
## Part 3: Experience Bullet Point Rewrites
|
||||
|
||||
For the 2–3 most relevant roles on the CV, suggest how to reframe existing bullet points to better match this JD:
|
||||
|
||||
**[Role Title] at [Company]**
|
||||
|
||||
| Original Bullet | Tailored Version | Why |
|
||||
|---|---|---|
|
||||
| [Candidate's original text] | [Improved version with JD keywords and stronger impact framing] | [Brief note on what changed] |
|
||||
|
||||
**Rules for bullet point rewrites:**
|
||||
- Lead with an action verb
|
||||
- Include a quantified outcome where possible (%, £, time saved, users impacted)
|
||||
- Weave in JD keywords naturally — not forced
|
||||
- Keep to one line (2 max)
|
||||
|
||||
---
|
||||
|
||||
## Part 4: Cover Letter
|
||||
|
||||
**Format:** 3 paragraphs + closing. Target: 250–350 words. Anything longer won't be read.
|
||||
|
||||
---
|
||||
|
||||
[Hiring Manager's name if known, otherwise "Hiring Team"]
|
||||
|
||||
**Paragraph 1 — The Hook (Why this role, specifically)**
|
||||
[2–4 sentences. Reference something specific about the company or role — not generic enthusiasm. The candidate's genuine reason for applying goes here. This is what makes it human. Generic openers like "I am writing to apply for..." are filtered out mentally within 3 seconds.]
|
||||
|
||||
**Paragraph 2 — The Evidence (Why them)**
|
||||
[3–5 sentences. 2–3 specific examples from their background that directly address the JD's key themes. Use the language of the JD. Include at least one quantified achievement. Don't list everything — pick the 2–3 strongest matches and go deep, not broad.]
|
||||
|
||||
**Paragraph 3 — The Forward Bridge (Why now)**
|
||||
[2–3 sentences. Connect their trajectory to this role. Why is this the logical next step? What do they want to learn or build that this role enables? This should feel like the natural continuation of their career, not just "I want a new challenge."]
|
||||
|
||||
---
|
||||
|
||||
I'd welcome the chance to discuss how my background could contribute to [Company/Team]. Thank you for your time.
|
||||
|
||||
[Name]
|
||||
[Email] | [LinkedIn URL] | [Location if relevant]
|
||||
|
||||
---
|
||||
|
||||
## Part 5: Application Checklist
|
||||
|
||||
Before submitting:
|
||||
- [ ] CV summary updated with tailored version above
|
||||
- [ ] ATS keywords appear in CV body (not just summary)
|
||||
- [ ] Cover letter is under 400 words
|
||||
- [ ] Company name is spelled correctly throughout (sounds obvious — it happens)
|
||||
- [ ] No generic phrases: "passionate about," "results-driven," "team player" without evidence
|
||||
- [ ] LinkedIn profile updated to match CV (recruiters cross-check)
|
||||
- [ ] Role title in subject line if emailing directly
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] JD analysis completed before writing (not skipped)
|
||||
- [ ] ATS keywords are integrated naturally (not stuffed)
|
||||
- [ ] Cover letter opens with something specific (not a generic opener)
|
||||
- [ ] Paragraph 2 includes at least one quantified achievement
|
||||
- [ ] Cover letter is 250–350 words
|
||||
- [ ] Gaps are either addressed or strategically omitted
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Help me apply for this job: [paste JD]"
|
||||
- "Tailor my CV for this role: [paste JD + CV]"
|
||||
- "Write a cover letter for [role] at [company]"
|
||||
- "Optimise my application for ATS for this job description"
|
||||
@@ -0,0 +1,13 @@
|
||||
{
|
||||
"$schema": "https://anthropic.com/claude-code/plugin.schema.json",
|
||||
"name": "pm-cross",
|
||||
"version": "1.1.0",
|
||||
"description": "Cross-profession skills: Press Release, Grant Proposal, Executive Summary, Teaching Lesson Plan. Write journalist-ready press releases, structure grant applications, produce decision-ready executive summaries, and design complete lesson plans for any subject, audience, or setting.",
|
||||
"author": {
|
||||
"name": "Mohit Aggarwal",
|
||||
"email": "mohit15856@gmail.com"
|
||||
},
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills",
|
||||
"license": "MIT",
|
||||
"keywords": ["communications", "press-release", "grant", "executive-summary", "briefing", "funding", "media", "education", "teaching", "lesson-plan", "training"]
|
||||
}
|
||||
@@ -0,0 +1,98 @@
|
||||
---
|
||||
name: executive-summary
|
||||
description: "Write an executive summary for any document, report, or proposal. Use when asked to write an executive summary, management summary, briefing paper, or one-pager for senior stakeholders. Produces a structured summary that busy executives can read in under 3 minutes and act on."
|
||||
---
|
||||
|
||||
# Executive Summary Skill
|
||||
|
||||
Writes executive summaries that busy decision-makers actually read — front-loaded with conclusions, structured for skimming, ruthless about what to include.
|
||||
|
||||
## Required Inputs
|
||||
- **Source document or topic** (paste or describe)
|
||||
- **Audience** (CEO / board / investor / minister / client / committee)
|
||||
- **Decision or action needed** (what should the reader do after reading?)
|
||||
- **Length limit** (1 page / 2 pages / 500 words)
|
||||
- **Format** (formal report / slide / email / briefing paper)
|
||||
|
||||
## Core Principle
|
||||
|
||||
An executive summary is NOT a summary of the document. It is a standalone document that:
|
||||
- States the conclusion upfront — not at the end
|
||||
- Contains only what the reader needs to make a decision
|
||||
- Can be understood without reading anything else
|
||||
- Recommends a specific action
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
### [Title]
|
||||
**Executive Summary**
|
||||
*Prepared for: [Audience] | Date: [Date] | Author: [Name]*
|
||||
|
||||
---
|
||||
|
||||
**Bottom line up front:**
|
||||
[The most important thing. The recommendation or finding. 2-3 sentences. A reader who only reads this should know what you are asking or telling them.]
|
||||
|
||||
---
|
||||
|
||||
**Background (why this matters):**
|
||||
[2-3 sentences. Minimum context to understand the bottom line. Not the history — just what the reader needs now.]
|
||||
|
||||
---
|
||||
|
||||
**Key findings / analysis:**
|
||||
- **[Finding 1]:** [One sentence — specific and evidence-based]
|
||||
- **[Finding 2]:** [One sentence]
|
||||
- **[Finding 3]:** [One sentence]
|
||||
|
||||
---
|
||||
|
||||
**Options considered:** (include only if a decision is being presented)
|
||||
|
||||
| Option | Benefit | Risk | Recommendation |
|
||||
|---|---|---|---|
|
||||
| [Option A] | [Benefit] | [Risk] | Recommended |
|
||||
| [Option B] | [Benefit] | [Risk] | Not recommended |
|
||||
|
||||
---
|
||||
|
||||
**Recommendation:**
|
||||
[Specific. "We recommend [action] because [reason]. This will [outcome]." Not "we suggest consideration of options."]
|
||||
|
||||
---
|
||||
|
||||
**Immediate next steps:**
|
||||
- [Action 1 — specific, with owner and date]
|
||||
- [Action 2]
|
||||
|
||||
---
|
||||
|
||||
**Risks of inaction:** [What happens if the reader does nothing]
|
||||
|
||||
**Full report:** [Reference to where the full document can be found]
|
||||
|
||||
---
|
||||
|
||||
## Adapting for Different Audiences
|
||||
|
||||
**CEO/MD:** Lead with financial or strategic impact. 1 page. Make the decision binary. Ask in sentence one.
|
||||
**Board:** Lead with governance or risk. Frame against organisational objectives. State specifically what you need from them.
|
||||
**Investor:** Lead with return or opportunity. Specific numbers. 1 page. Anticipate "why now."
|
||||
**Minister/senior public sector:** Lead with public benefit or policy alignment. Include cost-benefit framing.
|
||||
**Client:** Lead with their problem. Show you understand before presenting recommendation.
|
||||
|
||||
## Quality Checks
|
||||
- Bottom line in first 3 sentences
|
||||
- Standalone — no need to read full document
|
||||
- Recommendation is specific
|
||||
- Fits length limit
|
||||
- Written for audience priorities not author priorities
|
||||
- Next steps have owners and dates
|
||||
|
||||
## Example Trigger Phrases
|
||||
- "Write an executive summary of this report: [paste]"
|
||||
- "Summarise this document for the board: [paste]"
|
||||
- "Create a one-pager from this proposal for the CEO"
|
||||
- "Turn these findings into an exec summary"
|
||||
@@ -0,0 +1,102 @@
|
||||
---
|
||||
name: grant-proposal
|
||||
description: "Write a structured grant proposal or funding application for any grant type. Use when asked to write a grant proposal, funding application, research grant, charitable grant, or innovation fund application. Produces a complete proposal with project summary, rationale, methodology, impact, and budget narrative."
|
||||
---
|
||||
|
||||
# Grant Proposal Skill
|
||||
|
||||
Produces structured grant proposals tailored to the funder priorities — the most common reason grants fail is writing about what you want to do rather than what the funder wants to fund.
|
||||
|
||||
## Required Inputs
|
||||
- **Funder name and grant programme**
|
||||
- **Grant amount sought**
|
||||
- **Project description** (rough notes are fine)
|
||||
- **Your organisation** (type, track record, capacity)
|
||||
- **Funder stated priorities** (copy from their guidance — essential)
|
||||
- **Word or page limits**
|
||||
- **Deadline**
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
### Project Title
|
||||
[Informative and memorable. Should convey the problem being solved and the approach.]
|
||||
|
||||
### 1. Project Summary / Abstract (200-300 words — written last, placed first)
|
||||
[What you will do, why it matters, who will benefit, measurable outcomes. Every sentence earns its place.]
|
||||
|
||||
### 2. Problem Statement / Need
|
||||
- **The problem:** [Specific, evidenced — use data]
|
||||
- **Who is affected:** [Population, scale, geography]
|
||||
- **Current situation:** [What exists and why it is insufficient]
|
||||
- **Consequence of inaction:** [What happens if not funded]
|
||||
- **Why your organisation:** [Track record, relationships, expertise]
|
||||
|
||||
Funder test: does this problem align with [funder] stated priorities? Make the connection explicit.
|
||||
|
||||
### 3. Project Objectives
|
||||
3-5 SMART objectives:
|
||||
- **Objective 1:** [Specific, Measurable, Achievable, Relevant, Time-bound]
|
||||
|
||||
### 4. Methodology / Approach
|
||||
|
||||
**Phase 1: [Name]** (Months 1-X)
|
||||
[What will happen, who will do it, what is produced]
|
||||
|
||||
**Key activities:**
|
||||
- [Activity — specific]
|
||||
|
||||
**What makes this approach innovative or effective:** [Why this over alternatives]
|
||||
|
||||
### 5. Impact and Outcomes
|
||||
|
||||
| Level | Description | Measure |
|
||||
|---|---|---|
|
||||
| Output | [Tangible deliverable] | [How counted] |
|
||||
| Short-term outcome | [Immediate change] | [How measured] |
|
||||
| Medium-term outcome | [Behaviour change] | [How measured] |
|
||||
| Long-term impact | [Systemic change] | [How evidenced] |
|
||||
|
||||
**Direct beneficiaries:** [Who and how many]
|
||||
**Sustainability:** [How work continues beyond grant period]
|
||||
|
||||
### 6. Evaluation Plan
|
||||
- Who evaluates, how, when, what is measured, how findings are shared
|
||||
|
||||
### 7. Budget Narrative
|
||||
|
||||
| Budget line | Amount | Justification |
|
||||
|---|---|---|
|
||||
| Staff costs | £[amount] | [Role, % FTE, duration, salary] |
|
||||
| Travel | £[amount] | [Specific journeys named] |
|
||||
| Equipment | £[amount] | [Itemised] |
|
||||
| Indirect costs | £[amount] | [[X]% of direct — check policy] |
|
||||
| **Total** | **£[total]** | |
|
||||
|
||||
**Value for money:** [Cost per beneficiary. What could not be done without this grant]
|
||||
|
||||
### 8. Organisational Capacity
|
||||
[Track record of similar projects, governance, financial management. Name previous grants and outputs — be specific]
|
||||
|
||||
### 9. Risk Register
|
||||
|
||||
| Risk | Likelihood | Impact | Mitigation |
|
||||
|---|---|---|---|
|
||||
| [Risk] | H/M/L | H/M/L | [Specific mitigation] |
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Every section explicitly references funder stated priorities (not just generic language)
|
||||
- [ ] Problem statement includes specific data, not just assertions
|
||||
- [ ] Objectives are SMART (measurable and time-bound)
|
||||
- [ ] Budget narrative justifies every line with specific detail
|
||||
- [ ] Sustainability section explains what happens after the grant ends
|
||||
- [ ] Word limits respected
|
||||
|
||||
## Example Trigger Phrases
|
||||
- "Write a grant proposal for [project] applying to [funder]"
|
||||
- "Help me write a funding application for [grant programme]"
|
||||
- "Turn these project notes into a grant proposal: [paste]"
|
||||
@@ -0,0 +1,79 @@
|
||||
---
|
||||
name: press-release
|
||||
description: "Write a professional press release for any announcement. Use when asked to write a press release, media announcement, news release, or press statement. Produces a structured press release with headline, dateline, body, boilerplate, and media contact — ready to send to journalists."
|
||||
---
|
||||
|
||||
# Press Release Skill
|
||||
|
||||
Writes press releases that journalists actually read — structured around the news angle, not the desire to promote.
|
||||
|
||||
## Required Inputs
|
||||
- **The news** (what is actually happening — be specific)
|
||||
- **Company name**
|
||||
- **Date of announcement / embargo date**
|
||||
- **Key quote** (from which executive and approximately what they want to say)
|
||||
- **Why this matters** (to the reader, not the company)
|
||||
- **Target media** (trade / national / local / consumer / investor)
|
||||
- **Media contact details**
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
FOR IMMEDIATE RELEASE / EMBARGOED UNTIL: [Date and time]
|
||||
|
||||
---
|
||||
|
||||
# [Headline — active verb, specific news, under 10 words]
|
||||
## [Subheadline — the so-what in one sentence, adds context not repetition]
|
||||
|
||||
**[City, Date]** — [Opening paragraph: Who, What, When, Where, Why in 2-3 sentences. A journalist should be able to run this paragraph alone. No background, no context, no company history.]
|
||||
|
||||
[Second paragraph: the significance. Why does this matter? What does it mean for customers or the industry?]
|
||||
|
||||
[Third paragraph: quote from executive. Human and specific. Not a restatement of the headline.]
|
||||
|
||||
"[Quote text — specific, adds something the facts do not say]," said [Name], [Title] at [Company]. "[Second sentence extending the thought]."
|
||||
|
||||
[Fourth paragraph: supporting detail — data, customer names with permission, additional context]
|
||||
|
||||
[Fifth paragraph optional: what happens next, when it goes live, what people can do]
|
||||
|
||||
---
|
||||
|
||||
ENDS
|
||||
|
||||
---
|
||||
|
||||
**Notes to editors:**
|
||||
|
||||
**About [Company]**
|
||||
[Boilerplate: 3-4 sentences. What the company does, when founded, where based, key facts. Factual not promotional.]
|
||||
|
||||
**Media contact:**
|
||||
[Name] | [Title] | [Email] | [Phone] | [Hours/timezone]
|
||||
|
||||
---
|
||||
|
||||
## Headline Rules
|
||||
- Active voice: "Company launches X" not "X is launched by Company"
|
||||
- Specific: "raises 5M" not "secures significant investment"
|
||||
- Under 10 words
|
||||
- Never start with the company name — lead with the news
|
||||
|
||||
## Journalist Test
|
||||
Would a journalist care? Is the headline the full story? Is there a human angle? Is the quote something a human would say? Can the first paragraph stand alone?
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Headline uses active voice and is under 10 words
|
||||
- [ ] First paragraph stands alone as the complete story
|
||||
- [ ] Quote adds something the facts don't say (not a restatement)
|
||||
- [ ] Boilerplate is factual, not promotional
|
||||
- [ ] Embargo date and media contact are included
|
||||
|
||||
## Example Trigger Phrases
|
||||
- "Write a press release announcing [news]"
|
||||
- "Draft a media statement about [event]"
|
||||
- "We are launching [product] — write the press release"
|
||||
- "Turn this announcement into a press release: [paste notes]"
|
||||
@@ -0,0 +1,118 @@
|
||||
---
|
||||
name: teaching-lesson-plan
|
||||
description: "Design a structured lesson plan for any subject, audience, or format. Use when asked to write a lesson plan, course outline, teaching session, workshop curriculum, or training module. Produces a complete lesson plan with learning objectives, activities, timing, assessment, and differentiation guidance."
|
||||
---
|
||||
|
||||
# Teaching Lesson Plan Skill
|
||||
|
||||
Produces a complete, structured lesson plan for any subject, age group, or setting — from a one-hour corporate training to a full school lesson. Built around clear learning objectives, varied activities, and formative assessment.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Subject or topic**
|
||||
- **Audience** (age group, experience level, group size)
|
||||
- **Session length** (30 / 45 / 60 / 90 / 120 minutes)
|
||||
- **Setting** (classroom / workshop / online / corporate training / one-to-one)
|
||||
- **Learning goal** (what should participants know or be able to do by the end?)
|
||||
- **Prior knowledge** (what can you assume they already know?)
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# Lesson Plan: [Topic]
|
||||
|
||||
**Subject:** [Subject] | **Audience:** [Description] | **Duration:** [X minutes]
|
||||
**Setting:** [Setting] | **Group size:** [N]
|
||||
|
||||
---
|
||||
|
||||
## Learning Objectives
|
||||
|
||||
By the end of this session, participants will be able to:
|
||||
1. [Objective 1 — use Bloom's taxonomy verbs: recall, explain, apply, analyse, evaluate, create]
|
||||
2. [Objective 2]
|
||||
3. [Objective 3 — maximum 3–4 objectives per session]
|
||||
|
||||
**Key vocabulary:** [3–5 terms participants will need to know]
|
||||
|
||||
---
|
||||
|
||||
## Materials and Preparation
|
||||
|
||||
- [ ] [Resource 1 — slides, handout, equipment]
|
||||
- [ ] [Resource 2]
|
||||
- [ ] Room setup: [configuration — rows / circles / tables / breakout spaces]
|
||||
|
||||
---
|
||||
|
||||
## Lesson Structure
|
||||
|
||||
| Time | Phase | Activity | Format |
|
||||
|---|---|---|---|
|
||||
| [00:00] | Hook / Opener | [How you grab attention and establish relevance] | [Whole group / Individual / Pairs] |
|
||||
| [00:05] | Prior knowledge | [How you connect to what they already know] | [Discussion / Quiz / Think-pair-share] |
|
||||
| [00:15] | Instruction | [Direct teaching of new content] | [Explanation / Demo / Video] |
|
||||
| [00:30] | Guided practice | [Supported practice with feedback] | [Worked examples / Group task] |
|
||||
| [00:50] | Independent practice | [Students apply learning independently] | [Task / Problem / Discussion] |
|
||||
| [01:05] | Check for understanding | [Formative assessment] | [Exit ticket / Quiz / Q&A] |
|
||||
| [01:15] | Closure | [Summarise, connect to next session] | [Whole group] |
|
||||
|
||||
---
|
||||
|
||||
## Key Explanations and Worked Examples
|
||||
|
||||
### [Concept 1]
|
||||
[Clear explanation + one concrete worked example. Explain the concept the way a good teacher would — no jargon without definition, one idea at a time.]
|
||||
|
||||
### [Concept 2]
|
||||
[Explanation + example]
|
||||
|
||||
---
|
||||
|
||||
## Differentiation
|
||||
|
||||
**For those who need more support:**
|
||||
- [Scaffold: e.g. sentence starters, worked examples, vocabulary cards]
|
||||
- [Modified task or reduced scope]
|
||||
|
||||
**For those ready for a challenge:**
|
||||
- [Extension: e.g. apply to a new context, evaluate, create something]
|
||||
|
||||
---
|
||||
|
||||
## Formative Assessment (Check for Understanding)
|
||||
|
||||
**During session:**
|
||||
- [Method 1: e.g. Cold calling with no-stakes approach, thumbs up/down, mini whiteboards]
|
||||
- [Method 2: e.g. Think-pair-share before moving on]
|
||||
|
||||
**Exit ticket (last 5 minutes):**
|
||||
[One specific question that directly tests the learning objective — not "what did you enjoy?" but "solve this problem" or "explain this concept in your own words"]
|
||||
|
||||
---
|
||||
|
||||
## Common Misconceptions to Address
|
||||
|
||||
| Misconception | Correct understanding | How to address it |
|
||||
|---|---|---|
|
||||
| [What learners often get wrong] | [The correct version] | [Specific activity or explanation] |
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Learning objectives use action verbs (not "understand" or "know")
|
||||
- [ ] Session has a clear hook that establishes relevance
|
||||
- [ ] Activities are varied (not all listening)
|
||||
- [ ] Formative assessment checks the actual learning objective
|
||||
- [ ] Differentiation is specified for both support and extension
|
||||
- [ ] Timing adds up to session length
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Write a lesson plan on [topic] for [audience]"
|
||||
- "Design a 60-minute session on [subject]"
|
||||
- "Create a training module on [skill]"
|
||||
- "Plan a workshop on [topic] for [group]"
|
||||
@@ -0,0 +1,13 @@
|
||||
{
|
||||
"$schema": "https://anthropic.com/claude-code/plugin.schema.json",
|
||||
"name": "pm-cs",
|
||||
"version": "1.0.0",
|
||||
"description": "Customer Success skills: Customer Health Scorecard, QBR Deck, Escalation Brief, Churn Analysis. Score account health with a weighted RAG framework, build structured QBR decks with value narratives, write crisp escalation briefs for at-risk accounts, and analyse churn by category and segment with prioritised interventions.",
|
||||
"author": {
|
||||
"name": "Mohit Aggarwal",
|
||||
"email": "mohit15856@gmail.com"
|
||||
},
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills",
|
||||
"license": "MIT",
|
||||
"keywords": ["customer-success", "account-management", "health-scorecard", "qbr", "quarterly-business-review", "churn", "retention", "escalation", "csm", "renewal"]
|
||||
}
|
||||
@@ -0,0 +1,179 @@
|
||||
---
|
||||
name: churn-analysis
|
||||
description: "Analyse customer churn for a product or cohort and produce a structured churn report. Use when asked to analyse churn, understand why customers are leaving, identify churn patterns, calculate churn rate, or build a churn reduction plan. Produces a churn analysis with rate calculations, categorised reasons, early warning signals, and prioritised interventions."
|
||||
---
|
||||
|
||||
# Churn Analysis Skill
|
||||
|
||||
Produce a structured churn analysis that goes beyond the headline rate — identifying why customers leave, which segments are most at risk, and what interventions will have the highest impact on retention.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask for these if not already provided:
|
||||
- **Time period** being analysed (e.g. Q1, last 12 months)
|
||||
- **Total customers at start of period** and **customers churned**
|
||||
- **ARR or revenue lost** to churn
|
||||
- **Churn reasons data** — exit survey results, CSM notes, support data, or sales loss reasons
|
||||
- **Customer segments** — by tier, industry, cohort, or product line
|
||||
- **Current retention rate** if known
|
||||
- **Any recent changes** — pricing, product, support model — that may have affected churn
|
||||
|
||||
## Churn Categories
|
||||
|
||||
Always classify churn before analysing it:
|
||||
|
||||
| Category | Definition |
|
||||
|---|---|
|
||||
| **Voluntary — avoidable** | Customer left due to a problem we could have addressed (product gaps, poor onboarding, relationship failures) |
|
||||
| **Voluntary — unavoidable** | Customer left for reasons outside our control (budget cuts, acquisition, company shutdown) |
|
||||
| **Involuntary** | Payment failure, contract non-renewal by mistake, admin error |
|
||||
|
||||
The interventions for each category are different. Conflating them leads to wrong conclusions.
|
||||
|
||||
## Output Format
|
||||
|
||||
---
|
||||
|
||||
# Churn Analysis: [Product / Segment / Company]
|
||||
**Period:** [Start date] — [End date]
|
||||
**Prepared by:** [Name] | **Date:** [Date]
|
||||
|
||||
---
|
||||
|
||||
## Headline Numbers
|
||||
|
||||
| Metric | Value |
|
||||
|---|---|
|
||||
| Customers at start of period | [N] |
|
||||
| Customers churned | [N] |
|
||||
| **Customer churn rate** | **[X]%** |
|
||||
| ARR at start of period | £/$/€[X] |
|
||||
| ARR lost to churn | £/$/€[X] |
|
||||
| **Revenue churn rate (gross)** | **[X]%** |
|
||||
| ARR from expansions (same period) | £/$/€[X] |
|
||||
| **Net revenue retention (NRR)** | **[X]%** |
|
||||
|
||||
**Benchmark context:**
|
||||
- Customer churn rate: [X]% vs. industry benchmark [Y]% — [above / below / in line]
|
||||
- NRR: [X]% — [What this means: above 100% = expansion offsets churn; below 100% = shrinking base]
|
||||
|
||||
---
|
||||
|
||||
## Churn Breakdown by Category
|
||||
|
||||
| Category | Customers | % of churn | ARR lost |
|
||||
|---|---|---|---|
|
||||
| Voluntary — avoidable | [N] | [X]% | £/$/€[X] |
|
||||
| Voluntary — unavoidable | [N] | [X]% | £/$/€[X] |
|
||||
| Involuntary | [N] | [X]% | £/$/€[X] |
|
||||
| **Total** | **[N]** | **100%** | **£/$/€[X]** |
|
||||
|
||||
**Avoidable churn as % of total churn:** [X]% — this is the number we can actually influence.
|
||||
|
||||
---
|
||||
|
||||
## Churn Reasons — Avoidable Churn Only
|
||||
|
||||
Rank by frequency. Include ARR weight where data allows.
|
||||
|
||||
| Reason | Count | % of avoidable churn | ARR lost | Representative quote |
|
||||
|---|---|---|---|---|
|
||||
| [Reason 1 — e.g. "Product missing key feature"] | [N] | [X]% | £/$/€[X] | "[Quote]" |
|
||||
| [Reason 2] | [N] | [X]% | £/$/€[X] | "[Quote]" |
|
||||
| [Reason 3] | [N] | [X]% | £/$/€[X] | "[Quote]" |
|
||||
| [Reason 4] | [N] | [X]% | £/$/€[X] | "[Quote]" |
|
||||
| Other | [N] | [X]% | £/$/€[X] | — |
|
||||
|
||||
**Theme synthesis:** [2–3 sentences grouping the top reasons into 2–3 themes. E.g. "The top three reasons cluster around two themes: product gaps in [area] (affecting X% of avoidable churn) and onboarding failures where customers never achieved value (Y%)."]
|
||||
|
||||
---
|
||||
|
||||
## Churn by Segment
|
||||
|
||||
Identify which segments over- or under-index for churn.
|
||||
|
||||
### By Tier
|
||||
|
||||
| Tier | Churn rate | vs. Overall | Notes |
|
||||
|---|---|---|---|
|
||||
| Enterprise | [X]% | +/-[X]pp | |
|
||||
| Mid-Market | [X]% | +/-[X]pp | |
|
||||
| SMB | [X]% | +/-[X]pp | |
|
||||
|
||||
### By Cohort (Acquisition Year)
|
||||
|
||||
| Cohort | Churn rate | Notes |
|
||||
|---|---|---|
|
||||
| [Year 1] | [X]% | |
|
||||
| [Year 2] | [X]% | |
|
||||
| [Year 3] | [X]% | |
|
||||
|
||||
### By Industry / Use Case (if data available)
|
||||
|
||||
| Segment | Churn rate | Notes |
|
||||
|---|---|---|
|
||||
| [Segment 1] | [X]% | |
|
||||
| [Segment 2] | [X]% | |
|
||||
|
||||
**Key pattern:** [Which segment has the highest churn rate and what likely explains it]
|
||||
|
||||
---
|
||||
|
||||
## Timing Analysis
|
||||
|
||||
- **Average contract length before churn:** [X months]
|
||||
- **Highest-risk moment:** [e.g. "Month 3 — when trial value has worn off but full adoption hasn't happened"]
|
||||
- **Churn timing distribution:**
|
||||
|
||||
| When churn occurred | % of churned accounts |
|
||||
|---|---|
|
||||
| 0–3 months | [X]% |
|
||||
| 3–6 months | [X]% |
|
||||
| 6–12 months | [X]% |
|
||||
| 12+ months | [X]% |
|
||||
|
||||
---
|
||||
|
||||
## Early Warning Signals
|
||||
|
||||
Based on the churned accounts, identify the signals that preceded churn (and could have triggered earlier intervention):
|
||||
|
||||
| Signal | Lead time before churn | How to detect |
|
||||
|---|---|---|
|
||||
| [Signal 1 — e.g. "DAU/MAU dropped below 15%"] | [~X weeks] | [Usage dashboard / alert] |
|
||||
| [Signal 2 — e.g. "No QBR in 90+ days"] | [~X weeks] | [CRM flag] |
|
||||
| [Signal 3 — e.g. "Champion left the account"] | [~X weeks] | [LinkedIn alert / CSM tracking] |
|
||||
| [Signal 4] | [~X weeks] | [Detection method] |
|
||||
|
||||
---
|
||||
|
||||
## Intervention Recommendations
|
||||
|
||||
Ranked by estimated impact × feasibility.
|
||||
|
||||
| Intervention | Addresses | Est. churn reduction | Effort | Owner |
|
||||
|---|---|---|---|---|
|
||||
| [Intervention 1 — e.g. "Improve onboarding for [segment] with dedicated 30-day check-in"] | [Reason 1] | [X accounts / £X ARR] | Low / Med / High | [Team] |
|
||||
| [Intervention 2] | [Reason 2] | [X accounts / £X ARR] | Low / Med / High | [Team] |
|
||||
| [Intervention 3] | [Reason 3] | [X accounts / £X ARR] | Low / Med / High | [Team] |
|
||||
|
||||
**Priority call:** [Which one intervention, if implemented this quarter, would have the biggest impact and why]
|
||||
|
||||
---
|
||||
|
||||
## What We Don't Know (Data Gaps)
|
||||
|
||||
- [Data gap 1 — e.g. "Exit survey response rate is only 30% — the reasons data may not be representative"]
|
||||
- [Data gap 2 — e.g. "No product usage data for SMB tier — can't confirm usage signal correlation"]
|
||||
- [Data gap 3]
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Churn rate is correctly calculated (churned ÷ starting cohort, not end-of-period total)
|
||||
- [ ] Avoidable and unavoidable churn are separated — interventions target avoidable churn only
|
||||
- [ ] Churn reasons are customer-reported, not internally assumed
|
||||
- [ ] Segment analysis identifies which segments over-index — not just averages
|
||||
- [ ] Early warning signals are specific and detectable, not generic ("low engagement")
|
||||
- [ ] Interventions link directly to the top churn reasons — no recommendations without a root cause match
|
||||
@@ -0,0 +1,176 @@
|
||||
---
|
||||
name: cs-escalation-brief
|
||||
description: "Write a structured escalation brief for an at-risk customer account. Use when an account has escalated, when a customer is threatening churn, when a P1 customer issue needs executive attention, or when preparing an internal save play. Produces a crisp escalation brief with account context, timeline, root cause, business impact, and a clear resolution plan."
|
||||
---
|
||||
|
||||
# Customer Escalation Brief Skill
|
||||
|
||||
Produce a clear, concise escalation brief that gives internal stakeholders — VP CS, CCO, product leadership, or the CEO — everything they need to understand the situation, make decisions, and act fast.
|
||||
|
||||
A good escalation brief is not a complaint. It is a professional document that states the facts, assigns accountability honestly, and proposes a specific resolution plan.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask for these if not already provided:
|
||||
- **Account name**, tier, and ARR
|
||||
- **CSM name** and account owner
|
||||
- **Nature of the escalation** — what happened, what the customer is saying
|
||||
- **Timeline** of events leading to escalation
|
||||
- **Customer contact** who escalated (name, role, influence level)
|
||||
- **What the customer wants** — their stated ask
|
||||
- **What we believe the root cause is**
|
||||
- **What has already been done** to address the situation
|
||||
- **Renewal date** and current renewal risk assessment
|
||||
|
||||
## Escalation Levels
|
||||
|
||||
Calibrate urgency and audience based on escalation level:
|
||||
|
||||
| Level | Trigger | Audience | Response time |
|
||||
|---|---|---|---|
|
||||
| L1 — Account Risk | Customer expressing dissatisfaction; renewal at risk | CSM + CS Manager | 24 hours |
|
||||
| L2 — Executive Escalation | Customer escalated to their exec; requesting vendor exec involvement | VP CS + Account Exec | 4 hours |
|
||||
| L3 — Churn Risk | Customer has issued notice or is in active churn conversation | CCO / CEO + Revenue leadership | 1 hour |
|
||||
| L4 — Public Risk | Customer threatening public escalation, legal, or press | CCO / Legal / Comms | Immediate |
|
||||
|
||||
## Output Format
|
||||
|
||||
---
|
||||
|
||||
# Escalation Brief: [Account Name]
|
||||
|
||||
**Escalation level:** L[1/2/3/4] — [Label]
|
||||
**Date raised:** [Date]
|
||||
**Raised by:** [CSM name]
|
||||
**Escalation owner:** [Name of exec or senior stakeholder now leading response]
|
||||
|
||||
---
|
||||
|
||||
## Account at a Glance
|
||||
|
||||
| Field | Detail |
|
||||
|---|---|
|
||||
| ARR | £/$/€[X] |
|
||||
| Tier | Enterprise / Mid-Market / SMB |
|
||||
| Customer since | [Date] |
|
||||
| Renewal date | [Date] — [N] days away |
|
||||
| Renewal risk (pre-escalation) | Green / Amber / Red |
|
||||
| Renewal risk (current) | Green / Amber / Red |
|
||||
| Customer contact who escalated | [Name, role, seniority] |
|
||||
| Executive sponsor (customer) | [Name, role — active / passive / vacant] |
|
||||
| Executive sponsor (vendor) | [Name, role] |
|
||||
|
||||
---
|
||||
|
||||
## What Happened — Summary
|
||||
|
||||
[3–5 sentences. State the facts plainly. What the customer experienced, how they reacted, and how we learned about the escalation. No editorialising. No blame.]
|
||||
|
||||
---
|
||||
|
||||
## Timeline
|
||||
|
||||
List in chronological order. Each entry: `[Date / time] — [What happened. Who did what.]`
|
||||
|
||||
Include:
|
||||
- When the original issue or trigger event occurred
|
||||
- When the customer first raised concerns (informally)
|
||||
- When it escalated (formal escalation or exec involvement)
|
||||
- Actions taken since escalation
|
||||
|
||||
---
|
||||
|
||||
## Root Cause
|
||||
|
||||
**Primary cause:** [One clear sentence. What specifically went wrong.]
|
||||
|
||||
**Contributing factors:**
|
||||
- [Factor 1 — be honest about internal failures as well as external ones]
|
||||
- [Factor 2]
|
||||
|
||||
**Is this a systemic issue or isolated?**
|
||||
[ ] Isolated to this account
|
||||
[ ] Pattern seen in other accounts — details: [_______]
|
||||
[ ] Product or process gap that needs fixing
|
||||
|
||||
---
|
||||
|
||||
## Customer's Stated Position
|
||||
|
||||
**What the customer says happened:** [Their version of events — fair and unfiltered]
|
||||
|
||||
**What they are asking for:** [Their explicit ask — compensation, fix by date, exec call, SLA credit, exit clause]
|
||||
|
||||
**Sentiment of escalating contact:** [Frustrated but constructive / Angry / Seeking exit / Unknown]
|
||||
|
||||
**Risk of public escalation:** Low / Medium / High — [evidence if Medium or High]
|
||||
|
||||
---
|
||||
|
||||
## Business Impact
|
||||
|
||||
| Impact type | Detail |
|
||||
|---|---|
|
||||
| ARR at risk | £/$/€[X] |
|
||||
| Potential churn probability | [X]% |
|
||||
| Reputational risk | Low / Medium / High |
|
||||
| Reference / case study status | [Was a reference — now at risk / Not a reference] |
|
||||
| Expansion pipeline at risk | £/$/€[X] |
|
||||
|
||||
---
|
||||
|
||||
## What Has Been Done So Far
|
||||
|
||||
1. [Action taken — by whom — date — outcome]
|
||||
2. [Action taken — by whom — date — outcome]
|
||||
3. [Action taken — by whom — date — outcome]
|
||||
|
||||
**Has a formal apology or acknowledgement been issued?** Yes / No
|
||||
|
||||
---
|
||||
|
||||
## Proposed Resolution Plan
|
||||
|
||||
**Immediate actions (next 24–48 hours):**
|
||||
|
||||
| Action | Owner | By when |
|
||||
|---|---|---|
|
||||
| [Action] | [Name] | [Date] |
|
||||
| [Action] | [Name] | [Date] |
|
||||
|
||||
**Medium-term actions (next 2–4 weeks):**
|
||||
|
||||
| Action | Owner | By when |
|
||||
|---|---|---|
|
||||
| [Action] | [Name] | [Date] |
|
||||
|
||||
**What we are NOT offering:** [Be explicit about what is not on the table — avoids misaligned expectations]
|
||||
|
||||
**Success criteria:** [How will we know the escalation is resolved? What does the customer need to confirm they are satisfied?]
|
||||
|
||||
---
|
||||
|
||||
## Decision Required from Escalation Owner
|
||||
|
||||
[State clearly what decision or resource the escalation owner needs to provide. Be specific — do not make them ask. E.g.: "We need approval to offer a 20% service credit for Q2" or "We need an exec call with [name] within 48 hours."]
|
||||
|
||||
---
|
||||
|
||||
## Communication Plan
|
||||
|
||||
| Audience | Message | Channel | Owner | By when |
|
||||
|---|---|---|---|---|
|
||||
| Escalating customer contact | [Summary of message] | Email / Call | [Name] | [Date] |
|
||||
| Customer exec sponsor | [Summary] | Call | [Name] | [Date] |
|
||||
| Internal CS team | [Summary] | Slack / Meeting | CS Manager | [Date] |
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Root cause is specific — not "communication breakdown" or "product gap" without detail
|
||||
- [ ] Customer's position is stated fairly — not minimised or dismissed
|
||||
- [ ] A clear decision is requested from the escalation owner — brief does not end with "what do you think?"
|
||||
- [ ] ARR at risk is quantified
|
||||
- [ ] Communication plan has owners and dates — not "TBD"
|
||||
- [ ] Language is professional and blameless toward individuals
|
||||
@@ -0,0 +1,141 @@
|
||||
---
|
||||
name: cs-health-scorecard
|
||||
description: "Build a customer health scorecard for a specific account. Use when asked to score account health, assess renewal risk, build a health dashboard, or evaluate an account's likelihood to renew or expand. Produces a structured health scorecard with a RAG status, dimension scores, key risks, and recommended actions."
|
||||
---
|
||||
|
||||
# Customer Health Scorecard Skill
|
||||
|
||||
Produce a structured, data-driven health scorecard for a customer account — giving the CSM and leadership a clear view of renewal risk, expansion potential, and the actions needed to move the account in the right direction.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask for these if not already provided:
|
||||
- **Account name** and tier (enterprise / mid-market / SMB)
|
||||
- **Contract value** (ARR) and **renewal date**
|
||||
- **Product usage data** — logins, DAU/MAU ratio, key feature adoption
|
||||
- **Support data** — open tickets, CSAT or NPS score, recent escalations
|
||||
- **Engagement data** — last QBR date, executive sponsor status, champion name
|
||||
- **Commercial data** — payment history, expansion conversations, seats used vs. licensed
|
||||
- **Any known risks or recent changes** at the account
|
||||
|
||||
## Scoring Framework
|
||||
|
||||
Score each dimension 1–5. Weight as shown. Calculate weighted total out of 100.
|
||||
|
||||
| Dimension | Weight | What to Score |
|
||||
|---|---|---|
|
||||
| **Product Adoption** | 30% | DAU/MAU ratio, breadth of features used, power users identified |
|
||||
| **Engagement** | 20% | QBR cadence, executive sponsor active, champion strength |
|
||||
| **Outcomes** | 20% | Customer hitting their stated goals / success metrics |
|
||||
| **Support Health** | 15% | Ticket volume trend, unresolved escalations, CSAT |
|
||||
| **Commercial** | 15% | On-time payments, seats utilised, expansion signals |
|
||||
|
||||
**Score → RAG conversion:**
|
||||
- 80–100: Green (healthy, renew likely)
|
||||
- 60–79: Amber (at risk, needs attention)
|
||||
- 0–59: Red (high churn risk, escalate)
|
||||
|
||||
## Output Format
|
||||
|
||||
---
|
||||
|
||||
# Customer Health Scorecard: [Account Name]
|
||||
|
||||
**CSM:** [Name] | **Tier:** [Enterprise / Mid-Market / SMB]
|
||||
**ARR:** £/$/€[X] | **Renewal date:** [Date] | **Days to renewal:** [N]
|
||||
**Overall health:** [Green / Amber / Red] — [Score]/100
|
||||
**Last updated:** [Date]
|
||||
|
||||
---
|
||||
|
||||
## Health Score Summary
|
||||
|
||||
| Dimension | Score (1–5) | Weight | Weighted Score | Trend |
|
||||
|---|---|---|---|---|
|
||||
| Product Adoption | [1–5] | 30% | [X] | ↑ / → / ↓ |
|
||||
| Engagement | [1–5] | 20% | [X] | ↑ / → / ↓ |
|
||||
| Outcomes | [1–5] | 20% | [X] | ↑ / → / ↓ |
|
||||
| Support Health | [1–5] | 15% | [X] | ↑ / → / ↓ |
|
||||
| Commercial | [1–5] | 15% | [X] | ↑ / → / ↓ |
|
||||
| **Total** | — | 100% | **[X]/100** | |
|
||||
|
||||
---
|
||||
|
||||
## Dimension Detail
|
||||
|
||||
### Product Adoption — [Score]/5
|
||||
- **DAU/MAU ratio:** [X]% (benchmark: >25% = healthy)
|
||||
- **Key features adopted:** [List features in use]
|
||||
- **Features not adopted:** [List unused high-value features]
|
||||
- **Power users identified:** [Yes / No — how many]
|
||||
- **Assessment:** [1–2 sentences on adoption health]
|
||||
|
||||
### Engagement — [Score]/5
|
||||
- **Last QBR:** [Date] — [Outcome summary]
|
||||
- **Next QBR:** [Scheduled / Overdue]
|
||||
- **Executive sponsor:** [Active / Passive / Vacant]
|
||||
- **Champion:** [Name, role, strength: strong / moderate / weak]
|
||||
- **Assessment:** [1–2 sentences]
|
||||
|
||||
### Outcomes — [Score]/5
|
||||
- **Customer's stated goals:** [List 2–3 goals from onboarding or last QBR]
|
||||
- **Progress against goals:** [On track / Partial / Off track]
|
||||
- **Evidence of value:** [Metric or quote that demonstrates ROI]
|
||||
- **Assessment:** [1–2 sentences]
|
||||
|
||||
### Support Health — [Score]/5
|
||||
- **Open tickets:** [N] (priority breakdown: P1: X, P2: X, P3: X)
|
||||
- **CSAT / NPS:** [Score] (benchmark: >8 CSAT / >30 NPS = healthy)
|
||||
- **Unresolved escalations:** [Yes / No — details if yes]
|
||||
- **Ticket trend (last 90 days):** Increasing / Stable / Decreasing
|
||||
- **Assessment:** [1–2 sentences]
|
||||
|
||||
### Commercial — [Score]/5
|
||||
- **Seats licensed:** [N] | **Seats active:** [N] ([X]% utilisation)
|
||||
- **Payment history:** [On time / Late — details]
|
||||
- **Expansion signals:** [Yes — describe / No]
|
||||
- **Downgrade or cancellation signals:** [Yes — describe / No]
|
||||
- **Assessment:** [1–2 sentences]
|
||||
|
||||
---
|
||||
|
||||
## Top Risks
|
||||
|
||||
| Risk | Severity | Mitigation |
|
||||
|---|---|---|
|
||||
| [Risk description] | High / Medium / Low | [Specific action to mitigate] |
|
||||
|
||||
---
|
||||
|
||||
## Recommended Actions
|
||||
|
||||
**Immediate (this week):**
|
||||
1. [Action — owner — deadline]
|
||||
|
||||
**This month:**
|
||||
1. [Action — owner — deadline]
|
||||
|
||||
**Before renewal:**
|
||||
1. [Action — owner — deadline]
|
||||
|
||||
---
|
||||
|
||||
## Renewal Forecast
|
||||
|
||||
| Scenario | Probability | ARR at risk |
|
||||
|---|---|---|
|
||||
| Full renewal at current ARR | [X]% | £/$/€0 |
|
||||
| Renewal with contraction | [X]% | £/$/€[X] |
|
||||
| Churn | [X]% | £/$/€[full ARR] |
|
||||
|
||||
**Recommended renewal play:** [Expand / Hold / Save / Manage out]
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Score is based on data, not gut feel — each dimension has evidence
|
||||
- [ ] Risks are specific (not "low engagement" — something like "executive sponsor left in March, no replacement identified")
|
||||
- [ ] Actions have owners and deadlines
|
||||
- [ ] Renewal probability is calibrated against pipeline reality
|
||||
- [ ] Trend arrows reflect direction of change vs. last scorecard, not just current state
|
||||
@@ -0,0 +1,218 @@
|
||||
---
|
||||
name: qbr-deck
|
||||
description: "Build a Quarterly Business Review (QBR) deck structure and narrative for a customer account. Use when asked to prepare a QBR, business review meeting, executive review, or quarterly check-in with a customer. Produces a slide-by-slide QBR structure with talking points, metrics review, value narrative, and mutual next steps."
|
||||
---
|
||||
|
||||
# QBR Deck Skill
|
||||
|
||||
Produce a complete Quarterly Business Review deck — structured, data-backed, and customer-focused. A good QBR demonstrates value delivered, aligns on goals for the next quarter, and strengthens the executive relationship. It should never feel like a product demo or a vendor update.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask for these if not already provided:
|
||||
- **Account name**, CSM name, and customer stakeholders attending
|
||||
- **Contract details** — ARR, contract start date, renewal date
|
||||
- **Last quarter's goals** (from previous QBR or kickoff)
|
||||
- **Usage and adoption data** — key metrics for the quarter
|
||||
- **Support summary** — tickets raised, resolution time, any escalations
|
||||
- **Business outcomes the customer cares about** — what success looks like for them
|
||||
- **Product updates or new features** relevant to this customer
|
||||
- **Goals for next quarter**
|
||||
- **Any open commercial conversations** (expansion, renewal, at-risk signals)
|
||||
|
||||
## QBR Principles
|
||||
|
||||
- Lead with customer outcomes, not product features
|
||||
- Every metric should connect to a business result the customer cares about
|
||||
- The agenda is a conversation, not a presentation — build in time for customer input at every stage
|
||||
- Close with mutual commitments, not just vendor actions
|
||||
|
||||
## Output Format
|
||||
|
||||
---
|
||||
|
||||
# QBR: [Account Name] × [Your Company]
|
||||
**[Quarter] [Year] Business Review**
|
||||
|
||||
**Date:** [Date] | **Location / Call link:** [TBC]
|
||||
**Customer attendees:** [Names and roles]
|
||||
**[Your company] attendees:** [Names and roles]
|
||||
|
||||
---
|
||||
|
||||
## Slide 1: Agenda (5 min)
|
||||
|
||||
| Time | Topic | Owner |
|
||||
|---|---|---|
|
||||
| 0:00 | Welcome and introductions | CSM |
|
||||
| 0:05 | [Last quarter] — how did we do? | CSM + Customer |
|
||||
| 0:20 | Value delivered — business impact | CSM |
|
||||
| 0:35 | What's coming — roadmap preview | CSM / Product |
|
||||
| 0:45 | [Next quarter] — goals and priorities | Customer |
|
||||
| 0:55 | Actions and mutual commitments | CSM |
|
||||
| 1:00 | Close | |
|
||||
|
||||
*Talking point: "We've kept today to 60 minutes. We want as much of this to be a conversation as possible — please push back, redirect, and ask questions throughout."*
|
||||
|
||||
---
|
||||
|
||||
## Slide 2: Where We Are Together (2 min)
|
||||
|
||||
**Partnership snapshot:**
|
||||
- **Customer since:** [Date]
|
||||
- **Contract value:** £/$/€[ARR]/year
|
||||
- **Renewal date:** [Date]
|
||||
- **Active users:** [N] of [N] licensed seats ([X]% adoption)
|
||||
- **Products / modules active:** [List]
|
||||
|
||||
*Talking point: "Before we dive in — a quick picture of where we are. [X] months in, [Y] active users, and this is our [Nth] QBR together."*
|
||||
|
||||
---
|
||||
|
||||
## Slide 3: Last Quarter — Goals We Set Together (5 min)
|
||||
|
||||
| Goal | Set in [Last QBR / Kickoff] | Status |
|
||||
|---|---|---|
|
||||
| [Goal 1] | [What we committed to] | ✅ Achieved / ⚠️ Partial / ❌ Missed |
|
||||
| [Goal 2] | [What we committed to] | ✅ Achieved / ⚠️ Partial / ❌ Missed |
|
||||
| [Goal 3] | [What we committed to] | ✅ Achieved / ⚠️ Partial / ❌ Missed |
|
||||
|
||||
For any partial or missed goal: state what happened and what changes next quarter.
|
||||
|
||||
*Talking point: "Let's start with accountability. Here's what we said we'd achieve last quarter — let's be honest about where we landed."*
|
||||
|
||||
---
|
||||
|
||||
## Slide 4: Usage and Adoption (5 min)
|
||||
|
||||
**Quarter-over-quarter trend:**
|
||||
|
||||
| Metric | [Q-1] | [Q] | Change |
|
||||
|---|---|---|---|
|
||||
| Monthly active users | [N] | [N] | +/-X% |
|
||||
| Sessions per user per week | [N] | [N] | +/-X% |
|
||||
| [Key feature 1] adoption | [X]% | [X]% | +/-X% |
|
||||
| [Key feature 2] adoption | [X]% | [X]% | +/-X% |
|
||||
|
||||
**Highlights:**
|
||||
- [Positive adoption trend to call out]
|
||||
- [Feature or workflow with strongest engagement]
|
||||
|
||||
**Opportunity:**
|
||||
- [Feature with low adoption that could drive more value — link to their goals]
|
||||
|
||||
*Talking point: "Usage is [up / stable / something we want to talk about]. The area I'd like to focus on is [feature] — we're not seeing the adoption we'd expect given [their goal], and I want to understand why."*
|
||||
|
||||
---
|
||||
|
||||
## Slide 5: Business Impact — Value Delivered (10 min)
|
||||
|
||||
Lead with outcomes, not activity.
|
||||
|
||||
**[Outcome 1: customer's primary success metric]**
|
||||
- Before: [baseline]
|
||||
- Now: [current state]
|
||||
- Impact: [quantified business result — time saved, revenue influenced, cost reduced, risk mitigated]
|
||||
|
||||
**[Outcome 2]**
|
||||
- [Same structure]
|
||||
|
||||
**[Outcome 3]**
|
||||
- [Same structure]
|
||||
|
||||
**Customer evidence** (use if available):
|
||||
> "[Quote from champion or user about value experienced]"
|
||||
|
||||
*Talking point: "This is the section I most want your input on. Are these the outcomes that matter to your business? Are there other ways you're measuring success that we should be tracking?"*
|
||||
|
||||
---
|
||||
|
||||
## Slide 6: Support Summary (3 min)
|
||||
|
||||
| Metric | This quarter | Last quarter | Trend |
|
||||
|---|---|---|---|
|
||||
| Tickets raised | [N] | [N] | ↑ / → / ↓ |
|
||||
| Average resolution time | [X hrs] | [X hrs] | ↑ / → / ↓ |
|
||||
| P1 / critical issues | [N] | [N] | ↑ / → / ↓ |
|
||||
| CSAT score | [X/10] | [X/10] | ↑ / → / ↓ |
|
||||
|
||||
**Notable issues this quarter:**
|
||||
- [Any escalation or major ticket — brief summary and resolution]
|
||||
|
||||
**What we're doing differently:**
|
||||
- [Any process change or improvement based on support patterns]
|
||||
|
||||
---
|
||||
|
||||
## Slide 7: What's Coming — Roadmap Preview (5 min)
|
||||
|
||||
Focus only on what's relevant to this customer's goals. Do not dump the full roadmap.
|
||||
|
||||
| Feature / Improvement | Expected | Why it matters to [Account Name] |
|
||||
|---|---|---|
|
||||
| [Feature 1] | [Q+1] | [Direct link to their goal or pain point] |
|
||||
| [Feature 2] | [Q+1 / Q+2] | [Direct link] |
|
||||
| [Feature 3] | [H2] | [Direct link] |
|
||||
|
||||
*Talking point: "I've filtered the roadmap to what I think matters most to your team. I'd love your reaction — are these the right priorities from your perspective?"*
|
||||
|
||||
---
|
||||
|
||||
## Slide 8: Next Quarter — Your Goals (10 min)
|
||||
|
||||
**Customer input section — facilitate, don't present.**
|
||||
|
||||
Prompt questions:
|
||||
- "What does success look like for your team in [next quarter]?"
|
||||
- "What's the biggest challenge you're trying to solve in the next 90 days?"
|
||||
- "Is there anything about the way you're using [product] you want to change?"
|
||||
|
||||
**Capture live:**
|
||||
|
||||
| Goal for next quarter | Owner (customer) | How we'll support it | How we'll measure it |
|
||||
|---|---|---|---|
|
||||
| [Goal 1] | [Name] | [CSM / product action] | [Metric] |
|
||||
| [Goal 2] | [Name] | [CSM / product action] | [Metric] |
|
||||
|
||||
---
|
||||
|
||||
## Slide 9: Mutual Commitments (5 min)
|
||||
|
||||
**[Your company] commits to:**
|
||||
1. [Specific action — owner — by when]
|
||||
2. [Specific action — owner — by when]
|
||||
3. [Specific action — owner — by when]
|
||||
|
||||
**[Account Name] commits to:**
|
||||
1. [Specific action — owner — by when]
|
||||
2. [Specific action — owner — by when]
|
||||
|
||||
**Next touchpoint:** [Date of next check-in or mid-quarter review]
|
||||
|
||||
---
|
||||
|
||||
## Slide 10: Thank You + Open Q&A (5 min)
|
||||
|
||||
- Recap the one headline from today: [The single most important thing you want them to remember]
|
||||
- Confirm actions are captured and shared after the call
|
||||
- Ask: "Is there anything we didn't cover today that you wanted to raise?"
|
||||
|
||||
---
|
||||
|
||||
## Preparation Checklist
|
||||
|
||||
- [ ] Usage data pulled and QoQ comparison calculated
|
||||
- [ ] Last QBR goals reviewed — status confirmed before the meeting
|
||||
- [ ] Business outcomes framed in customer language (not product language)
|
||||
- [ ] Roadmap filtered to this account's specific use cases
|
||||
- [ ] Customer's goals for next quarter researched or pre-confirmed with champion
|
||||
- [ ] Executive sponsor briefed on any sensitive topics before the call
|
||||
- [ ] Actions from previous QBR reviewed — any outstanding items addressed
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Every slide has a talking point, not just a title
|
||||
- [ ] Value slide leads with business outcomes, not product activity
|
||||
- [ ] Roadmap preview links each item to a customer goal
|
||||
- [ ] Mutual commitments section has real owners on both sides
|
||||
- [ ] Customer has at least 20 minutes of airtime in the agenda
|
||||
Vendored
BIN
Binary file not shown.
@@ -0,0 +1,13 @@
|
||||
{
|
||||
"$schema": "https://anthropic.com/claude-code/plugin.schema.json",
|
||||
"name": "pm-data",
|
||||
"version": "1.0.0",
|
||||
"description": "Data & analytics skills: Metrics Framework, SQL Query Explainer, Dashboard Brief. Build North Star metric trees, explain and optimise SQL, and spec dashboards from business questions.",
|
||||
"author": {
|
||||
"name": "Mohit Aggarwal",
|
||||
"email": "mohit15856@gmail.com"
|
||||
},
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills",
|
||||
"license": "MIT",
|
||||
"keywords": ["product-management", "data", "analytics", "metrics", "north-star", "sql", "dashboard", "kpi"]
|
||||
}
|
||||
@@ -0,0 +1,95 @@
|
||||
---
|
||||
name: chart-data-extractor
|
||||
description: "Extract pixel-level data from an image of a chart or graph and produce a structured data table. Use when asked to extract data from a chart image, transcribe numbers from a graph, digitise a chart, or turn a screenshot of data into a table. Produces a structured table with extracted values, confidence levels, and a reconstructed chart source. Best used with Claude Opus 4.7 or newer for reliable chart data extraction."
|
||||
---
|
||||
|
||||
# Chart Data Extractor Skill
|
||||
|
||||
Extracts data from images of charts and graphs — bar charts, line charts, pie charts, scatter plots, and tables in images — producing a structured data table that can be used in spreadsheets or rebuilt in any charting tool. Built to leverage Opus 4.7 pixel-level image analysis capabilities.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **The chart image** (upload a screenshot or image file)
|
||||
- **Chart type** (if ambiguous — bar / line / pie / scatter / other)
|
||||
- **What matters most** (approximate trends / precise values / specific data points / categorisation)
|
||||
- **Known axis values** (optional — if the user knows the max/min values to anchor the extraction)
|
||||
|
||||
## Output Structure
|
||||
|
||||
### 1. Chart Identification
|
||||
|
||||
| Attribute | Value |
|
||||
|---|---|
|
||||
| Chart type | [Bar / Line / Pie / Scatter / Area / Other] |
|
||||
| Chart title (if visible) | [Title text] |
|
||||
| X-axis label | [Label + unit] |
|
||||
| Y-axis label | [Label + unit] |
|
||||
| Number of series | N |
|
||||
| Legend categories | [List] |
|
||||
| Data period (if time-based) | [Start — End] |
|
||||
|
||||
### 2. Extracted Data Table
|
||||
|
||||
| [X axis] | [Series 1] | [Series 2] | ... |
|
||||
|---|---|---|---|
|
||||
| [Value] | [Value] | [Value] | |
|
||||
|
||||
### 3. Confidence Levels
|
||||
|
||||
For each data point or series, flag confidence:
|
||||
|
||||
- **High confidence:** data points where the value is clearly readable against gridlines or labels
|
||||
- **Medium confidence:** data points where the value is interpolated between gridlines
|
||||
- **Low confidence:** data points where the value is ambiguous or overlaps with other elements
|
||||
|
||||
Low-confidence points should be explicitly listed — not silently included in the main table.
|
||||
|
||||
### 4. Notable Observations
|
||||
|
||||
Observations that the data itself reveals:
|
||||
- Peak value: [Value, when, in which series]
|
||||
- Lowest value: [Value, when, in which series]
|
||||
- Largest delta between series: [Details]
|
||||
- Any anomalies or outliers visible in the chart
|
||||
|
||||
### 5. Reconstructed Source
|
||||
|
||||
CSV format for direct use:
|
||||
|
||||
```csv
|
||||
[x_axis],[series_1],[series_2]
|
||||
[value],[value],[value]
|
||||
```
|
||||
|
||||
### 6. Assumptions and Caveats
|
||||
|
||||
- Grid resolution: [How precisely values could be read — e.g. "Y-axis has major gridlines every 10 units, minor every 2"]
|
||||
- Interpolation used: [Any values that required estimating between gridlines]
|
||||
- Unclear data: [Anything in the chart that could not be read reliably]
|
||||
- Axis scale: [Linear/logarithmic/etc — note if not obvious]
|
||||
|
||||
### 7. Follow-up Options
|
||||
|
||||
Ask the user which of these they want:
|
||||
- Rebuild the chart in a specified format (Excel formula, Python matplotlib, D3, etc.)
|
||||
- Produce a narrative description of what the chart shows
|
||||
- Compare this data against another chart or source
|
||||
- Flag potentially misleading visual choices in the original (truncated axes, misleading scales, etc.)
|
||||
|
||||
## Quality Checks
|
||||
- [ ] Every extracted number specifies which series it belongs to
|
||||
- [ ] Confidence levels are explicit for ambiguous points
|
||||
- [ ] Low-confidence values are flagged separately, not silently included
|
||||
- [ ] Assumptions about axis scale and interpolation are stated
|
||||
- [ ] CSV output is clean and directly usable
|
||||
|
||||
## Example Trigger Phrases
|
||||
- "Extract the data from this chart"
|
||||
- "Transcribe the numbers in this graph"
|
||||
- "Turn this chart image into a spreadsheet"
|
||||
- "Digitise this chart so I can rebuild it"
|
||||
- "What are the exact values in this bar chart?"
|
||||
|
||||
## Why This Works Better on Opus 4.7
|
||||
Earlier models struggled with pixel-level data transcription from charts, often hallucinating values or misreading gridline positions. Opus 4.7 uses a higher image resolution (2576px vs 1568px) with coordinates mapping 1:1 to pixels, making chart data extraction reliable for practical use.
|
||||
@@ -0,0 +1,122 @@
|
||||
---
|
||||
name: dashboard-brief
|
||||
description: "Convert a business question into a complete dashboard specification. Use when asked to design a dashboard, create a dashboard spec or brief, plan a BI report, or define what charts and metrics a dashboard should include. Produces a structured spec with metrics, dimensions, chart types, filters, and layout guidance."
|
||||
---
|
||||
|
||||
# Dashboard Brief Skill
|
||||
|
||||
This skill converts a business question or monitoring need into a complete, implementation-ready dashboard specification. The output gives a data engineer or BI developer everything they need to build without a follow-up meeting.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **The business question this dashboard should answer** (e.g. "How is our activation funnel performing this week?")
|
||||
- **Primary audience** (exec / product team / operations / customer success / engineering)
|
||||
- **Refresh cadence** (real-time / hourly / daily / weekly)
|
||||
- **Data sources available** (e.g. Postgres, BigQuery, Mixpanel, Salesforce, Jira)
|
||||
- **BI tool being used** (Looker / Metabase / Tableau / Power BI / Grafana / Custom / Unknown)
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# Dashboard Brief: [Dashboard Name]
|
||||
|
||||
**Business Question:** [The question this dashboard answers — verbatim from inputs or refined]
|
||||
**Audience:** [Who uses this]
|
||||
**Refresh Rate:** [Real-time / Hourly / Daily / Weekly]
|
||||
**Data Sources:** [List]
|
||||
**BI Tool:** [Tool or Unknown]
|
||||
|
||||
---
|
||||
|
||||
## Section 1: Key Metrics (KPI Cards)
|
||||
|
||||
List the headline numbers that should appear at the top of the dashboard as KPI cards.
|
||||
|
||||
| Metric | Definition | Data Source | Comparison |
|
||||
|---|---|---|---|
|
||||
| [Metric name] | [How it's calculated] | [Table/source] | [vs. last week / vs. target / MoM] |
|
||||
|
||||
Aim for 3–6 KPI cards. More than 6 is noise.
|
||||
|
||||
---
|
||||
|
||||
## Section 2: Charts & Visualisations
|
||||
|
||||
For each chart, specify:
|
||||
|
||||
### Chart [N]: [Chart Title]
|
||||
|
||||
- **Chart type:** [Line / Bar / Stacked bar / Pie / Funnel / Heatmap / Table / Scatter]
|
||||
- **Why this chart type:** [One sentence — why this type suits this data]
|
||||
- **X-axis / Rows:** [Dimension — e.g. Date, User segment, Product]
|
||||
- **Y-axis / Values:** [Metric — e.g. Count of active users, Revenue]
|
||||
- **Breakdown/colour:** [Optional secondary dimension — e.g. by Plan tier, by Channel]
|
||||
- **Data source:** [Table or source]
|
||||
- **Filters:** [Any default filters applied — e.g. "Exclude internal test accounts"]
|
||||
- **Key insight to surface:** [What pattern or signal this chart should help the viewer spot]
|
||||
|
||||
---
|
||||
|
||||
## Section 3: Filters & Controls
|
||||
|
||||
Global filters available to dashboard viewers:
|
||||
|
||||
| Filter | Type | Default | Options |
|
||||
|---|---|---|---|
|
||||
| Date range | Date picker | Last 30 days | Custom |
|
||||
| [Segment filter] | Dropdown | All | [List relevant values] |
|
||||
| [Other filter] | Multi-select | All | [List relevant values] |
|
||||
|
||||
---
|
||||
|
||||
## Section 4: Layout Recommendation
|
||||
|
||||
Describe the dashboard layout in plain terms:
|
||||
|
||||
```
|
||||
[ROW 1 — KPI Cards]: [Metric 1] | [Metric 2] | [Metric 3] | [Metric 4]
|
||||
[ROW 2 — Primary chart, full width]: [Chart name]
|
||||
[ROW 3 — Two charts side by side]: [Chart A] | [Chart B]
|
||||
[ROW 4 — Supporting table, full width]: [Table name]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Section 5: Data Requirements
|
||||
|
||||
List any data transformations, joins, or derived fields needed:
|
||||
|
||||
| Derived Field | Logic | Source Tables |
|
||||
|---|---|---|
|
||||
| [Field name] | [How it's calculated] | [Tables involved] |
|
||||
|
||||
Flag any fields that may not exist in current data infrastructure.
|
||||
|
||||
---
|
||||
|
||||
## Section 6: Access & Ownership
|
||||
|
||||
- **Dashboard owner:** [Leave for user to fill]
|
||||
- **Who can edit:** [Leave for user to fill]
|
||||
- **Who can view:** [Leave for user to fill]
|
||||
- **Review cadence:** [When should this dashboard be reviewed for relevance?]
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Every chart has a stated "key insight to surface" — not just "show the data"
|
||||
- [ ] KPI cards are 3–6 (not more)
|
||||
- [ ] Chart types are justified
|
||||
- [ ] Layout follows visual hierarchy (summary → detail)
|
||||
- [ ] Data requirements section flags any missing fields
|
||||
- [ ] Filters are practical and don't require IT to configure
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Design a dashboard to track [business process]"
|
||||
- "Give me a spec for a [team] performance dashboard"
|
||||
- "What should go on a [topic] dashboard?"
|
||||
- "Write a dashboard brief for our [metric] monitoring"
|
||||
@@ -0,0 +1,103 @@
|
||||
---
|
||||
name: metrics-framework
|
||||
description: "Build a metrics framework for any product, team, or business. Use when asked for a metrics tree, KPI framework, North Star metric, AARRR funnel, HEART framework, or OKR metrics. Produces a structured metrics hierarchy from North Star down to leading indicators, with measurement guidance."
|
||||
---
|
||||
|
||||
# Metrics Framework Skill
|
||||
|
||||
This skill builds a complete metrics framework tailored to a product or business. It connects the North Star metric to actionable leading indicators, making it clear which metrics to track, which to optimise, and how they relate to each other.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Product or business description** (one paragraph is enough)
|
||||
- **Business model** (SaaS / Marketplace / E-commerce / Consumer app / B2B / Other)
|
||||
- **Stage** (Pre-PMF / Growth / Scale / Mature)
|
||||
- **Framework preference** (if they have one): North Star + Metric Tree / AARRR / HEART / OKRs / Custom
|
||||
- **Primary goal this quarter** (e.g. grow activation, reduce churn, increase revenue)
|
||||
|
||||
If no framework preference is given, recommend the best fit based on stage and business model.
|
||||
|
||||
## Output Structure
|
||||
|
||||
### 1. Framework Recommendation (if not specified)
|
||||
|
||||
Explain in 2–3 sentences why you're recommending this framework for their context.
|
||||
|
||||
---
|
||||
|
||||
### 2. North Star Metric
|
||||
|
||||
**[Metric Name]:** [Definition — exactly what is measured and how]
|
||||
|
||||
**Why this is the right North Star for this business:**
|
||||
[2–3 sentences. It should reflect customer value delivered, not just revenue or activity. Explain what behaviour it captures and why maximising it correlates with long-term business health.]
|
||||
|
||||
**How to measure it:** [Formula or data source]
|
||||
**Current baseline:** [Leave as [ADD BASELINE] for user to fill]
|
||||
**Target:** [Leave as [ADD TARGET] for user to fill]
|
||||
|
||||
---
|
||||
|
||||
### 3. Metric Tree
|
||||
|
||||
Show how supporting metrics roll up to the North Star. Format as a hierarchy:
|
||||
|
||||
```
|
||||
[North Star Metric]
|
||||
├── [Driver 1: e.g. Acquisition]
|
||||
│ ├── [L2 metric: e.g. Organic signups / week]
|
||||
│ └── [L2 metric: e.g. Paid CAC by channel]
|
||||
├── [Driver 2: e.g. Activation]
|
||||
│ ├── [L2 metric: e.g. % users completing onboarding within 7 days]
|
||||
│ └── [L2 metric: e.g. Time to first value action]
|
||||
└── [Driver 3: e.g. Retention]
|
||||
├── [L2 metric: e.g. Day 30 retention rate]
|
||||
└── [L2 metric: e.g. Feature adoption depth]
|
||||
```
|
||||
|
||||
For each L2 metric, provide:
|
||||
- **Definition:** [What exactly is measured]
|
||||
- **Why it matters:** [How it connects to the North Star]
|
||||
- **Leading or lagging?** [Leading = predictive / Lagging = outcome]
|
||||
- **How to measure:** [Data source or calculation]
|
||||
|
||||
---
|
||||
|
||||
### 4. Counter-Metrics
|
||||
|
||||
[2–3 metrics to watch that prevent optimising the North Star in ways that damage the business. E.g. "If we optimise for signups, we need to watch spam account rate. If we optimise for engagement, we need to watch support ticket volume."]
|
||||
|
||||
---
|
||||
|
||||
### 5. Dashboard Recommendation
|
||||
|
||||
Suggest a 3-tier dashboard structure:
|
||||
- **Exec view (weekly):** [3–5 metrics — outcomes only]
|
||||
- **Team view (daily):** [7–10 metrics — leading indicators + outputs]
|
||||
- **Diagnostic view (on demand):** [Metrics to drill into when something looks wrong]
|
||||
|
||||
---
|
||||
|
||||
### 6. Metric Health Check Questions
|
||||
|
||||
[5 questions the team should ask in their weekly metrics review to turn numbers into insights. e.g. "Is our activation rate improving while retention stays flat? That suggests onboarding quality issue, not a product-market fit problem."]
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] North Star reflects customer value, not just business activity
|
||||
- [ ] Metric tree has 3–4 distinct drivers (not all one category)
|
||||
- [ ] Each L2 metric is classified as leading or lagging
|
||||
- [ ] Counter-metrics are included to prevent perverse incentives
|
||||
- [ ] Dashboard tiers are tailored to the product stage
|
||||
- [ ] All metric definitions are unambiguous (formula or clear description)
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Build a metrics framework for [product]"
|
||||
- "What should our North Star metric be?"
|
||||
- "Create a KPI tree for [business]"
|
||||
- "Give me an AARRR breakdown for [product]"
|
||||
- "What metrics should our [team type] team track?"
|
||||
@@ -0,0 +1,143 @@
|
||||
---
|
||||
name: sql-query-explainer
|
||||
description: "Explain, optimise, or translate SQL queries into plain language. Use when asked to explain a SQL query, optimise slow SQL, write a data dictionary, translate SQL to plain English for non-technical stakeholders, or review a query for correctness and performance. Works across PostgreSQL, MySQL, BigQuery, Snowflake, and standard SQL."
|
||||
---
|
||||
|
||||
# SQL Query Explainer Skill
|
||||
|
||||
This skill explains SQL queries in plain language, identifies optimisation opportunities, and helps communicate data logic to non-technical stakeholders. It also writes and documents new queries from natural language descriptions.
|
||||
|
||||
## Modes
|
||||
|
||||
Detect which mode the user needs based on their request:
|
||||
|
||||
1. **Explain** — Translate existing SQL into plain English
|
||||
2. **Optimise** — Review SQL for performance issues and suggest improvements
|
||||
3. **Write** — Generate SQL from a natural language description
|
||||
4. **Document** — Produce a data dictionary or query documentation
|
||||
|
||||
---
|
||||
|
||||
## Mode 1: Explain
|
||||
|
||||
When given a SQL query, produce:
|
||||
|
||||
### Plain English Summary
|
||||
[1–3 sentences. What does this query do? What data does it return? Write as if explaining to a business analyst, not a developer.]
|
||||
|
||||
### Step-by-Step Walkthrough
|
||||
|
||||
Break the query into logical sections. For each section:
|
||||
- Quote the SQL clause
|
||||
- Explain what it does in plain English
|
||||
- Flag any complexity (e.g. window functions, subqueries, CTEs)
|
||||
|
||||
### What the Result Looks Like
|
||||
|
||||
[Describe the shape of the output: "Returns one row per user, with columns for X, Y, Z. Ordered by [field] descending."]
|
||||
|
||||
### Potential Issues to Flag
|
||||
|
||||
- [Gotchas, edge cases, or implicit assumptions in this query]
|
||||
- [e.g. "This will include NULLs in the user_id column if the LEFT JOIN finds no match"]
|
||||
|
||||
---
|
||||
|
||||
## Mode 2: Optimise
|
||||
|
||||
When asked to optimise a query, produce:
|
||||
|
||||
### Performance Assessment
|
||||
|
||||
Rate overall: 🟢 Well-optimised / 🟡 Some improvements possible / 🔴 Significant issues
|
||||
|
||||
### Issues Found
|
||||
|
||||
For each issue:
|
||||
|
||||
**Issue [N]: [Short name, e.g. "Missing index on join column"]**
|
||||
- **What it is:** [Plain explanation]
|
||||
- **Why it matters:** [Performance impact — e.g. "Full table scan on a 10M row table"]
|
||||
- **Fix:**
|
||||
```sql
|
||||
-- Before
|
||||
[original snippet]
|
||||
|
||||
-- After
|
||||
[improved snippet]
|
||||
```
|
||||
- **Expected improvement:** [Estimate if possible]
|
||||
|
||||
### Optimisation Checklist
|
||||
|
||||
- [ ] SELECT * used? (Replace with specific columns)
|
||||
- [ ] Implicit type conversions on JOIN/WHERE columns?
|
||||
- [ ] Missing indexes on JOIN or WHERE columns?
|
||||
- [ ] N+1 patterns (queries inside loops)?
|
||||
- [ ] DISTINCT used where GROUP BY would be faster?
|
||||
- [ ] Window functions used where a subquery would be clearer/faster?
|
||||
- [ ] CTEs re-used or materialised unnecessarily?
|
||||
- [ ] Large IN() lists that could use a JOIN instead?
|
||||
|
||||
---
|
||||
|
||||
## Mode 3: Write
|
||||
|
||||
When given a natural language description, generate the SQL query and then explain it using Mode 1.
|
||||
|
||||
Ask the user to confirm:
|
||||
- **Database/dialect** (PostgreSQL / MySQL / BigQuery / Snowflake / SQLite / Standard SQL)
|
||||
- **Table and column names** (if known; otherwise use descriptive placeholder names like `users`, `orders`, `user_id`)
|
||||
- **Any filters, sorting, or aggregation requirements**
|
||||
|
||||
Produce:
|
||||
1. The SQL query with inline comments
|
||||
2. Plain English explanation (Mode 1 format)
|
||||
|
||||
---
|
||||
|
||||
## Mode 4: Document
|
||||
|
||||
When asked to create documentation for a query or table:
|
||||
|
||||
### Query Documentation
|
||||
|
||||
```
|
||||
Query: [Name]
|
||||
Purpose: [One sentence — what business question this answers]
|
||||
Author: [If provided]
|
||||
Last reviewed: [If provided]
|
||||
|
||||
Inputs:
|
||||
- Table: [table_name] — [what it contains]
|
||||
- Filter: [any WHERE conditions and their business meaning]
|
||||
|
||||
Output columns:
|
||||
| Column | Type | Description |
|
||||
|--------|------|-------------|
|
||||
| [name] | [type] | [plain English description] |
|
||||
|
||||
Assumptions:
|
||||
- [Any implicit assumptions the query makes]
|
||||
|
||||
Known limitations:
|
||||
- [Edge cases not handled, data quality dependencies, etc.]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Plain English explanation avoids SQL jargon
|
||||
- [ ] Optimisation suggestions include before/after SQL
|
||||
- [ ] Written queries include inline comments
|
||||
- [ ] Output shape is described (columns, row grain, ordering)
|
||||
- [ ] Dialect-specific syntax is flagged when non-standard
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Explain this SQL query: [paste query]"
|
||||
- "Optimise this slow query: [paste query]"
|
||||
- "Write a SQL query that [natural language description]"
|
||||
- "Document this query for my non-technical stakeholders"
|
||||
- "Why is this query returning unexpected results?"
|
||||
Vendored
BIN
Binary file not shown.
@@ -0,0 +1,13 @@
|
||||
{
|
||||
"$schema": "https://anthropic.com/claude-code/plugin.schema.json",
|
||||
"name": "pm-delivery",
|
||||
"version": "3.0.0",
|
||||
"description": "Sprint & delivery skills: Sprint Planning, Technical Spec Template, A/B Test Planner, Go-to-Market Planner, Product Launch Checklist, Sprint Brief, Retro Analysis.",
|
||||
"author": {
|
||||
"name": "Mohit Aggarwal",
|
||||
"email": "mohit15856@gmail.com"
|
||||
},
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills",
|
||||
"license": "MIT",
|
||||
"keywords": ["product-management", "sprint", "agile", "ab-testing", "go-to-market", "launch", "technical-spec"]
|
||||
}
|
||||
Vendored
BIN
Binary file not shown.
@@ -0,0 +1,113 @@
|
||||
---
|
||||
name: ab-test-planner
|
||||
description: "Design statistically rigorous A/B tests for product features, UI changes, onboarding flows, and pricing experiments. Use when asked to set up an experiment, design an A/B test, calculate sample size, or interpret test results. Produces a complete test plan with hypothesis, variant definitions, sample size, duration estimate, guardrail metrics, and a results interpretation guide."
|
||||
---
|
||||
|
||||
# A/B Test Planner Skill
|
||||
|
||||
Design experiments that produce trustworthy results — not just directional signals. Every test output includes hypothesis, success metrics, sample size, duration, and a results interpretation guide.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **What is being tested** (feature, UI change, copy, pricing, onboarding step)
|
||||
- **Hypothesis** (or ask to help formulate one)
|
||||
- **Primary metric** (conversion rate, click-through, completion rate, etc.)
|
||||
- **Baseline rate** and **minimum detectable effect** (MDE)
|
||||
- **Daily eligible users** (to calculate duration)
|
||||
|
||||
## Experiment Design Checklist
|
||||
|
||||
Before running any test, confirm:
|
||||
- [ ] Clear hypothesis with predicted direction
|
||||
- [ ] Single primary metric (plus up to 2 guardrail metrics)
|
||||
- [ ] Minimum detectable effect (MDE) defined
|
||||
- [ ] Sample size calculated
|
||||
- [ ] Test duration estimated
|
||||
- [ ] Segment isolated (no overlap with other running tests)
|
||||
- [ ] Rollback plan defined
|
||||
|
||||
## Hypothesis Template
|
||||
|
||||
> "We believe that [change] will cause [primary metric] to [increase/decrease] by [X%] for [user segment], because [rationale based on data or insight]."
|
||||
|
||||
Never run a test without a directional hypothesis. "Let's just see what happens" is not a hypothesis.
|
||||
|
||||
## Sample Size Calculator Logic
|
||||
|
||||
Use this formula (provide the output, not the formula, to the user):
|
||||
|
||||
- **Baseline conversion rate:** Current rate of primary metric
|
||||
- **MDE:** Smallest change worth detecting (recommend 10–20% relative lift for most features)
|
||||
- **Statistical power:** 80% (standard)
|
||||
- **Significance level:** 95% (p < 0.05)
|
||||
|
||||
For common scenarios, provide pre-calculated estimates:
|
||||
|
||||
| Baseline Rate | MDE (Relative) | Required Sample per Variant |
|
||||
|---|---|---|
|
||||
| 5% | 20% | ~19,000 |
|
||||
| 10% | 15% | ~14,000 |
|
||||
| 20% | 10% | ~15,000 |
|
||||
| 40% | 10% | ~9,500 |
|
||||
| 60% | 5% | ~42,000 |
|
||||
|
||||
Always warn: "These are estimates. Use a tool like Evan Miller's calculator or Statsig for precision."
|
||||
|
||||
## Test Duration Guidance
|
||||
|
||||
Minimum: 2 full weeks (to capture weekly seasonality)
|
||||
Maximum: 4 weeks (novelty effect distorts results beyond this)
|
||||
|
||||
`Duration = Required sample ÷ (Daily traffic × % exposed)`
|
||||
|
||||
Flag if traffic is too low to reach significance in under 8 weeks — recommend a different approach (e.g., holdout test, qualitative research).
|
||||
|
||||
## Output Format
|
||||
|
||||
### A/B Test Plan — [Test Name] — [Date]
|
||||
|
||||
**Hypothesis:**
|
||||
> [Filled hypothesis template]
|
||||
|
||||
**Variants:**
|
||||
- Control (A): [Current experience]
|
||||
- Treatment (B): [Changed experience — be specific]
|
||||
|
||||
**Primary Metric:** [Metric name + how measured]
|
||||
**Guardrail Metrics:** [Metrics that must not degrade]
|
||||
|
||||
**Target Segment:** [Who sees the test — % of traffic, user type]
|
||||
**Traffic Split:** [50/50 recommended unless ramp-up needed]
|
||||
|
||||
**Sample Size Required:** ~[N] users per variant
|
||||
**Estimated Duration:** [X] weeks (based on [Y] daily eligible users)
|
||||
**Significance Threshold:** 95% confidence, 80% power
|
||||
|
||||
**Exclusions:** [Any user segments to exclude and why]
|
||||
|
||||
**Rollback Trigger:** If [guardrail metric] degrades by [X%], stop the test immediately.
|
||||
|
||||
**Results Interpretation Guide:**
|
||||
- ✅ Ship if: Treatment shows [X%]+ lift on primary metric at 95% confidence AND guardrail metrics are stable
|
||||
- 🔄 Iterate if: Direction is positive but not significant — consider extending or redesigning
|
||||
- ❌ Reject if: No lift or negative direction at significance
|
||||
- ⚠️ Inconclusive: Do not ship. Do not call it a win.
|
||||
|
||||
---
|
||||
|
||||
## Guidelines
|
||||
|
||||
- Always recommend against peeking at results before the test reaches planned sample size — explain p-hacking risk
|
||||
- If user wants to test multiple variants, explain the multiple comparisons problem and recommend a Bonferroni correction or a Bayesian approach
|
||||
- If traffic is very low (<1,000 users/day), recommend qualitative alternatives: moderated testing, 5-second tests, or user interviews
|
||||
- Never approve a test with no guardrail metrics — always protect revenue, retention, or core engagement
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Hypothesis is directional (predicts a specific direction and magnitude, not "let's see")
|
||||
- [ ] Primary metric is singular (guardrail metrics are secondary)
|
||||
- [ ] Sample size is calculated from actual MDE and baseline (not guessed)
|
||||
- [ ] Test duration accounts for weekly seasonality (minimum 2 weeks)
|
||||
- [ ] Guardrail metrics are defined (at least one to protect revenue or core engagement)
|
||||
- [ ] Rollback trigger is specified with a concrete threshold
|
||||
@@ -0,0 +1,133 @@
|
||||
---
|
||||
name: go-to-market-planner
|
||||
description: "Build a go-to-market plan for any product launch, feature release, or new market entry. Use when planning a product launch, writing a GTM strategy, defining launch tiers, or coordinating cross-functional launch activities. Produces a tiered GTM plan with messaging, cross-functional activity tracker, success metrics, and launch day checklist."
|
||||
---
|
||||
|
||||
# Go-to-Market Planner Skill
|
||||
|
||||
Produce a complete, cross-functional GTM plan that aligns product, marketing, sales, and support around a single launch — with clear owners, timelines, and success metrics.
|
||||
|
||||
## Launch Tier Framework
|
||||
|
||||
Before planning, classify the launch:
|
||||
|
||||
| Tier | Scope | Typical Effort | Examples |
|
||||
|---|---|---|---|
|
||||
| **Tier 1 — Major Launch** | New product / significant platform change | 8–12 weeks | New pricing model, platform rebrand, new product line |
|
||||
| **Tier 2 — Feature Launch** | Significant new capability | 4–6 weeks | Major feature, API release, new integration |
|
||||
| **Tier 3 — Incremental Release** | Improvement, bug fix, minor feature | 1–2 weeks | UI tweak, performance improvement, small enhancement |
|
||||
|
||||
Always confirm tier with the user before proceeding.
|
||||
|
||||
---
|
||||
|
||||
## GTM Plan Output Format
|
||||
|
||||
### GTM Plan — [Product/Feature Name] — [Launch Date]
|
||||
|
||||
**Launch Tier:** [1 / 2 / 3]
|
||||
**Launch Owner (PM):** [Name]
|
||||
**Target Launch Date:** [Date]
|
||||
**Soft Launch Date (Beta/Limited):** [Date, if applicable]
|
||||
|
||||
---
|
||||
|
||||
### 1. What We're Launching
|
||||
**One-line description:** [What it is, for whom, and why now]
|
||||
**Key customer problem solved:** [Specific pain point]
|
||||
**Key differentiator:** [Why ours, why now]
|
||||
|
||||
---
|
||||
|
||||
### 2. Target Audience
|
||||
**Primary segment:** [Who benefits most — be specific]
|
||||
**Secondary segment:** [Who else benefits]
|
||||
**Not for:** [Who this is NOT for — helps sales and support]
|
||||
|
||||
---
|
||||
|
||||
### 3. Messaging
|
||||
|
||||
**Headline:** [Customer-facing headline — lead with outcome, not feature]
|
||||
**Sub-headline:** [Supporting context — how it works or why it matters]
|
||||
**3 key messages:**
|
||||
1. [Problem solved]
|
||||
2. [How it works / what's new]
|
||||
3. [Proof / social proof / data]
|
||||
|
||||
**Elevator pitch (30 seconds):**
|
||||
> [For [target user] who [has this problem], [product/feature] is a [category] that [key benefit]. Unlike [alternative], we [differentiator].]
|
||||
|
||||
---
|
||||
|
||||
### 4. Launch Activities by Function
|
||||
|
||||
| Function | Activity | Owner | Due Date | Status |
|
||||
|---|---|---|---|---|
|
||||
| Product | Feature flagging / rollout plan | PM | [date] | |
|
||||
| Marketing | Blog post / landing page | Marketing | [date] | |
|
||||
| Marketing | Email campaign to existing users | Marketing | [date] | |
|
||||
| Marketing | Social media content | Marketing | [date] | |
|
||||
| Sales | Sales enablement deck | PM + Sales | [date] | |
|
||||
| Sales | FAQ for sales team | PM | [date] | |
|
||||
| Support | Help centre articles | Support | [date] | |
|
||||
| Support | Support team training | Support | [date] | |
|
||||
| Engineering | Monitoring/alerting in place | Eng | [date] | |
|
||||
|
||||
---
|
||||
|
||||
### 5. Success Metrics
|
||||
|
||||
| Metric | Baseline | Target | Measurement Window |
|
||||
|---|---|---|---|
|
||||
| [Adoption metric] | [X] | [Y] | 30 days post-launch |
|
||||
| [Engagement metric] | [X] | [Y] | 60 days post-launch |
|
||||
| [Business metric] | [X] | [Y] | 90 days post-launch |
|
||||
|
||||
---
|
||||
|
||||
### 6. Risks & Contingencies
|
||||
|
||||
| Risk | Likelihood | Impact | Mitigation |
|
||||
|---|---|---|---|
|
||||
| [Risk] | H/M/L | H/M/L | [Action if it happens] |
|
||||
|
||||
---
|
||||
|
||||
### 7. Launch Day Checklist
|
||||
- [ ] Feature live for [X%] of users
|
||||
- [ ] Monitoring dashboard active
|
||||
- [ ] Support team briefed
|
||||
- [ ] Blog post published
|
||||
- [ ] Email sent / scheduled
|
||||
- [ ] Sales team notified
|
||||
- [ ] Executive announcement sent (if Tier 1)
|
||||
- [ ] Rollback procedure confirmed
|
||||
|
||||
---
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Product or feature name**
|
||||
- **Target launch date**
|
||||
- **Launch tier** (Tier 1 / 2 / 3 — or describe scope and the skill will classify)
|
||||
- **Target audience** (who benefits and who it's NOT for)
|
||||
- **Key message** (what's the headline outcome for the customer)
|
||||
- **PM and launch owner**
|
||||
|
||||
## Guidelines
|
||||
|
||||
- Never plan a Tier 1 launch without at least 8 weeks of lead time
|
||||
- Always include a "Not for" section — it prevents misdirected sales and support tickets
|
||||
- Recommend a soft launch to 5–10% of users before full rollout for any Tier 1 or 2 launch
|
||||
- Post-launch retrospective should be scheduled at launch planning time — don't leave it to chance
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Launch tier is confirmed and appropriate for scope
|
||||
- [ ] "Not for" section is included to prevent misdirected sales and support
|
||||
- [ ] Every function has at least one activity with a named owner and due date
|
||||
- [ ] Success metrics include a measurement window (30/60/90 days)
|
||||
- [ ] Rollback procedure is confirmed for Tier 1 and 2 launches
|
||||
- [ ] Post-launch retrospective is scheduled
|
||||
@@ -0,0 +1,93 @@
|
||||
---
|
||||
name: pptx-slide-auditor
|
||||
description: "Audit a PowerPoint presentation for layout issues, text overflow, visual hierarchy problems, and consistency gaps. Use when asked to review a slide deck, check a presentation before a meeting, audit slides for layout problems, or QA a deck before sharing. Produces a slide-by-slide report with issues ranked by severity and specific fixes. Best used with Claude Opus 4.7 or newer for reliable slide-level vision analysis."
|
||||
---
|
||||
|
||||
# PPTX Slide Auditor Skill
|
||||
|
||||
Runs a systematic visual and structural audit of a PowerPoint presentation — identifying layout issues, text overflow, inconsistent styling, weak visual hierarchy, and slides that will cause problems in a presentation setting. Built to leverage Opus 4.7 vision improvements for pixel-level layout analysis.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **The deck** (upload the .pptx file or individual slide screenshots)
|
||||
- **Audience** (internal team / executive / external client / conference / investor)
|
||||
- **Presentation mode** (presented live / sent to read / shared async on video)
|
||||
- **Areas of concern** (optional — e.g. "I think slide 12 is overcrowded")
|
||||
|
||||
## Output Structure
|
||||
|
||||
### 1. Deck Overview
|
||||
| Metric | Result |
|
||||
|---|---|
|
||||
| Total slides | N |
|
||||
| Overall status | Ready / Minor fixes needed / Major revisions required |
|
||||
| Readability score | /10 |
|
||||
| Visual consistency score | /10 |
|
||||
| Most common issue | [Pattern observed across multiple slides] |
|
||||
|
||||
### 2. Slide-by-Slide Audit
|
||||
|
||||
For each slide with issues:
|
||||
|
||||
**Slide N: [Slide title]**
|
||||
- Status: Ready / Fix before sending / Major revision
|
||||
- Issues found:
|
||||
- [Specific issue with exact location — e.g. "Body text extends beyond the text frame on the right side"]
|
||||
- [Issue 2]
|
||||
- Suggested fix: [Specific action — move element, reduce text, resize]
|
||||
|
||||
Slides with no issues: just list the slide numbers. Do not write anything else about them.
|
||||
|
||||
### 3. Pattern Issues Across the Deck
|
||||
|
||||
Issues that repeat across multiple slides:
|
||||
|
||||
**[Pattern title — e.g. "Inconsistent body text size"]**
|
||||
- Slides affected: [list]
|
||||
- Root cause: [master slide issue / manual overrides / mixed templates]
|
||||
- Fix: [Single action to resolve across all affected slides]
|
||||
|
||||
### 4. Visual Hierarchy Check
|
||||
|
||||
| Dimension | Status | Notes |
|
||||
|---|---|---|
|
||||
| Title consistency (size, font, colour) | Pass / Fail | |
|
||||
| Body text readability at presentation distance | Pass / Fail | |
|
||||
| Image placement alignment | Pass / Fail | |
|
||||
| Whitespace and breathing room | Pass / Fail | |
|
||||
| Data visualisation clarity | Pass / Fail / N/A | |
|
||||
|
||||
### 5. Audience-Specific Flags
|
||||
|
||||
Based on the stated audience:
|
||||
|
||||
- **Executive audience:** flag slides with too much text, complex tables, or unclear bottom-line messages
|
||||
- **External client:** flag slides with internal jargon, unfinished placeholder text, or confidentiality concerns
|
||||
- **Live presentation:** flag slides that will be hard to read from the back of a room
|
||||
- **Async/video:** flag slides that assume a presenter voiceover
|
||||
|
||||
### 6. Prioritised Fix List
|
||||
|
||||
| # | Fix | Slide | Effort | Impact |
|
||||
|---|---|---|---|---|
|
||||
| 1 | [Specific fix] | Slide N | Low/Med/High | High |
|
||||
|
||||
Order by: fixes before handoff (critical) > consistency fixes (high) > polish (medium).
|
||||
|
||||
## Quality Checks
|
||||
- [ ] Every issue references a specific slide number and location on the slide
|
||||
- [ ] Pattern issues are identified separately from slide-specific issues
|
||||
- [ ] Fix list is ordered by impact, not by slide order
|
||||
- [ ] Audience-appropriate concerns flagged explicitly
|
||||
- [ ] Slides without issues are listed briefly, not ignored
|
||||
|
||||
## Example Trigger Phrases
|
||||
- "Audit this slide deck before my board meeting"
|
||||
- "Review this PowerPoint for layout issues"
|
||||
- "Check this presentation for consistency problems"
|
||||
- "QA my deck before I send it to the client"
|
||||
- "What is wrong with slide 7 in this deck?"
|
||||
|
||||
## Why This Works Better on Opus 4.7
|
||||
Earlier models struggled with precise spatial analysis of slide layouts — they would hallucinate issues or miss obvious overflow problems. Opus 4.7 vision improvements mean coordinates map 1:1 to pixels, making slide-level issue detection reliable without manual screenshot annotation.
|
||||
@@ -0,0 +1,125 @@
|
||||
---
|
||||
name: product-launch-checklist
|
||||
description: "Generate a comprehensive pre-launch, launch day, and post-launch checklist for any product release. Use when preparing for a product launch, feature release, or major update. Produces a role-assigned, tiered checklist covering engineering readiness, marketing and comms, support, and post-launch monitoring."
|
||||
---
|
||||
|
||||
# Product Launch Checklist Skill
|
||||
|
||||
Never launch without checking everything. Generate a complete, role-assigned checklist covering pre-launch readiness, launch day execution, and post-launch monitoring.
|
||||
|
||||
## How to Use This Skill
|
||||
|
||||
Provide:
|
||||
- Launch name and date
|
||||
- Launch tier (1 = major, 2 = feature, 3 = incremental)
|
||||
- Team members and their roles
|
||||
|
||||
The skill generates a tiered checklist. Tier 3 launches use only the Essentials section. Tier 2 adds Marketing & Comms. Tier 1 uses all sections.
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
### Launch Checklist — [Feature/Product Name] — Target Date: [Date]
|
||||
|
||||
**Launch Tier:** [1 / 2 / 3]
|
||||
**Launch Owner:** [PM Name]
|
||||
**Engineering Lead:** [Name]
|
||||
**Go/No-Go Decision By:** [Date and time — typically 24 hours before launch]
|
||||
|
||||
---
|
||||
|
||||
### 🔧 PRE-LAUNCH — Engineering & Product (T-2 weeks)
|
||||
- [ ] Feature flag created and tested in staging
|
||||
- [ ] All acceptance criteria signed off by PM
|
||||
- [ ] Code reviewed and merged to main
|
||||
- [ ] QA sign-off completed (regression + new feature)
|
||||
- [ ] Performance testing completed (load, latency)
|
||||
- [ ] Security review completed (if data or auth changes)
|
||||
- [ ] Rollback procedure documented and tested
|
||||
- [ ] Monitoring and alerting configured
|
||||
- [ ] Error logging in place with correct severity levels
|
||||
- [ ] Database migrations tested on staging with production data volume
|
||||
|
||||
### 📢 PRE-LAUNCH — Marketing & Comms (T-1 week)
|
||||
- [ ] Blog post written, reviewed, and scheduled
|
||||
- [ ] In-app announcement or tooltip configured
|
||||
- [ ] Email campaign drafted and QA'd
|
||||
- [ ] Social media posts drafted and scheduled
|
||||
- [ ] Landing page or feature page live in staging
|
||||
- [ ] Press outreach sent (Tier 1 only)
|
||||
- [ ] Product Hunt / community posts prepared (Tier 1 only)
|
||||
|
||||
### 🎓 PRE-LAUNCH — Sales & Support (T-1 week)
|
||||
- [ ] Sales enablement one-pager completed
|
||||
- [ ] FAQ document shared with sales and support teams
|
||||
- [ ] Help centre articles written and published
|
||||
- [ ] Support team demo / training completed
|
||||
- [ ] Customer success team briefed on top accounts
|
||||
- [ ] Pricing updated (if applicable)
|
||||
- [ ] Contracts / ToS updated (if applicable)
|
||||
|
||||
### 📊 PRE-LAUNCH — Analytics (T-1 week)
|
||||
- [ ] Analytics events firing correctly in staging
|
||||
- [ ] Dashboard configured for launch metrics
|
||||
- [ ] Baseline metrics documented
|
||||
- [ ] Success criteria documented and shared with team
|
||||
- [ ] A/B test configured (if applicable)
|
||||
|
||||
---
|
||||
|
||||
### ✅ GO / NO-GO DECISION — T-24 hours
|
||||
|
||||
| Criteria | Status | Owner |
|
||||
|---|---|---|
|
||||
| All critical bugs resolved | 🟢 / 🔴 | Eng Lead |
|
||||
| QA sign-off complete | 🟢 / 🔴 | QA |
|
||||
| Rollback tested | 🟢 / 🔴 | Eng Lead |
|
||||
| Help centre articles live | 🟢 / 🔴 | Support |
|
||||
| Monitoring active | 🟢 / 🔴 | Eng Lead |
|
||||
| PM sign-off | 🟢 / 🔴 | PM |
|
||||
|
||||
**Go / No-Go Decision:** [GO / NO-GO]
|
||||
**Decision Owner:** [PM + Eng Lead jointly]
|
||||
|
||||
---
|
||||
|
||||
### 🚀 LAUNCH DAY
|
||||
- [ ] Feature flag enabled for [X%] of users (start low — 5–10%)
|
||||
- [ ] Launch confirmed in team Slack/channel
|
||||
- [ ] Metrics dashboard open and being monitored
|
||||
- [ ] Error rate checked at T+15 min, T+1 hr, T+4 hr
|
||||
- [ ] Blog post published / email sent
|
||||
- [ ] Social posts live
|
||||
- [ ] Support team on standby for first 4 hours
|
||||
- [ ] PM available and reachable all day
|
||||
- [ ] Feature flag expanded to 50% if T+2hr checks pass
|
||||
- [ ] Feature flag expanded to 100% if T+4hr checks pass
|
||||
|
||||
---
|
||||
|
||||
### 📈 POST-LAUNCH (D+7, D+30)
|
||||
- [ ] D+7 metrics review: adoption, errors, support tickets
|
||||
- [ ] D+7 customer feedback synthesised
|
||||
- [ ] Retrospective scheduled
|
||||
- [ ] Learnings documented
|
||||
- [ ] D+30 success metrics reviewed against targets
|
||||
- [ ] Feature flag removed from codebase (clean up)
|
||||
- [ ] Follow-up features added to backlog based on feedback
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Launch tier confirmed before generating checklist (scope determines depth)
|
||||
- [ ] Go/No-Go decision has a named owner and a specific decision time
|
||||
- [ ] Rollback procedure is documented and tested (not just planned)
|
||||
- [ ] Feature flag expansion is staged (5% → 50% → 100%), not all-at-once
|
||||
- [ ] Post-launch retrospective is scheduled at launch time
|
||||
|
||||
## Guidelines
|
||||
|
||||
- The Go/No-Go decision must have a named owner — "the team" is not an owner
|
||||
- Never launch on a Friday unless you have weekend engineering coverage
|
||||
- Recommend starting all launches at <10% traffic — even for simple features
|
||||
- Document rollback time: "We can revert this in X minutes" should be known before launch
|
||||
@@ -0,0 +1,53 @@
|
||||
---
|
||||
name: retro-analysis
|
||||
description: "Analyse sprint delivery data and produce a structured retrospective brief. Use when asked to run a retrospective, analyse sprint data, prepare a retro brief, or turn sprint metrics into discussion prompts. Produces a data-grounded retrospective brief with completion stats, pattern analysis, Start/Stop/Continue prompts, and one concrete experiment for next sprint."
|
||||
---
|
||||
|
||||
# Retrospective Analysis Skill
|
||||
|
||||
Generate a data-grounded retrospective brief that separates facts from feelings, so the team spends retro time on solutions rather than debating what happened.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Sprint tickets: planned vs. completed**
|
||||
- **Carry-over tickets and reasons** (if known)
|
||||
- **Tickets reopened after closing** (quality signal)
|
||||
- **Any incidents or unplanned work** (scope creep signal)
|
||||
- **Sprint velocity vs. historical average** (trend context)
|
||||
|
||||
## Process
|
||||
1. Calculate: completion rate, carry-over rate, unplanned work percentage
|
||||
2. Identify patterns: which ticket types were most likely to carry over? Which caused blockers?
|
||||
3. Note any process or communication breakdowns visible in the data
|
||||
4. Prepare 3 "Start / Stop / Continue" prompts based on the data — not generic, specific to this sprint
|
||||
5. Suggest 1 concrete experiment for the next sprint based on the biggest friction point
|
||||
6. **Validate** — Confirm each prompt is specific to this sprint (not a recycled generic prompt), and that the recommended experiment is concrete and measurable
|
||||
|
||||
## Output Structure
|
||||
|
||||
### Sprint [Number] Retrospective Brief
|
||||
|
||||
**By the Numbers:**
|
||||
- Planned: [n] tickets | Completed: [n] | Carry-over: [n] | Completion rate: [%]
|
||||
- Unplanned work: [n] tickets ([%] of capacity)
|
||||
- Velocity: [points] vs. [average] average
|
||||
|
||||
**What the Data Suggests:**
|
||||
[2-3 observations grounded in the numbers above]
|
||||
|
||||
**Discussion Prompts:**
|
||||
- Start: [specific prompt based on this sprint's data]
|
||||
- Stop: [specific prompt based on this sprint's data]
|
||||
- Continue: [specific prompt based on this sprint's data]
|
||||
|
||||
**Suggested Experiment for Next Sprint:**
|
||||
[One concrete, testable process change — with a specific success metric]
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Each Start/Stop/Continue prompt names a specific behaviour, not a vague category
|
||||
- [ ] The recommended experiment is testable in one sprint
|
||||
- [ ] Carry-over analysis identifies the ticket type or cause, not just the count
|
||||
- [ ] Data observations don't assign blame — they describe patterns
|
||||
- [ ] Velocity trend is mentioned in context (is this a one-off or a pattern?)
|
||||
@@ -0,0 +1,53 @@
|
||||
---
|
||||
name: sprint-brief
|
||||
description: "Generate a structured sprint brief from sprint data and goals. Use when asked to write a sprint brief, create a sprint summary, document sprint goals and scope, or produce a team-facing sprint overview. Produces a scannable brief with sprint goal, rationale, grouped work, critical path, risks, and definition of done."
|
||||
---
|
||||
|
||||
# Sprint Brief Skill
|
||||
|
||||
Produce a clear, scannable sprint brief that every team member — engineer, designer, PM — can read in under three minutes and understand exactly what we're doing and why.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Sprint name and number**
|
||||
- **Sprint goal** (1-2 sentences — flag if too vague)
|
||||
- **Ticket list with owners** (or a description of the work)
|
||||
- **Known dependencies or blockers**
|
||||
- **Carry-over items from previous sprint** (if any)
|
||||
|
||||
## Process
|
||||
1. Read sprint goal and check it's specific and measurable — flag if it's too vague
|
||||
2. Group tickets by theme or feature area
|
||||
3. Identify the critical path — which tickets must complete for the sprint goal to be met?
|
||||
4. Flag risks: tickets with unclear acceptance criteria, missing designs, unresolved dependencies
|
||||
5. Note carry-over items and whether they affect this sprint's goal
|
||||
6. **Validate** — Confirm the sprint goal is achievable given the ticket scope and capacity. If the critical path items alone would fill the sprint, flag it as overloaded.
|
||||
|
||||
## Output Structure
|
||||
|
||||
### Sprint [Number] Brief — [Dates]
|
||||
**Sprint Goal:** [1-2 sentences — specific and measurable]
|
||||
**Why This Sprint Matters:** [Connect to quarterly OKR in 2-3 sentences]
|
||||
|
||||
**What We're Building:**
|
||||
- [Theme 1]: [tickets and owners]
|
||||
- [Theme 2]: [tickets and owners]
|
||||
|
||||
**Critical Path:** [The 2-3 tickets everything else depends on]
|
||||
|
||||
**Risks to Flag:**
|
||||
- [Risk 1 + mitigation]
|
||||
- [Risk 2 + mitigation]
|
||||
|
||||
**Carry-over from Last Sprint:** [List + impact on current goal]
|
||||
|
||||
**Definition of Done:** [Specific, agreed criteria for sprint success]
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Sprint goal is specific enough to score pass/fail at the end of the sprint
|
||||
- [ ] Critical path items are named — not just "the important ones"
|
||||
- [ ] Every risk has a mitigation or owner (not just "this is a risk")
|
||||
- [ ] Carry-over items are connected to their impact on this sprint's goal
|
||||
- [ ] Definition of Done is agreed criteria, not a task list
|
||||
@@ -0,0 +1,97 @@
|
||||
---
|
||||
name: sprint-planning
|
||||
description: "Structure and facilitate sprint planning sessions. Use when asked to plan a sprint, organise backlog items, assign story points, create sprint goals, or prepare sprint planning agendas. Produces a sprint goal, velocity-calibrated backlog, capacity plan, risk flags, and a structured sprint planning meeting agenda."
|
||||
---
|
||||
|
||||
# Sprint Planning Skill
|
||||
|
||||
Transform raw backlog items into a structured, achievable sprint with clear goals, velocity-calibrated scope, and team-ready output.
|
||||
|
||||
## What This Skill Produces
|
||||
|
||||
- **Sprint Goal** — single, outcome-focused sentence the whole team can rally around
|
||||
- **Sprint Backlog** — prioritised list of user stories with story point estimates and acceptance criteria
|
||||
- **Capacity Plan** — team availability breakdown accounting for holidays, meetings, and focus time
|
||||
- **Sprint Planning Agenda** — structured 2-hour meeting agenda with timings
|
||||
- **Risk Flags** — blockers or dependencies that could derail the sprint
|
||||
|
||||
## Inputs to Request From User
|
||||
|
||||
Ask for (if not already provided):
|
||||
- Sprint duration (1 or 2 weeks)
|
||||
- Team size and velocity (average story points per sprint)
|
||||
- Top 3–5 backlog items or epics to pull from
|
||||
- Any known absences, holidays, or team events
|
||||
- Previous sprint's incomplete items (carry-overs)
|
||||
|
||||
## Sprint Goal Formula
|
||||
|
||||
Use this structure:
|
||||
> "This sprint we will [deliver X outcome] so that [user/business benefit], measured by [success indicator]."
|
||||
|
||||
Never write sprint goals as task lists. Always outcome-first.
|
||||
|
||||
## Story Point Calibration
|
||||
|
||||
| Complexity | Points | Description |
|
||||
|---|---|---|
|
||||
| Trivial | 1 | Clearly understood, no unknowns |
|
||||
| Small | 2 | Straightforward, minor effort |
|
||||
| Medium | 3 | Some complexity, clear path |
|
||||
| Large | 5 | Complex, needs design or research |
|
||||
| Very Large | 8 | High uncertainty, may need splitting |
|
||||
| Epic | 13+ | Too large — must be split before sprint |
|
||||
|
||||
Flag any item estimated at 8+ and recommend splitting.
|
||||
|
||||
## Capacity Formula
|
||||
|
||||
```
|
||||
Available capacity = (Team size × Sprint days × Focus hours/day) × Availability factor
|
||||
Focus hours/day: 6 (accounting for meetings, Slack, admin)
|
||||
Availability factor: 0.7–0.85 depending on holidays/events
|
||||
Story points to commit = Historical velocity × Availability factor
|
||||
```
|
||||
|
||||
## Output Format
|
||||
|
||||
### Sprint [N] — [Start Date] to [End Date]
|
||||
|
||||
**Sprint Goal:**
|
||||
> [Goal statement]
|
||||
|
||||
**Team Capacity:** [X] story points available (based on [Y] team members, [Z]% availability)
|
||||
|
||||
**Sprint Backlog:**
|
||||
|
||||
| Priority | Story | Points | Owner | Acceptance Criteria |
|
||||
|---|---|---|---|---|
|
||||
| 1 | [Story title] | [N] | [Team member] | [When X then Y] |
|
||||
|
||||
**Carry-Overs from Previous Sprint:**
|
||||
- [Item] — Reason for carry-over: [brief explanation]
|
||||
|
||||
**Risks & Dependencies:**
|
||||
- [Risk description] → Mitigation: [action]
|
||||
|
||||
**Sprint Planning Agenda:**
|
||||
- 00:00–00:10 — Review sprint goal and team capacity
|
||||
- 00:10–00:40 — Walk through backlog items, confirm estimates
|
||||
- 00:40–01:20 — Assign stories, identify dependencies
|
||||
- 01:20–01:50 — Review acceptance criteria per story
|
||||
- 01:50–02:00 — Confirm sprint commitment and close
|
||||
|
||||
## Guidelines
|
||||
|
||||
- Always challenge stories missing acceptance criteria — flag them explicitly
|
||||
- Recommend the team commits to 80% of available capacity, not 100%
|
||||
- If no velocity data is provided, assume 20–30 points for a 5-person team as a starting point
|
||||
- Highlight any story with unclear ownership as a blocker
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Sprint goal is outcome-focused (not "implement X" — something like "users can do Y")
|
||||
- [ ] Team capacity is calculated using actual availability, not theoretical 100%
|
||||
- [ ] Every story has an acceptance criterion (flag any that don't)
|
||||
- [ ] Stories estimated at 8+ points are flagged for splitting
|
||||
- [ ] Carry-overs from last sprint are accounted for in capacity
|
||||
@@ -0,0 +1,149 @@
|
||||
---
|
||||
name: technical-spec-template
|
||||
description: "Create structured technical specification documents that bridge product requirements and engineering implementation. Use when writing a tech spec, engineering spec, system design doc, or API specification. Produces a complete spec with problem statement, proposed solution, data model, API design, alternatives considered, security considerations, testing plan, and rollout strategy."
|
||||
---
|
||||
|
||||
# Technical Spec Template Skill
|
||||
|
||||
Write technical specifications that engineers actually read — clear problem framing, unambiguous requirements, explicit decisions, and documented trade-offs.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Feature or system description** (what needs to be specced)
|
||||
- **Related PRD or product brief** (if available)
|
||||
- **Engineering reviewers** (whose sign-off is needed)
|
||||
- **Known constraints** (technical limitations, security requirements, performance targets)
|
||||
|
||||
## When to Write a Tech Spec
|
||||
|
||||
Write a tech spec when:
|
||||
- The feature requires changes to 2+ systems
|
||||
- There are significant architectural decisions to make
|
||||
- More than one engineer will work on the implementation
|
||||
- The feature has security, privacy, or compliance implications
|
||||
- Estimated effort is >5 story points
|
||||
|
||||
Skip the spec for trivial bug fixes or 1-2 hour changes.
|
||||
|
||||
---
|
||||
|
||||
## Technical Spec Output Format
|
||||
|
||||
### Technical Specification — [Feature Name]
|
||||
|
||||
**Author:** [Name]
|
||||
**Status:** Draft | In Review | Approved | Implemented
|
||||
**Created:** [Date] | **Last Updated:** [Date]
|
||||
**Reviewers:** [Eng Lead, Architect, PM, Security if needed]
|
||||
**Related PRD:** [Link] | **Jira Epic:** [Link]
|
||||
|
||||
---
|
||||
|
||||
#### 1. Problem Statement
|
||||
> [2–3 sentences. What problem are we solving and why now? No solution language here.]
|
||||
|
||||
#### 2. Goals & Non-Goals
|
||||
|
||||
**Goals (in scope):**
|
||||
- [Specific, measurable outcome]
|
||||
- [Specific, measurable outcome]
|
||||
|
||||
**Non-Goals (explicitly out of scope):**
|
||||
- [What this spec does NOT cover]
|
||||
- [Common assumption to shut down early]
|
||||
|
||||
#### 3. Background & Context
|
||||
[Any prior art, related systems, or context engineers need to understand the decision space. Link to previous specs, ADRs, or research.]
|
||||
|
||||
#### 4. Proposed Solution
|
||||
|
||||
**High-Level Approach:**
|
||||
[2–4 sentences describing the chosen solution. Why this approach vs alternatives?]
|
||||
|
||||
**System Architecture Diagram:**
|
||||
[Describe or embed: which services are involved, how data flows, what APIs are called]
|
||||
|
||||
**Data Model Changes:**
|
||||
```sql
|
||||
-- New tables or schema changes
|
||||
[Include DDL or schema definition]
|
||||
```
|
||||
|
||||
**API Design:**
|
||||
```
|
||||
[Endpoint] [Method]
|
||||
Request: { [fields and types] }
|
||||
Response: { [fields and types] }
|
||||
Error codes: [list]
|
||||
```
|
||||
|
||||
**Key Implementation Details:**
|
||||
- [Important technical constraint or approach]
|
||||
- [Edge case handling]
|
||||
- [Third-party dependency and version]
|
||||
|
||||
#### 5. Alternative Approaches Considered
|
||||
|
||||
| Option | Pros | Cons | Why Rejected |
|
||||
|---|---|---|---|
|
||||
| [Alt 1] | [Benefits] | [Drawbacks] | [Reason not chosen] |
|
||||
| [Alt 2] | [Benefits] | [Drawbacks] | [Reason not chosen] |
|
||||
|
||||
#### 6. Security & Privacy Considerations
|
||||
- Data stored: [What PII or sensitive data is involved]
|
||||
- Authentication: [How is access controlled]
|
||||
- Authorisation: [What permissions are required]
|
||||
- Encryption: [At rest / in transit requirements]
|
||||
- Compliance implications: [GDPR, SOC2, etc. if relevant]
|
||||
|
||||
#### 7. Performance & Scalability
|
||||
- Expected load: [Requests/second, data volume]
|
||||
- Latency requirements: [P50 / P95 targets]
|
||||
- Caching strategy: [If applicable]
|
||||
- Database indexing: [New indexes required]
|
||||
- Known bottlenecks: [Where to watch]
|
||||
|
||||
#### 8. Testing Plan
|
||||
- Unit tests: [Key scenarios to cover]
|
||||
- Integration tests: [System boundaries to test]
|
||||
- Load tests: [If performance-critical]
|
||||
- Edge cases: [Known tricky scenarios]
|
||||
- Rollback plan: [How to revert if something goes wrong]
|
||||
|
||||
#### 9. Rollout Plan
|
||||
- Feature flag: [Yes / No — name of flag]
|
||||
- Rollout stages: [% of users at each stage]
|
||||
- Monitoring: [Metrics and alerts to set up]
|
||||
- Success criteria to progress rollout: [What needs to be true]
|
||||
- Rollback trigger: [What would cause immediate rollback]
|
||||
|
||||
#### 10. Open Questions
|
||||
| Question | Owner | Due Date | Resolution |
|
||||
|---|---|---|---|
|
||||
| [Unresolved question] | [Name] | [Date] | [Pending] |
|
||||
|
||||
#### 11. Implementation Timeline (Rough)
|
||||
| Phase | Work | Estimated Effort |
|
||||
|---|---|---|
|
||||
| [Phase 1] | [What gets built] | [X days/points] |
|
||||
| [Phase 2] | [What gets built] | [X days/points] |
|
||||
| Total | | [X story points] |
|
||||
|
||||
---
|
||||
|
||||
## Guidelines
|
||||
|
||||
- The spec is a decision record, not a task list — document *why* decisions were made
|
||||
- All open questions must have an owner and due date
|
||||
- Security and privacy sections are never optional for features that touch user data
|
||||
- Recommend async review: engineers read first, then a 30-minute sync to resolve questions
|
||||
- Keep the spec updated as implementation progresses — stale specs are worse than no specs
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Problem statement contains no solution language
|
||||
- [ ] Non-goals explicitly list at least 2 things that might be assumed in scope
|
||||
- [ ] At least 2 alternative approaches are documented with reasons for rejection
|
||||
- [ ] Security and privacy section is completed for any feature touching user data
|
||||
- [ ] All open questions have a named owner and due date (not "TBD")
|
||||
Vendored
BIN
Binary file not shown.
@@ -0,0 +1,13 @@
|
||||
{
|
||||
"$schema": "https://anthropic.com/claude-code/plugin.schema.json",
|
||||
"name": "pm-design",
|
||||
"version": "1.0.0",
|
||||
"description": "Design & UX skills: UX Research Plan, Design Critique, Accessibility Audit. Create research plans with discussion guides, critique designs using JTBD and Gestalt principles, and audit for WCAG 2.2 compliance.",
|
||||
"author": {
|
||||
"name": "Mohit Aggarwal",
|
||||
"email": "mohit15856@gmail.com"
|
||||
},
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills",
|
||||
"license": "MIT",
|
||||
"keywords": ["product-management", "design", "ux", "user-research", "accessibility", "wcag", "usability", "design-critique"]
|
||||
}
|
||||
Vendored
BIN
Binary file not shown.
@@ -0,0 +1,175 @@
|
||||
---
|
||||
name: accessibility-audit
|
||||
description: "Generate a WCAG 2.2 accessibility audit checklist and remediation suggestions for any UI or design. Use when asked to audit for accessibility, check WCAG compliance, review a design for a11y issues, or create an accessibility remediation plan. Produces a prioritised checklist with pass/fail assessments and specific fixes."
|
||||
---
|
||||
|
||||
# Accessibility Audit Skill
|
||||
|
||||
This skill produces a structured accessibility audit based on WCAG 2.2 guidelines. It covers visual, motor, cognitive, and screen reader accessibility — with prioritised remediation for each issue found.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **What is being audited** (screen, component, full product, design spec)
|
||||
- **Description or image** of the UI
|
||||
- **Target WCAG level** (A / AA / AAA — default to AA, which is the legal standard in most jurisdictions)
|
||||
- **Known assistive technology users?** (Yes/No — if yes, which: screen reader / switch access / voice control / magnification)
|
||||
- **Platform** (Web / iOS / Android / Desktop app)
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# Accessibility Audit: [Component or Screen Name]
|
||||
**Target standard:** WCAG 2.2 Level [AA]
|
||||
**Platform:** [Platform]
|
||||
**Date:** [Date]
|
||||
|
||||
---
|
||||
|
||||
## Audit Summary
|
||||
|
||||
| Category | Issues Found | Critical | Moderate | Minor |
|
||||
|---|---|---|---|---|
|
||||
| Perceivable | | | | |
|
||||
| Operable | | | | |
|
||||
| Understandable | | | | |
|
||||
| Robust | | | | |
|
||||
| **Total** | | | | |
|
||||
|
||||
**Overall compliance status:** ✅ Compliant / 🟡 Minor issues / 🔴 Fails AA standard
|
||||
|
||||
---
|
||||
|
||||
## Perceivable
|
||||
|
||||
### 1.1 Text Alternatives
|
||||
- [ ] All images have descriptive alt text (not filename or "image")
|
||||
- [ ] Decorative images have `alt=""` to be skipped by screen readers
|
||||
- [ ] Icons without visible labels have accessible names
|
||||
- [ ] Complex images (charts, diagrams) have extended descriptions
|
||||
|
||||
**Issues found:** [List specific issues or "None"]
|
||||
|
||||
### 1.3 Adaptable
|
||||
- [ ] Content structure uses semantic HTML (headings, lists, landmarks) — not just visual formatting
|
||||
- [ ] Reading order in DOM matches visual order
|
||||
- [ ] Form inputs have associated labels (not placeholder text as label)
|
||||
- [ ] Data tables have proper headers and scope
|
||||
|
||||
**Issues found:**
|
||||
|
||||
### 1.4 Distinguishable
|
||||
- [ ] Text contrast ratio ≥ 4.5:1 (normal text) or ≥ 3:1 (large text 18px+)
|
||||
- [ ] UI component contrast ratio ≥ 3:1 against background
|
||||
- [ ] Information is not conveyed by colour alone
|
||||
- [ ] Text can be resized to 200% without loss of content
|
||||
- [ ] No content that auto-plays audio
|
||||
|
||||
**Issues found:**
|
||||
|
||||
---
|
||||
|
||||
## Operable
|
||||
|
||||
### 2.1 Keyboard Accessible
|
||||
- [ ] All interactive elements are reachable by keyboard (Tab key)
|
||||
- [ ] No keyboard traps
|
||||
- [ ] Custom components have keyboard interactions (arrow keys for menus, Escape to close modals)
|
||||
- [ ] Skip navigation link available for pages with repeated navigation
|
||||
|
||||
**Issues found:**
|
||||
|
||||
### 2.4 Navigable
|
||||
- [ ] Focus is visible at all times (not removed with `outline: none` without replacement)
|
||||
- [ ] Focus order is logical and predictable
|
||||
- [ ] Page/screen has a descriptive title
|
||||
- [ ] Link text is descriptive (not "click here" or "read more")
|
||||
- [ ] Headings are hierarchical (H1 → H2 → H3, no skips)
|
||||
|
||||
**Issues found:**
|
||||
|
||||
### 2.5 Input Modalities
|
||||
- [ ] Touch targets are at least 44x44px
|
||||
- [ ] No functionality requires complex gestures (pinch, multi-touch) without a simple alternative
|
||||
- [ ] Motion or dragging interactions have button alternatives
|
||||
|
||||
**Issues found:**
|
||||
|
||||
---
|
||||
|
||||
## Understandable
|
||||
|
||||
### 3.1 Readable
|
||||
- [ ] Language of the page is set (`lang` attribute)
|
||||
- [ ] Unusual words, abbreviations, or jargon are explained
|
||||
|
||||
### 3.2 Predictable
|
||||
- [ ] Navigation is consistent across screens
|
||||
- [ ] Components behave consistently (same button does the same thing)
|
||||
- [ ] No unexpected context changes on focus or input
|
||||
|
||||
### 3.3 Input Assistance
|
||||
- [ ] Error messages identify the field and describe the error in plain language (not just "Invalid input")
|
||||
- [ ] Required fields are labelled (not just with colour or asterisk alone)
|
||||
- [ ] Forms provide suggestions for correcting errors where possible
|
||||
|
||||
**Issues found:**
|
||||
|
||||
---
|
||||
|
||||
## Robust
|
||||
|
||||
### 4.1 Compatible
|
||||
- [ ] HTML is valid and well-structured
|
||||
- [ ] ARIA roles and attributes are used correctly (not to fix broken semantics)
|
||||
- [ ] Status messages (success, error, loading) are announced to screen readers without focus change
|
||||
|
||||
**Issues found:**
|
||||
|
||||
---
|
||||
|
||||
## Prioritised Remediation List
|
||||
|
||||
| Priority | Issue | WCAG Criterion | Fix | Effort |
|
||||
|---|---|---|---|---|
|
||||
| 🔴 Critical | [Issue] | [e.g. 1.4.3 Contrast] | [Specific fix] | [Low/Med/High] |
|
||||
| 🟡 Moderate | [Issue] | | | |
|
||||
| 🟢 Minor | [Issue] | | | |
|
||||
|
||||
**Priority definitions:**
|
||||
- 🔴 Critical: Blocks access for users with disabilities. Legal risk. Fix before launch.
|
||||
- 🟡 Moderate: Significant friction. Fix in next sprint.
|
||||
- 🟢 Minor: Best practice. Address in roadmap.
|
||||
|
||||
---
|
||||
|
||||
## Quick Wins (Fix in < 1 hour)
|
||||
|
||||
[List any issues that are trivially fixable — e.g. adding alt text, fixing contrast with a colour swap, adding a `lang` attribute. These are easy to ship immediately.]
|
||||
|
||||
---
|
||||
|
||||
## Testing Recommendations
|
||||
|
||||
- **Manual keyboard test:** Tab through the entire flow. Can you complete every task without a mouse?
|
||||
- **Screen reader test:** VoiceOver (Mac/iOS), NVDA or JAWS (Windows). Is every piece of content and every action accessible?
|
||||
- **Colour contrast check:** Use Stark (Figma plugin) or WebAIM Contrast Checker
|
||||
- **Automated scan:** Axe DevTools or Lighthouse accessibility audit (catches ~30% of issues automatically)
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Issues are mapped to specific WCAG criteria
|
||||
- [ ] Every critical issue has a specific fix recommendation
|
||||
- [ ] Quick wins are separated from larger fixes
|
||||
- [ ] Effort estimates are included for prioritisation
|
||||
- [ ] Testing recommendations are included
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Audit this design for accessibility"
|
||||
- "Check WCAG compliance for [screen/component]"
|
||||
- "Give me an a11y audit of [UI description]"
|
||||
- "What accessibility issues does this design have?"
|
||||
@@ -0,0 +1,130 @@
|
||||
---
|
||||
name: design-critique
|
||||
description: "Give structured, constructive feedback on any design. Use when asked to critique a design, review a UI, give feedback on a Figma file or wireframe, assess a user flow, or evaluate a design against UX principles. Applies Jobs-to-be-Done, Gestalt principles, and usability heuristics to give actionable feedback."
|
||||
---
|
||||
|
||||
# Design Critique Skill
|
||||
|
||||
This skill provides structured, actionable design feedback using established UX frameworks. It balances positive observations with clear, prioritised improvement suggestions.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **What is being reviewed** (screen, flow, component, full product)
|
||||
- **Design description or attached image** (describe it if no image — the skill will still work)
|
||||
- **User goal** (what is the user trying to accomplish with this design?)
|
||||
- **Context** (web / mobile / desktop app / physical product)
|
||||
- **Stage** (early wireframe / mid-fidelity / high-fidelity / live product)
|
||||
- **Primary concern** (optional — e.g. "I'm worried the onboarding is too long" or "I think the CTA is unclear")
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# Design Critique: [Design Name or Screen]
|
||||
|
||||
**User goal:** [What the user needs to accomplish]
|
||||
**Context:** [Platform / Stage]
|
||||
**Critique focus:** [Primary concern if stated, otherwise "full review"]
|
||||
|
||||
---
|
||||
|
||||
## 1. What's Working
|
||||
|
||||
[3–5 specific, honest observations about what the design does well. Don't manufacture praise — only include genuine strengths. Be specific: "The visual hierarchy clearly guides the eye from headline → supporting detail → CTA" is useful. "Looks clean" is not.]
|
||||
|
||||
---
|
||||
|
||||
## 2. Priority Issues
|
||||
|
||||
Rank issues by impact on the user goal. Use:
|
||||
- 🔴 **High** — Blocks or significantly degrades the user's ability to complete their goal
|
||||
- 🟡 **Medium** — Causes friction or confusion but doesn't block completion
|
||||
- 🟢 **Low** — Polish or preference — nice to fix but not critical
|
||||
|
||||
For each issue:
|
||||
|
||||
### [Priority] Issue [N]: [Short name]
|
||||
|
||||
**What's happening:**
|
||||
[Describe the specific design problem — be precise about which element, screen, or interaction]
|
||||
|
||||
**Why it matters:**
|
||||
[Connect to the user goal or a specific principle — don't just say "it's confusing." Say why it creates confusion and what the consequence is for the user.]
|
||||
|
||||
**Framework reference:**
|
||||
[Name the principle being violated — e.g. Nielsen's Heuristic #6 (Recognition over Recall), Gestalt proximity, JTBD clarity, Fitts's Law, etc.]
|
||||
|
||||
**Recommendation:**
|
||||
[Specific, actionable suggestion. Not "make the button bigger" but "Increase the primary CTA to at least 44x44px to meet touch target guidelines; consider moving it below the form rather than inline with the input fields to reduce accidental taps."]
|
||||
|
||||
---
|
||||
|
||||
## 3. Heuristic Assessment
|
||||
|
||||
Quick assessment against Nielsen's 10 Usability Heuristics — score each as ✅ Pass / 🟡 Partial / ❌ Fail:
|
||||
|
||||
| Heuristic | Status | Note |
|
||||
|---|---|---|
|
||||
| 1. Visibility of system status | | |
|
||||
| 2. Match between system and real world | | |
|
||||
| 3. User control and freedom | | |
|
||||
| 4. Consistency and standards | | |
|
||||
| 5. Error prevention | | |
|
||||
| 6. Recognition rather than recall | | |
|
||||
| 7. Flexibility and efficiency of use | | |
|
||||
| 8. Aesthetic and minimalist design | | |
|
||||
| 9. Help users recognise, diagnose, and recover from errors | | |
|
||||
| 10. Help and documentation | | |
|
||||
|
||||
Only include heuristics relevant to what's visible in the design — don't penalise for things not in scope.
|
||||
|
||||
---
|
||||
|
||||
## 4. Gestalt Principles Check
|
||||
|
||||
[Comment on any Gestalt principles that are either well-applied or violated:]
|
||||
|
||||
- **Proximity:** [Are related elements grouped clearly?]
|
||||
- **Similarity:** [Do similar elements look similar?]
|
||||
- **Continuity:** [Does the eye flow naturally through the design?]
|
||||
- **Figure/Ground:** [Is the primary content clearly distinguished from background?]
|
||||
- **Closure:** [Are any implied shapes or containers confusing?]
|
||||
|
||||
---
|
||||
|
||||
## 5. JTBD Alignment
|
||||
|
||||
[Assess how well the design serves the stated job-to-be-done:]
|
||||
|
||||
- **Does the design make the user's primary job obvious?** [Yes / Partially / No — explain]
|
||||
- **Are there any elements that distract from the primary job?** [List any competing CTAs, distractions, or unclear hierarchy]
|
||||
- **What emotional job does this design serve?** [Speed / Confidence / Control / Delight / Other] — and does the visual design match that emotional goal?
|
||||
|
||||
---
|
||||
|
||||
## 6. Top 3 Recommended Next Steps
|
||||
|
||||
Prioritised list of the 3 most impactful changes. Each should be actionable in the next design iteration:
|
||||
|
||||
1. [Most impactful change — specific]
|
||||
2. [Second priority]
|
||||
3. [Third priority]
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] "What's working" includes only genuine, specific observations
|
||||
- [ ] Every issue has a framework reference (not just subjective opinion)
|
||||
- [ ] Recommendations are specific and actionable
|
||||
- [ ] Priority levels (High/Medium/Low) reflect actual impact on user goal
|
||||
- [ ] Heuristic assessment only covers visible elements
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Critique this design: [description or image]"
|
||||
- "Give me feedback on this UI/UX"
|
||||
- "Review this Figma screen for usability issues"
|
||||
- "What's wrong with this user flow?"
|
||||
- "Do a heuristic evaluation of [screen/product]"
|
||||
@@ -0,0 +1,160 @@
|
||||
---
|
||||
name: ux-research-plan
|
||||
description: "Create a structured UX research plan for any product question or feature. Use when asked to write a research plan, design a user study, create a discussion guide, write screener questions, or plan usability testing. Produces a full research plan with objectives, methodology, screener, discussion guide, and synthesis framework."
|
||||
---
|
||||
|
||||
# UX Research Plan Skill
|
||||
|
||||
This skill creates a complete, ready-to-execute UX research plan. Output covers everything from research objectives to screener questions, discussion guide, and synthesis framework.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Research question** (what decision will this research inform?)
|
||||
- **Product area or feature** being researched
|
||||
- **Research type** (Generative / Evaluative / Usability testing / Diary study / Survey)
|
||||
- **Stage** (Discovery / Concept validation / Prototype testing / Live product)
|
||||
- **Target participants** (role, demographics, behaviour — who should we talk to?)
|
||||
- **Timeline and number of sessions**
|
||||
- **Existing assumptions or hypotheses** (optional but valuable)
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# UX Research Plan: [Study Title]
|
||||
**Product area:** [Area]
|
||||
**Research type:** [Type]
|
||||
**Date:** [Timeline]
|
||||
**Researcher:** [Leave for user]
|
||||
|
||||
---
|
||||
|
||||
## 1. Research Objectives
|
||||
|
||||
State 2–4 clear research objectives. Each objective should map to a decision that will be made differently depending on what you find.
|
||||
|
||||
**Objective [N]:** Understand [specific thing] so we can [decision this informs].
|
||||
|
||||
---
|
||||
|
||||
## 2. Research Questions
|
||||
|
||||
[5–8 questions — the actual questions you want research to answer. These are not the interview questions; they're the knowledge gaps. Organised under each objective.]
|
||||
|
||||
**Objective 1:**
|
||||
- RQ1.1: [Research question]
|
||||
- RQ1.2: [Research question]
|
||||
|
||||
---
|
||||
|
||||
## 3. Methodology & Rationale
|
||||
|
||||
**Method chosen:** [e.g. Semi-structured interviews / Usability testing / Concept testing]
|
||||
|
||||
**Why this method:**
|
||||
[2–3 sentences. Match method to research type. If evaluative: usability testing. If generative: contextual inquiry or interviews. If testing comprehension: 5-second test or concept test.]
|
||||
|
||||
**What this method will and won't tell us:**
|
||||
- **Will tell us:** [What this method is good at revealing]
|
||||
- **Won't tell us:** [What's out of scope — be honest about limits]
|
||||
|
||||
**Sample size:** [Recommended number of sessions and why — e.g. "5–6 moderated interviews for generative research; 5–8 usability sessions to identify top issues"]
|
||||
|
||||
---
|
||||
|
||||
## 4. Participant Screener
|
||||
|
||||
**Recruitment criteria:**
|
||||
|
||||
| Criterion | Must Have / Nice to Have | Disqualify if |
|
||||
|---|---|---|
|
||||
| [e.g. Uses project management software daily] | Must Have | [Never uses any PM tool] |
|
||||
| [e.g. Works in a team of 5+] | Must Have | — |
|
||||
| [e.g. B2B industry] | Nice to Have | — |
|
||||
|
||||
**Screener questions (5–8 questions):**
|
||||
|
||||
[Q1] [Screening question — clear, not leading]
|
||||
- [Answer options — flag which qualify/disqualify]
|
||||
|
||||
[Q2] ...
|
||||
|
||||
**Incentive recommendation:** [Amount and format — e.g. "£50 gift voucher for a 60-min session is standard in the UK for professional participants"]
|
||||
|
||||
---
|
||||
|
||||
## 5. Discussion Guide
|
||||
|
||||
Structure the session:
|
||||
|
||||
### Opening (5 min)
|
||||
- Introduce yourself and the study
|
||||
- "We're testing the design, not you — there are no wrong answers"
|
||||
- Permission to record
|
||||
- Warm-up: [1–2 easy questions to build rapport — e.g. "Tell me about your role and what a typical week looks like"]
|
||||
|
||||
### Core Questions (by section)
|
||||
|
||||
**Section [A]: [Topic]** *(~X min)*
|
||||
|
||||
1. [Open question — start broad] *[Probe: Tell me more about...]*
|
||||
2. [Follow-up to go deeper] *[Probe: Can you walk me through what happened?]*
|
||||
3. [Specific scenario or past behaviour question]
|
||||
|
||||
**Section [B]: [Topic]** *(~X min)*
|
||||
[Continue with 2–3 questions per section]
|
||||
|
||||
**Usability tasks (if applicable):**
|
||||
> "I'm going to ask you to try a few things with this prototype. Please think aloud as you go."
|
||||
|
||||
- Task [N]: [Clear task instruction — write from the user's perspective, not "click on X" but "find where you would go to do Y"]
|
||||
- **Success criteria:** [What "completing this task" looks like]
|
||||
- **What to observe:** [Where friction typically appears]
|
||||
|
||||
### Closing (5 min)
|
||||
- "Is there anything about [topic] we haven't covered that you think is important?"
|
||||
- "If you could change one thing about [product/concept], what would it be?"
|
||||
- Debrief and thank
|
||||
|
||||
---
|
||||
|
||||
## 6. Synthesis Framework
|
||||
|
||||
After sessions, use this framework to synthesise findings:
|
||||
|
||||
**Step 1: Session notes → Key observations**
|
||||
For each session: 3–5 specific observations (behaviours, quotes, reactions — not interpretations yet)
|
||||
|
||||
**Step 2: Affinity mapping**
|
||||
Group observations by theme across all sessions. Aim for 4–7 clusters.
|
||||
|
||||
**Step 3: Insight statements**
|
||||
For each cluster: "When [context], users [behaviour/experience], because [underlying need or mental model]."
|
||||
|
||||
**Step 4: Implications**
|
||||
For each insight: "This means we should [design/product implication]" or "This challenges our assumption that [assumption]."
|
||||
|
||||
**Step 5: Research report structure:**
|
||||
- Key findings (3–5 headlines)
|
||||
- Supporting evidence per finding
|
||||
- Design recommendations
|
||||
- Open questions for next research cycle
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Research objectives map to real decisions
|
||||
- [ ] Discussion guide opens broad before going specific
|
||||
- [ ] Screener criteria are specific enough to get the right participants
|
||||
- [ ] Tasks (if usability) are written from the user's perspective
|
||||
- [ ] Synthesis framework is included
|
||||
- [ ] Incentive recommendation is included
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Write a research plan for [feature or product area]"
|
||||
- "Create a discussion guide for user interviews about [topic]"
|
||||
- "Plan a usability test for [prototype or feature]"
|
||||
- "Write screener questions for [target user type]"
|
||||
Vendored
BIN
Binary file not shown.
@@ -0,0 +1,13 @@
|
||||
{
|
||||
"$schema": "https://anthropic.com/claude-code/plugin.schema.json",
|
||||
"name": "pm-discovery",
|
||||
"version": "3.0.0",
|
||||
"description": "Discovery & research skills: Discovery Interview Guide, Job Story Mapper, User Interview Synthesis, Assumption Mapper. Structure user research from screener to synthesis.",
|
||||
"author": {
|
||||
"name": "Mohit Aggarwal",
|
||||
"email": "mohit15856@gmail.com"
|
||||
},
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills",
|
||||
"license": "MIT",
|
||||
"keywords": ["product-management", "user-research", "discovery", "jtbd", "interviews", "assumption-mapping"]
|
||||
}
|
||||
BIN
Binary file not shown.
@@ -0,0 +1,59 @@
|
||||
---
|
||||
name: assumption-mapper
|
||||
description: "Extract and risk-rate hidden assumptions in a product brief or PRD. Use when asked to review a product brief for assumptions, audit a PRD for risks, find hidden assumptions, validate product plans, or run an assumption analysis. Produces a prioritised assumption map with confidence and impact scores, recommended validation methods, and critical assumption flags."
|
||||
---
|
||||
|
||||
# Assumption Mapper Skill
|
||||
|
||||
Surface and prioritize the untested assumptions embedded in any product plan before development begins.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Product brief, PRD, or concept description** (even rough notes work)
|
||||
- **Stage** (concept / discovery / pre-build / post-launch — affects which assumptions matter most)
|
||||
|
||||
## Process
|
||||
1. Read the provided brief, PRD, or concept description
|
||||
2. Extract assumptions across four categories:
|
||||
- **Desirability** (do users want this?)
|
||||
- **Feasibility** (can we build it?)
|
||||
- **Viability** (will it sustain the business?)
|
||||
- **Usability** (can users actually use it?)
|
||||
3. Score each assumption:
|
||||
- Confidence (1-5): How sure are we this is true?
|
||||
- Impact (1-5): How badly does the plan fail if this assumption is wrong?
|
||||
- Priority = Impact − Confidence (higher = test first)
|
||||
4. **Validate completeness** — Ensure at least one assumption per category. If a category is empty, re-read the brief looking specifically for that type.
|
||||
5. Output a ranked list with recommended validation methods
|
||||
|
||||
## Output Structure
|
||||
|
||||
### Assumption Map: [Feature/Product Name]
|
||||
|
||||
| Assumption | Category | Confidence | Impact | Priority | Validation Method |
|
||||
|------------|----------|------------|--------|----------|-------------------|
|
||||
| [assumption] | [type] | [1-5] | [1-5] | [score] | [method] |
|
||||
|
||||
#### Critical Assumptions (Impact 4+ and Confidence 2 or below)
|
||||
[Flagged items with detailed validation recommendations]
|
||||
|
||||
#### Top 3 Assumptions to Validate First
|
||||
[Detailed recommendations including specific research method, estimated effort, and what the result would change]
|
||||
|
||||
## Example (Partial)
|
||||
|
||||
Input: *"We're building a self-serve onboarding flow to reduce time-to-value for SMB customers."*
|
||||
|
||||
| Assumption | Category | Confidence | Impact | Priority | Validation Method |
|
||||
|------------|----------|------------|--------|----------|-------------------|
|
||||
| SMB users can complete onboarding without human help | Usability | 2 | 5 | 3 | Unmoderated usability test (n=8) |
|
||||
| Faster onboarding correlates with higher retention | Viability | 3 | 4 | 1 | Cohort analysis of current onboarding times vs. 90-day retention |
|
||||
| The current onboarding is the primary reason for slow time-to-value | Desirability | 2 | 4 | 2 | User interviews with recent churned SMB accounts |
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] At least one assumption per category (Desirability, Feasibility, Viability, Usability)
|
||||
- [ ] All Impact 4+ / Confidence 2− assumptions flagged as CRITICAL
|
||||
- [ ] Each validation method is specific (not just "do research" — name the method and sample size)
|
||||
- [ ] Priority scores are consistent (Impact − Confidence, higher = more urgent)
|
||||
@@ -0,0 +1,107 @@
|
||||
---
|
||||
name: discovery-interview-guide
|
||||
description: "Create a structured user discovery interview guide with screener questions, a discussion guide, and a synthesis framework. Use when planning user interviews, customer discovery sessions, Jobs-to-be-Done research, or problem validation. Produces a complete guide covering warm-up, problem exploration, and a per-session synthesis template."
|
||||
---
|
||||
|
||||
# Discovery Interview Guide Skill
|
||||
|
||||
Design interviews that surface genuine insight — not validation of what you already believe. Every guide follows a story-based, past-behaviour-focused structure.
|
||||
|
||||
## Core Principles
|
||||
|
||||
1. **Never ask about the future.** "Would you use X?" tells you nothing. "Tell me about the last time you did X" tells you everything.
|
||||
2. **Interview for behaviour, not opinion.** Opinions are cheap. Behaviour is evidence.
|
||||
3. **The 5 Whys.** Every surface answer is a door. Keep opening doors.
|
||||
4. **Confirm the problem before exploring the solution.** Never show a prototype until you've confirmed the pain exists unprompted.
|
||||
|
||||
## Interview Structure (60 minutes standard)
|
||||
|
||||
### 1. Warm-Up (5 min)
|
||||
Build rapport. Get them talking. Don't discuss the topic yet.
|
||||
- "Tell me a bit about your role and what a typical week looks like for you."
|
||||
- "What tools do you rely on most day-to-day?"
|
||||
|
||||
### 2. Context Setting (10 min)
|
||||
Understand their world before diving into the problem space.
|
||||
- "Walk me through how you currently [handle the domain area]."
|
||||
- "What does that process look like from start to finish?"
|
||||
- "Who else is involved when you do this?"
|
||||
|
||||
### 3. Problem Exploration (25 min) — THE CORE
|
||||
Surface pain without leading.
|
||||
- "Tell me about the last time you had to [relevant task]. What happened?"
|
||||
- "What was the hardest part of that?"
|
||||
- "How did you handle it?"
|
||||
- "What did you try before settling on that approach?"
|
||||
- "What does it cost you when this goes wrong?" (time, money, stress, reputation)
|
||||
- "If you could wave a magic wand and change one thing about this process, what would it be?"
|
||||
|
||||
⚠️ **Do not mention your product or feature during this phase.**
|
||||
|
||||
### 4. Current Solutions (10 min)
|
||||
Understand the competitive landscape from their perspective.
|
||||
- "What tools or workarounds do you use today for this?"
|
||||
- "What do you like about [current solution]? What frustrates you?"
|
||||
- "Have you tried other approaches? What happened?"
|
||||
|
||||
### 5. Wrap-Up (10 min)
|
||||
- "Is there anything about this topic we haven't covered that you think I should know?"
|
||||
- "Is there anyone else you'd recommend I speak to?"
|
||||
- "Would you be open to a follow-up if I have more questions?"
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
### Discovery Interview Guide — [Topic] — [Date]
|
||||
|
||||
**Research Goal:** [One sentence: what decision will this research inform?]
|
||||
**Target Participant Profile:** [Role, company size, behaviour qualifier]
|
||||
|
||||
**Screener Questions** (for recruiting):
|
||||
1. [Question] → Must answer: [Y/N or specific]
|
||||
2. [Question] → Must answer: [Y/N or specific]
|
||||
3. [Disqualifier question] → Disqualify if: [answer]
|
||||
|
||||
**Interview Guide:**
|
||||
|
||||
[Full structured guide using the format above, customised to the specific research topic]
|
||||
|
||||
**Synthesis Template** (fill after each interview):
|
||||
- Key quote: "[verbatim]"
|
||||
- Core pain: [1 sentence]
|
||||
- Current workaround: [what they're doing today]
|
||||
- Intensity (1–5): [how painful is this?]
|
||||
- Surprise/unexpected finding: [anything that challenged your assumptions]
|
||||
|
||||
**Pattern Detection** (after 5+ interviews):
|
||||
- Pain mentioned by [X/N] participants: [theme]
|
||||
- Workaround used by [X/N] participants: [theme]
|
||||
- Most emotionally charged moment in interviews: [observation]
|
||||
|
||||
---
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Research topic or question** (what decision will this inform?)
|
||||
- **Target participant profile** (role, behaviour, company type)
|
||||
- **Session length** (30 / 45 / 60 / 90 minutes)
|
||||
- **Number of interviews planned**
|
||||
- **Known hypotheses to test or avoid confirming prematurely** (optional)
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] No future-tense questions ("would you...") — only past-behaviour questions
|
||||
- [ ] Product or solution not mentioned until after pain is confirmed
|
||||
- [ ] Questions open-ended (cannot be answered yes/no)
|
||||
- [ ] Synthesis template included for per-session notes
|
||||
- [ ] Screener questions identify and disqualify wrong participants
|
||||
|
||||
## Guidelines
|
||||
|
||||
- Recommend 5–8 interviews to reach thematic saturation for most discovery questions
|
||||
- Always record with permission — transcripts beat notes
|
||||
- If user is new to interviewing: remind them to stay silent after asking a question (aim for 80/20 participant-to-interviewer talking ratio)
|
||||
- Never synthesise during the interview — do it after, when you can look across sessions
|
||||
- Flag confirmation bias: if user writes questions that lead toward a predetermined answer, rewrite them as open-ended alternatives
|
||||
@@ -0,0 +1,122 @@
|
||||
---
|
||||
name: job-story-mapper
|
||||
description: "Write Jobs-to-be-Done (JTBD) job stories and map customer jobs across functional, social, and emotional dimensions. Use when defining user needs, writing job stories, conducting JTBD research, or reframing features around customer outcomes. Produces a job story map with opportunity scoring, pain intensity ratings, and product opportunity analysis."
|
||||
---
|
||||
|
||||
# Job Story Mapper Skill
|
||||
|
||||
Stop writing features. Start understanding jobs. This skill translates product requirements and user interviews into precise job stories that keep the team focused on outcomes — not outputs.
|
||||
|
||||
## Jobs-to-be-Done Fundamentals
|
||||
|
||||
A "job" is the progress a customer is trying to make in a given situation. People don't buy products — they hire them to get a job done.
|
||||
|
||||
Three dimensions of every job:
|
||||
- **Functional job:** The practical task ("get from A to B")
|
||||
- **Emotional job:** How they want to feel ("feel confident I made the right choice")
|
||||
- **Social job:** How they want to be perceived ("look like a competent professional to my team")
|
||||
|
||||
Great products address all three. Most roadmaps only address the functional one.
|
||||
|
||||
---
|
||||
|
||||
## Job Story Format
|
||||
|
||||
**Template:**
|
||||
> When [situation/trigger], I want to [motivation/goal], so I can [expected outcome].
|
||||
|
||||
**Not a user story:**
|
||||
User stories focus on roles and features: "As a [role] I want [feature] so that [benefit]."
|
||||
Job stories focus on situations and motivations: "When [I'm in this specific situation] I want [this capability] so I can [achieve this outcome]."
|
||||
|
||||
**The situation is the most important part.** "When I'm in the middle of a sprint and my PM asks for an update" is a much richer trigger than "As a developer."
|
||||
|
||||
---
|
||||
|
||||
## Mapping Process
|
||||
|
||||
### Step 1: Identify the main job
|
||||
One sentence: What is the core job your product is hired for?
|
||||
> "Help [user type] [accomplish outcome] when [context]."
|
||||
|
||||
### Step 2: Break into job steps
|
||||
What are all the sub-tasks within the main job?
|
||||
(Use a job map: Define → Locate → Prepare → Confirm → Execute → Monitor → Modify → Conclude)
|
||||
|
||||
### Step 3: Identify pain points per step
|
||||
Where does the job fall down today? Where do customers use workarounds?
|
||||
|
||||
### Step 4: Write job stories for each pain point
|
||||
One job story per distinct situation-motivation pair.
|
||||
|
||||
### Step 5: Map to product opportunities
|
||||
Which job stories are underserved? Which have existing solutions? Where is your differentiation?
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
### Job Story Map — [Product/Feature Area] — [Date]
|
||||
|
||||
**Core Job Statement:**
|
||||
> When [context], [user type] wants to [main job outcome], so they can [ultimate goal].
|
||||
|
||||
---
|
||||
|
||||
**Job Map:**
|
||||
|
||||
| Step | Sub-Job | Current Solution | Pain Points | Underserved? |
|
||||
|---|---|---|---|---|
|
||||
| Define | [What user does] | [Tool/method used] | [Frustration] | H/M/L |
|
||||
| Locate | | | | |
|
||||
| Prepare | | | | |
|
||||
| Confirm | | | | |
|
||||
| Execute | | | | |
|
||||
| Monitor | | | | |
|
||||
| Modify | | | | |
|
||||
| Conclude | | | | |
|
||||
|
||||
---
|
||||
|
||||
**Job Stories (prioritised by underservice):**
|
||||
|
||||
**Job Story 1 — [Situation label]**
|
||||
> When [specific situation], I want to [motivation], so I can [outcome].
|
||||
|
||||
Functional dimension: [What they need to get done]
|
||||
Emotional dimension: [How they want to feel]
|
||||
Social dimension: [How they want to be perceived]
|
||||
|
||||
Current workaround: [What they do today]
|
||||
Pain intensity: [High / Medium / Low]
|
||||
Frequency: [How often this situation occurs]
|
||||
Product opportunity: [What we could build to address this]
|
||||
|
||||
---
|
||||
|
||||
Repeat for each major job story.
|
||||
|
||||
**Opportunity Scoring:**
|
||||
Rate each job story on:
|
||||
- Importance to customer (1–10)
|
||||
- Satisfaction with current solution (1–10)
|
||||
- Opportunity score = Importance + max(Importance – Satisfaction, 0)
|
||||
- Prioritise: Opportunity score > 10
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Job stories use the "When / I want to / So I can" format (not user story format)
|
||||
- [ ] Situation is specific (not "as a user" — a real moment or trigger)
|
||||
- [ ] All three dimensions covered: functional, emotional, social
|
||||
- [ ] Opportunity score calculated for each job story
|
||||
- [ ] Current workaround identified for each high-opportunity story
|
||||
- [ ] Product opportunity is distinct from "build the feature" (it's an outcome)
|
||||
|
||||
## Guidelines
|
||||
|
||||
- Never write a job story for a feature — write it for the situation that makes the feature valuable
|
||||
- If you can't identify the situation, you don't understand the job yet — go back to user research
|
||||
- Social and emotional jobs are harder to surface but often the most defensible differentiators
|
||||
- Recommend sharing job stories with engineering — they make better technical decisions when they understand the "why"
|
||||
@@ -0,0 +1,52 @@
|
||||
---
|
||||
name: user-interview-synthesis
|
||||
description: "Synthesise user interview transcripts into structured research findings. Use when asked to analyse interview notes, synthesise qualitative research, identify themes from user interviews, or turn raw interview data into actionable product insights. Produces a themed synthesis with supporting quotes, 'so what' implications, and recommended next steps."
|
||||
---
|
||||
|
||||
# User Interview Synthesis Skill
|
||||
|
||||
Transform raw interview transcripts into a structured synthesis document that surfaces themes, pain points, and actionable insights.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Interview transcripts or notes** (even rough notes work)
|
||||
- **Number of participants and their profiles** (role, company size, context)
|
||||
- **Research questions** (what was the study trying to answer?)
|
||||
- **Date range** of research (for context)
|
||||
|
||||
## Process
|
||||
1. Read all provided transcripts fully before drawing conclusions
|
||||
2. Identify recurring themes (minimum 3 mentions to qualify as a theme)
|
||||
3. Categorize findings into: Pain Points, Workflow Insights, Feature Requests, Delight Moments
|
||||
4. Select 2-3 verbatim quotes per theme that best represent the pattern
|
||||
5. Draft "So What" implications for each theme — what does this mean for the product?
|
||||
6. **Validate** — Confirm every theme has quotes from at least 3 participants. Flag any insight resting on fewer as low-confidence.
|
||||
|
||||
## Output Structure
|
||||
|
||||
### Research Synthesis: [Study Name]
|
||||
**Participants:** [n]
|
||||
**Date Range:** [dates]
|
||||
**Research Questions:** [list]
|
||||
|
||||
#### Theme 1: [Theme Name]
|
||||
- Summary (2-3 sentences)
|
||||
- Supporting quotes (from at least 3 participants)
|
||||
- Implication for product
|
||||
|
||||
[Repeat for each theme]
|
||||
|
||||
#### Low-Confidence Signals (1-2 participants only)
|
||||
[Findings worth tracking but not acting on yet — note what further research would confirm or deny]
|
||||
|
||||
#### Recommended Next Steps
|
||||
[Specific, actionable recommendations based on findings]
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Every theme is supported by quotes from at least 3 participants
|
||||
- [ ] Implications connect to specific product decisions, not just observations
|
||||
- [ ] Researcher bias check: no leading language, findings don't all support one hypothesis
|
||||
- [ ] Single-source signals are flagged separately, not mixed into main themes
|
||||
- [ ] Research questions from the study brief are each addressed (even if the answer is "inconclusive")
|
||||
Vendored
BIN
Binary file not shown.
@@ -0,0 +1,13 @@
|
||||
{
|
||||
"$schema": "https://anthropic.com/claude-code/plugin.schema.json",
|
||||
"name": "pm-engineering",
|
||||
"version": "4.0.0",
|
||||
"description": "Engineering & tech skills: Code Review Checklist, Incident Postmortem, API Docs Writer, Architecture Decision Record, Debugging Log Analyser, PR Description Writer, System Design Interview, Changelog Generator, Test Strategy Doc, Runbook Writer, CI/CD Playbook, SLO & Error Budget, Developer Onboarding Doc, On-Call Runbook, Security Threat Model, Performance Budget, Database Schema Design, Database Migration Plan, Technical Debt Register, RFC Writer, Capacity Planning, Load Testing Plan, Disaster Recovery Plan, Feature Flag Guide, Dependency Audit, Service Catalog Entry, Monitoring Setup Guide, Local Dev Setup, API Versioning Strategy, Infra-as-Code Review, Engineering Weekly Report, Tech Radar, Sprint Velocity Analysis, Microservices Decomposition, Engineering Hiring Rubric. 35 structured skills for engineering teams, SREs, and technical PMs.",
|
||||
"author": {
|
||||
"name": "Mohit Aggarwal",
|
||||
"email": "mohit15856@gmail.com"
|
||||
},
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills",
|
||||
"license": "MIT",
|
||||
"keywords": ["product-management", "engineering", "code-review", "incident-postmortem", "api-documentation", "adr", "architecture", "debugging", "pull-request", "system-design", "changelog", "test-strategy", "runbook", "devops", "cicd", "slo", "error-budget", "onboarding", "oncall", "sre", "reliability", "security", "threat-model", "performance", "database", "migration", "technical-debt", "rfc", "capacity-planning", "load-testing", "disaster-recovery", "feature-flags", "dependency-audit", "service-catalog", "monitoring", "observability", "tech-radar", "microservices", "hiring", "velocity"]
|
||||
}
|
||||
@@ -0,0 +1,148 @@
|
||||
---
|
||||
name: api-docs-writer
|
||||
description: "Write clear, developer-facing API documentation. Use when asked to document an API endpoint, write API reference docs, create a developer guide, or turn a raw spec/Postman collection into documentation. Produces endpoint documentation with descriptions, parameters, request/response examples, and error codes."
|
||||
---
|
||||
|
||||
# API Docs Writer Skill
|
||||
|
||||
This skill transforms raw API specs, endpoint descriptions, or Postman collections into clean, developer-facing documentation following OpenAPI-adjacent conventions. Output is ready for a developer portal, README, or Notion/Confluence page.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **API or endpoint details** (raw spec, Postman export, or verbal description)
|
||||
- **Auth method** (API key / Bearer token / OAuth 2.0 / None)
|
||||
- **Base URL**
|
||||
- **API version** (e.g. v1, v2.3, or "unversioned" — affects deprecation notes and versioning headers)
|
||||
- **Rate limits** (requests per second/minute per token or IP, if known — or "unknown")
|
||||
- **Audience** (internal developers / external partners / public)
|
||||
- **Output format** (Markdown for developer portals and READMEs / Plain prose for Confluence or Notion — note: OpenAPI YAML is not produced by this skill)
|
||||
|
||||
## Output Format
|
||||
|
||||
For each endpoint, produce the following:
|
||||
|
||||
---
|
||||
|
||||
## `[METHOD] /path/to/endpoint`
|
||||
|
||||
**Summary:** [One line — what this endpoint does]
|
||||
|
||||
**Description:** [2–4 sentences. When to use this endpoint. What it returns. Any important behaviour to know (pagination, rate limits, async processing, etc.)]
|
||||
|
||||
**Authentication:** [Required / Optional — method]
|
||||
|
||||
---
|
||||
|
||||
### Request
|
||||
|
||||
**Headers:**
|
||||
|
||||
| Header | Required | Description |
|
||||
|---|---|---|
|
||||
| `Authorization` | Yes | `Bearer <token>` |
|
||||
| `Content-Type` | Yes | `application/json` |
|
||||
|
||||
**Path Parameters:**
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|---|---|---|---|
|
||||
| `id` | string | Yes | Unique identifier for the resource |
|
||||
|
||||
**Query Parameters:**
|
||||
|
||||
| Parameter | Type | Required | Default | Description |
|
||||
|---|---|---|---|---|
|
||||
| `limit` | integer | No | 20 | Max results per page (1–100) |
|
||||
| `cursor` | string | No | — | Pagination cursor from previous response |
|
||||
|
||||
**Request Body:**
|
||||
|
||||
```json
|
||||
{
|
||||
"field_name": "value",
|
||||
"another_field": 42
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|---|---|---|---|
|
||||
| `field_name` | string | Yes | [Plain description of what this field does] |
|
||||
| `another_field` | integer | No | [Description. Include valid range or enum values if applicable] |
|
||||
|
||||
---
|
||||
|
||||
### Response
|
||||
|
||||
**Success Response: `200 OK`**
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "abc123",
|
||||
"status": "active",
|
||||
"created_at": "2025-04-01T10:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Description |
|
||||
|---|---|---|
|
||||
| `id` | string | Unique identifier for the created/retrieved resource |
|
||||
| `status` | string | Current status. Enum: `active`, `inactive`, `pending` |
|
||||
| `created_at` | ISO 8601 string | Timestamp of creation in UTC |
|
||||
|
||||
---
|
||||
|
||||
### Error Codes
|
||||
|
||||
| Status Code | Error Code | Description | How to Resolve |
|
||||
|---|---|---|---|
|
||||
| `400` | `INVALID_REQUEST` | Request body is malformed or missing required fields | Check request body against schema above |
|
||||
| `401` | `UNAUTHORIZED` | Missing or invalid authentication token | Verify your API key or refresh your token |
|
||||
| `404` | `NOT_FOUND` | The requested resource does not exist | Check the ID in the path parameter |
|
||||
| `429` | `RATE_LIMITED` | Too many requests | Back off and retry after `Retry-After` header value |
|
||||
| `500` | `INTERNAL_ERROR` | Unexpected server error | Retry with exponential backoff; contact support if persists |
|
||||
|
||||
---
|
||||
|
||||
### Code Examples
|
||||
|
||||
Produce examples in at least 2 languages relevant to the audience (default: cURL + Python):
|
||||
|
||||
**cURL:**
|
||||
```bash
|
||||
curl -X POST https://api.example.com/v1/endpoint \
|
||||
-H "Authorization: Bearer YOUR_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"field_name": "value"}'
|
||||
```
|
||||
|
||||
**Python:**
|
||||
```python
|
||||
import requests
|
||||
|
||||
response = requests.post(
|
||||
"https://api.example.com/v1/endpoint",
|
||||
headers={"Authorization": "Bearer YOUR_TOKEN"},
|
||||
json={"field_name": "value"}
|
||||
)
|
||||
data = response.json()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Every parameter is documented (type, required/optional, description)
|
||||
- [ ] Response fields are fully documented with types
|
||||
- [ ] All relevant error codes are listed with resolution guidance
|
||||
- [ ] Error codes cover at minimum: 400 (bad request), 401/403 (auth), 404 (not found), 429 (rate limited), 500 (server error) — or explicitly note which don't apply to this endpoint
|
||||
- [ ] Code examples use the actual base URL and a realistic placeholder token — no examples reference undefined variables or "YOUR_ENDPOINT" outside the snippet
|
||||
- [ ] Auth method is clearly stated at the top
|
||||
- [ ] Enum values are listed where applicable
|
||||
- [ ] Pagination documented if the endpoint is a list endpoint
|
||||
|
||||
## Usage Examples
|
||||
- "Document this API endpoint: [paste spec or description]"
|
||||
- "Turn this Postman collection into developer docs"
|
||||
- "Write API reference docs for [endpoint]"
|
||||
- "Write a developer guide for our [product] API"
|
||||
@@ -0,0 +1,312 @@
|
||||
---
|
||||
name: api-versioning-strategy
|
||||
description: "Write an API versioning strategy document for a service or API platform. Use when asked to define versioning policy, plan API deprecation, classify breaking changes, or document version lifecycle. Produces a complete versioning strategy with breaking-change classification table, deprecation timeline, migration guide template, and client communication template."
|
||||
---
|
||||
|
||||
# API Versioning Strategy
|
||||
|
||||
Produce a complete API versioning strategy document that gives a service team durable, consistent rules for evolving their API without breaking consumers. This document covers the versioning scheme selection (with rationale), lifecycle policy from introduction through sunset, a precise breaking-change classification, and all the communication artifacts a team needs when deprecating a version. Engineers should be able to hand this document to a new team member or external consumer and have them understand exactly what to expect.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask for these if not already provided:
|
||||
- **API type** — REST, GraphQL, or gRPC (each has different versioning mechanics)
|
||||
- **Current versioning approach** — URL path (`/v1/`), request header, query parameter, or none; if none, document starts fresh
|
||||
- **Number of existing versions and active consumer count** — needed to size the lifecycle policy and migration scope
|
||||
- **Deprecation timeline constraints** — any hard deadlines (contract SLAs, compliance windows, annual release cycles)
|
||||
- **Consumer type** — internal teams only, external partners, public API, or mix (affects communication channel choices)
|
||||
|
||||
If any input is missing, ask before producing the document. For GraphQL, note that the versioning approach differs substantially (schema evolution over versioning) and tailor the scheme section accordingly.
|
||||
|
||||
## Output Format
|
||||
|
||||
---
|
||||
|
||||
# API Versioning Strategy: [Service Name]
|
||||
|
||||
**Owner:** [Team Name]
|
||||
**API Type:** [REST / GraphQL / gRPC]
|
||||
**Document Version:** 1.0
|
||||
**Last Reviewed:** [Date]
|
||||
**Next Review:** [Date + 6 months]
|
||||
|
||||
---
|
||||
|
||||
## 1. Versioning Scheme
|
||||
|
||||
### Selected Approach: [URL Path / Request Header / Query Parameter]
|
||||
|
||||
| Scheme | Example | Pros | Cons | Verdict |
|
||||
|--------|---------|------|------|---------|
|
||||
| URL Path | `/v2/orders` | Visible in logs and bookmarks; trivial to route | Violates strict REST resource identity; clutters URL space | **Recommended for public-facing REST APIs** |
|
||||
| `Accept` Header | `Accept: application/vnd.[service].v2+json` | Keeps URLs clean; proper content negotiation | Harder to test in browser; less visible in logs | Recommended for internal APIs with controlled clients |
|
||||
| Query Parameter | `/orders?version=2` | Easy to retrofit without URL restructuring | Often missed in client code; cache-key complications | Acceptable only for read-heavy APIs already in production |
|
||||
| GraphQL Schema Evolution | Field deprecation + `@deprecated` directive | No versioning needed for additive changes | Requires disciplined schema design | **Recommended for GraphQL APIs** |
|
||||
|
||||
**Rationale for [chosen scheme]:** [One paragraph explaining why this scheme fits the API type, consumer type, and operational context provided. Reference the specific inputs — e.g., "Because this API has external partners who integrate via generated clients, URL path versioning provides the most predictable routing behavior and eliminates header negotiation complexity."]
|
||||
|
||||
### Version Format
|
||||
|
||||
```
|
||||
[Base URL]/v{MAJOR}/{resource}
|
||||
|
||||
Examples:
|
||||
https://api.[company].com/v1/orders
|
||||
https://api.[company].com/v2/orders/{id}/items
|
||||
|
||||
Version identifier: integer only (v1, v2, v3)
|
||||
No minor versions in the URL — minor/patch changes are non-breaking and deployed continuously.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Version Lifecycle Policy
|
||||
|
||||
### Lifecycle Stages
|
||||
|
||||
```
|
||||
STABLE ──────────────────────────────────────────────────►
|
||||
│
|
||||
├─ STABLE Active development, full SLA, new consumers allowed
|
||||
│
|
||||
├─ DEPRECATED Announced, timeline posted, migration docs live.
|
||||
│ New consumers blocked. Existing consumers receive warnings.
|
||||
│
|
||||
├─ SUNSET Requests return HTTP 410 Gone + migration pointer.
|
||||
│ 30-day window before routing is removed.
|
||||
│
|
||||
└─ RETIRED Routing removed, docs archived, no traffic accepted.
|
||||
```
|
||||
|
||||
| Stage | Duration | SLA Applies | New Consumers Allowed | Required Action |
|
||||
|-------|----------|-------------|----------------------|-----------------|
|
||||
| Stable | Until superseded | Yes — full | Yes | None |
|
||||
| Deprecated | [12 months / adjust per constraint] | Yes — degraded acceptable | No | Migrate before sunset date |
|
||||
| Sunset | 30-day window | Best-effort only | No | Migrate immediately |
|
||||
| Retired | Permanent | None | No | — |
|
||||
|
||||
**Minimum Stable Period:** A version must remain Stable for at least [6 / 12] months before deprecation can be announced.
|
||||
|
||||
**Maximum Simultaneous Versions:** No more than [2] versions in Stable or Deprecated status at any time. Releasing v3 requires committing to a sunset date for v1 in the same announcement.
|
||||
|
||||
---
|
||||
|
||||
## 3. Breaking vs. Non-Breaking Change Classification
|
||||
|
||||
Apply this table before every API change. If a change is marked Breaking, it requires a new major version. When uncertain, default to Breaking.
|
||||
|
||||
| Change Type | Specific Example | Classification | Rationale |
|
||||
|-------------|-----------------|----------------|-----------|
|
||||
| Remove a response field | Delete `order.legacy_id` from response | **Breaking** | Clients reading this field will null-pointer or fail |
|
||||
| Rename a field | `user_name` → `username` | **Breaking** | Clients referencing old name receive null |
|
||||
| Change field type | `"amount": "10.00"` → `"amount": 10.00` | **Breaking** | Type mismatch at deserialization |
|
||||
| Make optional field required | `email` required in POST body | **Breaking** | Existing callers omitting it receive 400 |
|
||||
| Remove an endpoint | `DELETE /v1/widgets/{id}` removed | **Breaking** | Existing callers receive 404 |
|
||||
| Change HTTP method | `GET /search` → `POST /search` | **Breaking** | Bookmarked or cached GET calls fail |
|
||||
| Change authentication scheme | API key → OAuth2 | **Breaking** | All clients must re-authenticate |
|
||||
| Restructure error response shape | Error JSON schema changed | **Breaking** | Error-handling code misparses responses |
|
||||
| Expand enum values (response) | New `status: "on_hold"` value returned | **Breaking** | Switch statements with no default fall through |
|
||||
| Change pagination defaults | `page_size` default 20 → 50 | **Breaking** | Response length changes unexpectedly |
|
||||
| Tighten input validation | Max length 100 → 50 | **Breaking** | Previously valid inputs now rejected |
|
||||
| Add new optional field to response | Add `order.tax_breakdown` | Non-Breaking | Clients ignore unknown fields per spec |
|
||||
| Add new optional request parameter | Add `?include_archived=true` | Non-Breaking | Ignored by existing clients |
|
||||
| Add a new endpoint | `GET /v1/orders/{id}/audit` | Non-Breaking | No existing client references it |
|
||||
| Relax input validation | Min length 10 → 5 | Non-Breaking | Existing valid inputs remain valid |
|
||||
| Performance or latency improvement | Response time reduced | Non-Breaking | — |
|
||||
| Add new enum value (request-only) | Accept new `type: "express"` | Non-Breaking | Existing values still accepted |
|
||||
|
||||
---
|
||||
|
||||
## 4. Deprecation Process
|
||||
|
||||
### Step-by-Step Deprecation Checklist
|
||||
|
||||
- [ ] **T-0 (Decision day):** Engineering lead approves deprecation. New version confirmed Stable. Sunset date set.
|
||||
- [ ] **T-0:** Update API docs — add deprecation banner to all v[N] endpoint pages.
|
||||
- [ ] **T-0:** Add `Deprecation` and `Sunset` response headers to all v[N] responses (see format below).
|
||||
- [ ] **T-0:** Block new consumer onboarding for v[N] in API gateway and developer portal.
|
||||
- [ ] **T-0:** Send initial deprecation notice to all registered consumers (see Section 5 template).
|
||||
- [ ] **T-0:** Open tracking issue in engineering backlog linking all known consumers to their migration status.
|
||||
- [ ] **T minus 30 days:** Send 30-day warning to all consumers still sending v[N] traffic.
|
||||
- [ ] **T minus 7 days:** Send final warning. If consumer traffic > 100 req/day, escalate directly to their engineering lead.
|
||||
- [ ] **Sunset date:** Switch v[N] routing to return `HTTP 410 Gone` with body pointing to migration guide.
|
||||
- [ ] **T plus 30 days:** Remove routing rules. Archive documentation. Close tracking issue.
|
||||
|
||||
### Deprecation Response Headers
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Deprecation: true
|
||||
Sunset: Sat, 01 Jan 2027 00:00:00 GMT
|
||||
Link: <https://docs.[company].com/api/migration/v1-to-v2>; rel="successor-version"
|
||||
```
|
||||
|
||||
### Sunset Response Body
|
||||
|
||||
```http
|
||||
HTTP/1.1 410 Gone
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Client Communication Templates
|
||||
|
||||
### Initial Deprecation Notice
|
||||
|
||||
```
|
||||
Subject: [Action Required] [Service Name] API v[N] Deprecation — Sunset [Date]
|
||||
|
||||
Hi [Team / Partner Name],
|
||||
|
||||
We are deprecating [Service Name] API v[N], effective [Sunset Date].
|
||||
|
||||
What this means for you:
|
||||
- v[N] continues to work normally until [Sunset Date]
|
||||
- After [Sunset Date], all v[N] requests return HTTP 410 Gone
|
||||
- v[N+1] is available today and fully stable
|
||||
|
||||
Your current usage: approximately [X] requests/day as of [Date].
|
||||
Estimated migration effort: [Small: < 1 day | Medium: 1–3 days | Large: 3–10 days]
|
||||
|
||||
Migration resources:
|
||||
Migration guide: [URL]
|
||||
Changelog: [URL]
|
||||
Office hours: [Date/Time/Link]
|
||||
Support: [Slack channel or email]
|
||||
|
||||
Key dates:
|
||||
[Date] Deprecation announced (today)
|
||||
[Date] New consumer onboarding blocked for v[N]
|
||||
[Date] 30-day warning sent to remaining consumers
|
||||
[Sunset Date] v[N] returns 410 Gone
|
||||
|
||||
Reply to this message or contact us at [channel] with questions.
|
||||
|
||||
[Your Name], [Team Name]
|
||||
```
|
||||
|
||||
### 30-Day Warning
|
||||
|
||||
```
|
||||
Subject: [30 Days Remaining] [Service Name] API v[N] sunsets [Date]
|
||||
|
||||
Hi [Team / Partner Name],
|
||||
|
||||
[Service Name] API v[N] sunsets in 30 days on [Date].
|
||||
|
||||
Your current v[N] traffic: [X] requests/day — migration is not yet complete.
|
||||
|
||||
If you have a technical blocker requiring an extension, contact us before
|
||||
[Date minus 14 days]. Extensions require a documented blocker and a committed
|
||||
migration completion date.
|
||||
|
||||
Migration guide: [URL] | Support: [channel]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Migration Guide Template
|
||||
|
||||
Publish one migration guide per version transition at `docs.[company].com/api/migration/v[N]-to-v[N+1]`.
|
||||
|
||||
```markdown
|
||||
# Migration Guide: v[N] → v[N+1]
|
||||
|
||||
**Estimated effort:** [Small: < 1 day | Medium: 1–3 days | Large: 3–10 days]
|
||||
**Breaking changes in this guide:** [count]
|
||||
|
||||
## Quick Start
|
||||
|
||||
Update your base URL:
|
||||
Before: https://api.[company].com/v[N]/
|
||||
After: https://api.[company].com/v[N+1]/
|
||||
|
||||
## Breaking Changes
|
||||
|
||||
### 1. [Field Rename: user_name → username]
|
||||
|
||||
**Affected endpoints:** `GET /users/{id}`, `POST /users`
|
||||
|
||||
Before (v[N]):
|
||||
{ "user_name": "alice" }
|
||||
|
||||
After (v[N+1]):
|
||||
{ "username": "alice" }
|
||||
|
||||
Migration: Replace all references to `user_name` with `username` in request
|
||||
builders and response parsers.
|
||||
|
||||
### 2. [Next breaking change — repeat structure]
|
||||
|
||||
## New Capabilities in v[N+1]
|
||||
|
||||
| Feature | Description | Docs |
|
||||
|---------|-------------|------|
|
||||
| [Feature name] | [Brief description] | [Link] |
|
||||
|
||||
## SDK Upgrade Reference
|
||||
|
||||
| Language | Package | v[N+1] Version | Install Command |
|
||||
|----------|---------|----------------|-----------------|
|
||||
| Python | `[company]-sdk` | `2.0.0` | `pip install [company]-sdk==2.0.0` |
|
||||
| Node.js | `@[company]/sdk` | `2.0.0` | `npm install @[company]/sdk@2.0.0` |
|
||||
| Go | `github.com/[company]/sdk-go` | `v2.0.0` | `go get github.com/[company]/sdk-go/v2` |
|
||||
| Java | `com.[company]:sdk` | `2.0.0` | Update pom.xml / build.gradle |
|
||||
|
||||
## Migration Validation Checklist
|
||||
|
||||
- [ ] Base URL updated to v[N+1]
|
||||
- [ ] All renamed fields updated in request serializers
|
||||
- [ ] All renamed fields updated in response deserializers
|
||||
- [ ] Error-handling code updated for new error shape
|
||||
- [ ] Integration tests passing against v[N+1] in staging
|
||||
- [ ] Load test completed against v[N+1] — latency within acceptable range
|
||||
- [ ] Rollback plan documented if issues arise post-cutover
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Version-Specific Documentation
|
||||
|
||||
- Maintain separate documentation pages for each Stable and Deprecated version.
|
||||
- Deprecated version docs carry a persistent banner: "This version is deprecated. Sunset date: [Date]. [Migrate to v[N+1]]."
|
||||
- OpenAPI specs, Protobuf definitions, or GraphQL schemas are tagged and archived per version in the repository under `/api/v[N]/`.
|
||||
- A root-level CHANGELOG.md records every breaking and non-breaking change by version — not buried in commit history.
|
||||
|
||||
---
|
||||
|
||||
## 8. SDK Versioning Alignment
|
||||
|
||||
| API Version | SDK Major Version | SDK GA Date | SDK EOL Date |
|
||||
|-------------|------------------|-------------|--------------|
|
||||
| v[1] | 1.x | [Date] | [API Sunset + 90 days] |
|
||||
| v[2] | 2.x | [Date] | Active |
|
||||
|
||||
- SDK major versions align 1:1 with API major versions.
|
||||
- SDK minor versions track non-breaking API additions.
|
||||
- SDK EOL dates trail API sunset dates by 90 days to give consumers extra runway.
|
||||
- SDKs emit a runtime deprecation warning log line when the underlying API version is Deprecated.
|
||||
|
||||
---
|
||||
|
||||
*Strategy authored by [Team Name] — questions to [Slack channel or email]*
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Versioning scheme recommendation includes explicit rationale tied to the API type and consumer type provided — not a generic recommendation
|
||||
- [ ] Breaking-change table covers at minimum: field removal, field rename, type change, making optional field required, endpoint removal, enum expansion, and default value change
|
||||
- [ ] Deprecation timeline durations are filled in with concrete values, not left as abstract placeholders
|
||||
- [ ] All three communication artifacts are present: initial deprecation notice, 30-day warning, and migration guide template
|
||||
- [ ] Sunset response headers (`Deprecation`, `Sunset`, `Link`) use correct RFC date format and real URL structure
|
||||
- [ ] SDK versioning alignment table is present and ties SDK major versions explicitly to API major versions
|
||||
- [ ] Maximum simultaneous supported versions is stated with a concrete number
|
||||
- [ ] Breaking-change table covers at minimum: field removal, field rename, type change, making optional field required, endpoint removal, enum expansion, and default value change
|
||||
- [ ] Deprecation timeline durations are filled in with concrete values, not left as abstract placeholders
|
||||
- [ ] All three communication artifacts are present: initial deprecation notice, 30-day warning, and migration guide template
|
||||
- [ ] Sunset response headers (`Deprecation`, `Sunset`, `Link`) use correct RFC date format and real URL structure
|
||||
- [ ] SDK versioning alignment table is present and ties SDK major versions explicitly to API major versions
|
||||
- [ ] Maximum simultaneous supported versions is stated with a concrete number
|
||||
@@ -0,0 +1,119 @@
|
||||
---
|
||||
name: architecture-decision-record
|
||||
description: "Create an Architecture Decision Record (ADR) for any technical decision. Use when asked to document a technical decision, write an ADR, record an architecture choice, or capture why a technology or approach was selected. Produces a structured ADR with context, decision, consequences, and tradeoffs."
|
||||
---
|
||||
|
||||
# Architecture Decision Record (ADR) Skill
|
||||
|
||||
This skill produces a complete Architecture Decision Record (ADR) following the Nygard format — the most widely adopted standard. ADRs document the reasoning behind significant technical decisions so future team members understand not just *what* was decided, but *why*.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **ADR number** (sequential number in your ADR registry — e.g. 012; or "next available" if unknown)
|
||||
- **Decision title** (brief, e.g. "Use PostgreSQL as primary datastore")
|
||||
- **Context** (what situation led to this decision needing to be made?)
|
||||
- **Options considered** (at least 2; if only 1 is given, prompt for alternatives that were considered or ruled out)
|
||||
- **Decision made** (which option was chosen)
|
||||
- **Reason for choice**
|
||||
- **Status** (Proposed / Accepted / Deprecated / Superseded)
|
||||
- **Author and date**
|
||||
- **Team context** (optional — team size, relevant experience, org constraints; helps calibrate formality and depth of the Context section)
|
||||
|
||||
## Output Format
|
||||
|
||||
---
|
||||
|
||||
# ADR-[NNN]: [Decision Title]
|
||||
|
||||
**Date:** [YYYY-MM-DD]
|
||||
**Status:** [Proposed / Accepted / Deprecated / Superseded by ADR-NNN]
|
||||
**Author(s):** [Name(s)]
|
||||
**Deciders:** [Who had final say — individual or team]
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
[3–6 sentences. Describe the situation, constraints, and forces at play that made this decision necessary. Include: the problem being solved, relevant system state, team constraints, timeline pressures, or non-negotiable requirements. Write as if explaining to someone joining the team 18 months from now who has no prior context.]
|
||||
|
||||
**Key constraints:**
|
||||
- [Constraint 1: e.g. "Must be deployable on-premise for enterprise customers"]
|
||||
- [Constraint 2: e.g. "Team has no prior Go experience"]
|
||||
- [Add as many as are relevant]
|
||||
|
||||
---
|
||||
|
||||
## Options Considered
|
||||
|
||||
For each option, produce:
|
||||
|
||||
### Option [N]: [Name]
|
||||
|
||||
**Description:** [What this option is — 1–3 sentences]
|
||||
|
||||
**Pros:**
|
||||
- [Pro 1]
|
||||
- [Pro 2]
|
||||
|
||||
**Cons:**
|
||||
- [Con 1]
|
||||
- [Con 2]
|
||||
|
||||
**Why this was ruled out (if not chosen):** [Honest reason]
|
||||
|
||||
---
|
||||
|
||||
## Decision
|
||||
|
||||
**We will [chosen option].**
|
||||
|
||||
[2–4 sentences explaining the decision in plain language. This should be readable in isolation — someone should understand the decision from this paragraph alone without reading the full document.]
|
||||
|
||||
---
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive Consequences
|
||||
- [What this decision enables or improves]
|
||||
- [What risk it mitigates]
|
||||
|
||||
### Negative Consequences / Accepted Tradeoffs
|
||||
- [What we're giving up or taking on as a result of this decision]
|
||||
- [Technical debt or limitations introduced]
|
||||
- [What must now be true for this decision to remain valid]
|
||||
|
||||
### Risks
|
||||
- [What could cause this decision to be wrong in hindsight]
|
||||
- [What would trigger us to revisit this decision]
|
||||
|
||||
---
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
[Include if the decision has non-obvious implementation gotchas, or if there are related tickets/RFCs implementers will need. Skip only if the decision is purely tooling selection with no implementation ambiguity.]
|
||||
|
||||
---
|
||||
|
||||
## Review Date
|
||||
|
||||
[Include unless the decision is permanent or self-evidently final. State a specific trigger condition — e.g. "Review if team grows beyond 20 engineers or traffic exceeds 10M requests/day" — not just "should be reviewed periodically".]
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Context explains the *why* — not just the *what*
|
||||
- [ ] At least 2 options are documented (including the rejected ones)
|
||||
- [ ] Rejected options include honest reasons for rejection
|
||||
- [ ] Consequences include *negative* consequences — no decision is consequence-free
|
||||
- [ ] Decision is stated in plain language in the Decision section
|
||||
- [ ] Risks section identifies what would invalidate this decision
|
||||
- [ ] Context section states the problem explicitly in its first 1–2 sentences (does not assume the reader knows what problem the team was solving)
|
||||
- [ ] Each rejected option's "Why ruled out" explanation names a specific constraint or trade-off (not a circular statement like "didn't meet our requirements")
|
||||
|
||||
## Usage Examples
|
||||
- "Write an ADR for using [technology]"
|
||||
- "Document our decision to [architectural choice]"
|
||||
- "Create an architecture decision record for [topic]"
|
||||
- "Help me write up why we chose [option] over [alternative]"
|
||||
@@ -0,0 +1,358 @@
|
||||
---
|
||||
name: capacity-planning
|
||||
description: "Produce a capacity planning document for a service covering traffic forecasts, resource requirements, and scaling strategy. Use when asked to plan infrastructure capacity, forecast resource needs, model traffic growth, define scaling strategy, or produce a capacity review for a service. Produces a structured capacity plan covering current baseline metrics, growth projections, resource requirements per tier, scaling strategy, cost projections, capacity triggers, and an infrastructure action roadmap."
|
||||
---
|
||||
|
||||
# Capacity Planning Skill
|
||||
|
||||
Produce a complete capacity planning document for a service. Capacity planning is not about predicting the future exactly — it is about understanding current headroom, modelling growth, and ensuring the team takes infrastructure action before a constraint becomes an incident.
|
||||
|
||||
A good capacity plan answers: what is running out first, how long before it runs out, what does it cost to fix it, and who decides when to act.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask for these if not already provided:
|
||||
- **Service name and description** — what the service does and who depends on it
|
||||
- **Current traffic and usage metrics** — requests per second (or per day), active users, data volume — whatever units are most natural for this service
|
||||
- **Current resource utilisation** — CPU %, memory %, disk usage, connection pool utilisation, DB query throughput
|
||||
- **Growth rate or projections** — historical growth rate, or known upcoming events (product launch, sales cycle, seasonal peak)
|
||||
- **Tech stack and infrastructure** — cloud provider, compute type (VMs, containers, serverless), database, caching layer, CDN
|
||||
- **Cost constraints** — current infrastructure spend, acceptable cost ceiling, or target cost per unit of traffic
|
||||
|
||||
## Output Format
|
||||
|
||||
---
|
||||
|
||||
# Capacity Plan: [Service Name]
|
||||
|
||||
**Service:** [Name] | **Team:** [Team name]
|
||||
**Author:** [Name] | **Last updated:** [Date]
|
||||
**Planning horizon:** [12 months — [Month Year] to [Month Year]]
|
||||
**Review cadence:** [Quarterly]
|
||||
|
||||
---
|
||||
|
||||
## 1. Executive Summary
|
||||
|
||||
[3–5 sentences covering: current state, the most critical capacity constraint, the timeline before it becomes a risk, the recommended action, and the cost implication. Written for an engineering manager or VP who needs the key facts without reading the full document.]
|
||||
|
||||
**Critical finding:** [e.g. "The database connection pool will reach 90% utilisation within 6 weeks at current growth. Without action, this will cause request queueing and latency spikes under normal traffic."]
|
||||
|
||||
**Recommended immediate action:** [e.g. "Increase connection pool limit and add a read replica within the next 2 weeks."]
|
||||
|
||||
**Estimated cost impact:** [e.g. "Recommended changes add ~$[X]/month to infrastructure spend."]
|
||||
|
||||
---
|
||||
|
||||
## 2. Current Baseline
|
||||
|
||||
*All metrics are 30-day averages unless noted. Date captured: [Date]*
|
||||
|
||||
### Traffic
|
||||
|
||||
| Metric | Value | Peak (7-day) | Notes |
|
||||
|---|---|---|---|
|
||||
| Requests per second (avg) | [X req/s] | [X req/s] | [Peak time / day of week] |
|
||||
| Requests per day | [X M/day] | [X M/day] | — |
|
||||
| Active users (DAU/MAU) | [X] / [X] | — | — |
|
||||
| [Service-specific metric — e.g. jobs processed/hour] | [X] | [X] | — |
|
||||
| [Service-specific metric — e.g. GB ingested/day] | [X GB] | [X GB] | — |
|
||||
|
||||
### Compute
|
||||
|
||||
| Resource | Current utilisation | Instance type | Count | Notes |
|
||||
|---|---|---|---|---|
|
||||
| CPU (avg) | [X%] | [e.g. c5.2xlarge] | [X] | Peak: [X%] |
|
||||
| Memory (avg) | [X%] | — | — | Peak: [X%] |
|
||||
| Network egress | [X Mbps] | — | — | — |
|
||||
| Container / pod count | [X] | [e.g. 2 vCPU / 4 GB] | — | Auto-scaling range: [X–Y] |
|
||||
|
||||
### Database
|
||||
|
||||
| Resource | Current utilisation | Spec | Notes |
|
||||
|---|---|---|---|
|
||||
| CPU | [X%] | [e.g. db.r5.2xlarge] | Peak: [X%] |
|
||||
| Memory | [X%] | [X GB RAM] | — |
|
||||
| Storage used | [X GB] of [Y GB] ([Z%]) | [X GB provisioned] | Growth: [~X GB/month] |
|
||||
| IOPS (avg) | [X] of [Y provisioned] | [Y IOPS] | Peak: [X IOPS] |
|
||||
| Connection pool | [X] of [Y max] ([Z%]) | Max connections: [Y] | [ORM pool size: X] |
|
||||
| Query P99 latency | [X ms] | — | [Slowest query: X] |
|
||||
| Read/write ratio | [X%] reads / [Y%] writes | — | — |
|
||||
|
||||
### Cache
|
||||
|
||||
| Resource | Current utilisation | Spec | Notes |
|
||||
|---|---|---|---|
|
||||
| Memory used | [X GB] of [Y GB] ([Z%]) | [e.g. cache.r6g.large] | Eviction rate: [X%] |
|
||||
| Hit rate | [X%] | — | Miss rate: [Y%] |
|
||||
| Connections | [X] | Max: [Y] | — |
|
||||
|
||||
### Storage / Object Store
|
||||
|
||||
| Resource | Current usage | Growth rate | Notes |
|
||||
|---|---|---|---|
|
||||
| [S3 / GCS / Blob] | [X GB / TB] | [~X GB/month] | [Lifecycle policies in place? Y/N] |
|
||||
| Disk (if applicable) | [X GB] of [Y GB] | [~X GB/month] | [RAID / EBS type] |
|
||||
|
||||
### Cost Baseline
|
||||
|
||||
| Component | Current monthly cost | % of total |
|
||||
|---|---|---|
|
||||
| Compute (app servers) | $[X] | [X%] |
|
||||
| Database | $[X] | [X%] |
|
||||
| Cache | $[X] | [X%] |
|
||||
| Storage | $[X] | [X%] |
|
||||
| CDN / bandwidth | $[X] | [X%] |
|
||||
| Other ([describe]) | $[X] | [X%] |
|
||||
| **Total** | **$[X]** | 100% |
|
||||
|
||||
**Unit economics:** $[X] per [1,000 requests / 1,000 users / GB processed]
|
||||
|
||||
---
|
||||
|
||||
## 3. Growth Projections
|
||||
|
||||
### Assumptions
|
||||
|
||||
| Assumption | Value | Source | Confidence |
|
||||
|---|---|---|---|
|
||||
| Monthly traffic growth rate | [X%] | [Historical trend / product forecast] | [High / Medium / Low] |
|
||||
| Seasonal peak factor | [+X% in [month(s)]] | [Last year's data / expected launch] | [High / Medium] |
|
||||
| Upcoming events | [e.g. Marketing campaign — [Month], expected +[X]% traffic spike] | [Marketing plan] | [Medium] |
|
||||
| User growth | [X new users/month] | [Sales pipeline / growth model] | [Medium] |
|
||||
| Data growth | [X GB/month] | [Current trend] | [High] |
|
||||
|
||||
### Traffic Forecast
|
||||
|
||||
| Timeframe | Req/s (avg) | Req/s (peak) | DAU | Data volume (cumulative) |
|
||||
|---|---|---|---|---|
|
||||
| **Now** (baseline) | [X] | [X] | [X] | [X GB/TB] |
|
||||
| **+3 months** | [X] | [X] | [X] | [X GB/TB] |
|
||||
| **+6 months** | [X] | [X] | [X] | [X GB/TB] |
|
||||
| **+12 months** | [X] | [X] | [X] | [X GB/TB] |
|
||||
|
||||
*Growth formula: [Baseline] × (1 + [monthly rate])^[months] + seasonal adjustment*
|
||||
|
||||
### Capacity Headroom Analysis
|
||||
|
||||
**When does each resource run out at current utilisation and projected growth?**
|
||||
|
||||
| Resource | Current utilisation | Safe ceiling | Headroom remaining | Months to ceiling |
|
||||
|---|---|---|---|---|
|
||||
| App CPU | [X%] | 70% | [X%] | [X months] |
|
||||
| App memory | [X%] | 80% | [X%] | [X months] |
|
||||
| DB CPU | [X%] | 70% | [X%] | [X months] |
|
||||
| DB storage | [X GB] of [Y GB] | 80% = [Z GB] | [X GB] | [X months] |
|
||||
| DB IOPS | [X] of [Y] | 80% = [Z] | [X IOPS] | [X months] |
|
||||
| DB connections | [X] of [Y] | 80% = [Z] | [X] | [X months] |
|
||||
| Cache memory | [X GB] of [Y GB] | 75% = [Z GB] | [X GB] | [X months] |
|
||||
| Storage (object) | [X TB] | No hard limit — cost trigger | — | [Cost trigger: $X/month] |
|
||||
|
||||
**Red flags** (resources hitting ceiling within 3 months):
|
||||
- [Resource]: [current]% → ceiling in [X weeks] — **Action required**
|
||||
- [Resource]: [current]% → ceiling in [X weeks] — **Action required**
|
||||
|
||||
---
|
||||
|
||||
## 4. Resource Requirements
|
||||
|
||||
### Compute Requirements
|
||||
|
||||
| Timeframe | Required instances | Recommended instance type | Auto-scaling range | Notes |
|
||||
|---|---|---|---|---|
|
||||
| Now | [X] | [type] | [min: X, max: Y] | Current configuration |
|
||||
| +3 months | [X] | [type] | [min: X, max: Y] | [Any instance type change needed?] |
|
||||
| +6 months | [X] | [type or upgrade] | [min: X, max: Y] | [Consider [larger type / horizontal scale]] |
|
||||
| +12 months | [X] | [type or upgrade] | [min: X, max: Y] | [State of horizontal vs vertical decision] |
|
||||
|
||||
**Memory headroom target:** Maintain ≥30% available memory at average load; ≥20% at peak.
|
||||
**CPU headroom target:** Maintain ≥30% available CPU at average load; ≥15% at peak.
|
||||
|
||||
### Database Requirements
|
||||
|
||||
| Timeframe | Instance type | Storage | IOPS | Read replica | Notes |
|
||||
|---|---|---|---|---|---|
|
||||
| Now | [type] | [X GB] | [X] | [Y/N] | Current |
|
||||
| +3 months | [type] | [X GB] | [X] | [Y/N] | [Upgrade storage / IOPS] |
|
||||
| +6 months | [type or upgrade] | [X GB] | [X] | **Yes** | [Read replica recommended by this point] |
|
||||
| +12 months | [type] | [X GB] | [X] | [X replicas] | [Consider sharding / partitioning at this scale] |
|
||||
|
||||
**Storage growth management:**
|
||||
- Current growth: [~X GB/month]
|
||||
- Storage auto-scaling: [Enabled / Not enabled — enable by [date]]
|
||||
- Archiving policy: [Records older than X months moved to [cold storage / archive tier]]
|
||||
|
||||
### Cache Requirements
|
||||
|
||||
| Timeframe | Node type | Nodes | Memory | Notes |
|
||||
|---|---|---|---|---|
|
||||
| Now | [type] | [X] | [X GB] | Current |
|
||||
| +6 months | [type] | [X] | [X GB] | [Scale out or upgrade] |
|
||||
| +12 months | [type] | [X] | [X GB] | [Cluster mode if >Y GB required] |
|
||||
|
||||
---
|
||||
|
||||
## 5. Scaling Strategy
|
||||
|
||||
### Compute — Horizontal Scaling
|
||||
|
||||
**Decision: [Horizontal / Vertical / Both]**
|
||||
|
||||
[State the scaling strategy and the reasoning. E.g. "The application is stateless and CPU-bound; horizontal scaling is preferred. Vertical scaling is a short-term fallback only."]
|
||||
|
||||
**Auto-scaling configuration:**
|
||||
|
||||
```
|
||||
Scale-out trigger: CPU > [X%] for [Y minutes] OR memory > [X%] for [Y minutes]
|
||||
Scale-in trigger: CPU < [X%] for [Y minutes] AND memory < [X%] for [Y minutes]
|
||||
Min instances: [X] (ensures HA across [X] AZs)
|
||||
Max instances: [Y] (cost ceiling)
|
||||
Cooldown period: [X seconds]
|
||||
Warmup time: [X seconds] (time for new instance to be healthy)
|
||||
```
|
||||
|
||||
**Limits of horizontal scaling:**
|
||||
- [e.g. Database connection pool is the current bottleneck — adding more app instances without increasing DB connections will not help]
|
||||
- [e.g. Session affinity required for WebSocket connections — limits pure stateless scaling]
|
||||
|
||||
### Database — Read Scaling
|
||||
|
||||
**Strategy:** [Read replica / Connection pooling via PgBouncer / Query caching / None needed yet]
|
||||
|
||||
**When to add a read replica:**
|
||||
- DB CPU sustained >60% for >30 minutes, OR
|
||||
- Read query P95 latency >50ms, OR
|
||||
- Connection pool utilisation >70%
|
||||
|
||||
**Connection pooling:**
|
||||
- Pooler: [PgBouncer / RDS Proxy / application-level / not configured]
|
||||
- Pool size: [X connections per app instance × Y instances = Z total]
|
||||
- Max DB connections: [configured to Z + 20% headroom]
|
||||
|
||||
### Caching Strategy
|
||||
|
||||
**Cache policy:** [Cache-aside / Write-through / Write-behind]
|
||||
**TTL strategy:**
|
||||
|
||||
| Data type | TTL | Invalidation method |
|
||||
|---|---|---|
|
||||
| [e.g. User profile] | [5 minutes] | [Explicit invalidation on update] |
|
||||
| [e.g. Product catalog] | [1 hour] | [TTL expiry — eventual consistency acceptable] |
|
||||
| [e.g. Session data] | [24 hours] | [Explicit invalidation on logout] |
|
||||
|
||||
**Cache miss handling:** [Describe what happens on a cache miss — does it fall through gracefully or cause a thundering herd risk?]
|
||||
|
||||
---
|
||||
|
||||
## 6. Cost Projections
|
||||
|
||||
### Infrastructure Cost Forecast
|
||||
|
||||
| Component | Now (monthly) | +3 months | +6 months | +12 months |
|
||||
|---|---|---|---|---|
|
||||
| Compute | $[X] | $[X] | $[X] | $[X] |
|
||||
| Database | $[X] | $[X] | $[X] | $[X] |
|
||||
| Cache | $[X] | $[X] | $[X] | $[X] |
|
||||
| Storage | $[X] | $[X] | $[X] | $[X] |
|
||||
| CDN / bandwidth | $[X] | $[X] | $[X] | $[X] |
|
||||
| **Total** | **$[X]** | **$[X]** | **$[X]** | **$[X]** |
|
||||
| MoM growth % | — | [X%] | [X%] | [X%] |
|
||||
|
||||
**Unit economics trend:**
|
||||
|
||||
| Timeframe | Cost per 1k requests | Cost per user/month | Notes |
|
||||
|---|---|---|---|
|
||||
| Now | $[X] | $[X] | Baseline |
|
||||
| +6 months | $[X] | $[X] | [Improving / worsening — why] |
|
||||
| +12 months | $[X] | $[X] | [Target: $X per 1k requests] |
|
||||
|
||||
**Cost optimisation opportunities:**
|
||||
|
||||
| Opportunity | Estimated saving | Effort | Timeline |
|
||||
|---|---|---|---|
|
||||
| [e.g. Reserved instances for baseline compute] | $[X/month] | Low | Immediate |
|
||||
| [e.g. S3 lifecycle policy — move objects >90 days to Glacier] | $[X/month] | Low | This sprint |
|
||||
| [e.g. Right-size [instance] — current is overprovisioned] | $[X/month] | Low | This sprint |
|
||||
| [e.g. Optimise top-5 slow queries — reduce DB compute need] | $[X/month] | Medium | Next quarter |
|
||||
|
||||
---
|
||||
|
||||
## 7. Capacity Triggers and Actions
|
||||
|
||||
Define the thresholds that require explicit action — not retrospective fixes after an incident.
|
||||
|
||||
| Resource | Watch (amber) | Act (red — schedule work) | Emergency (incident risk) |
|
||||
|---|---|---|---|
|
||||
| App CPU (sustained avg) | >60% | >70% | >85% |
|
||||
| App memory | >70% | >80% | >90% |
|
||||
| DB CPU | >55% | >65% | >80% |
|
||||
| DB storage | >65% | >75% | >85% |
|
||||
| DB connections | >60% | >70% | >85% |
|
||||
| Cache memory / eviction | Hit rate <90% | Hit rate <85% | Hit rate <75% |
|
||||
| Error rate | >0.5% | >1% | >2% |
|
||||
| P99 latency | >2× baseline | >3× baseline | >5× baseline |
|
||||
|
||||
**When a Watch threshold is crossed:**
|
||||
- Engineer who observes it creates a ticket with capacity label
|
||||
- Ticket reviewed in next sprint planning
|
||||
|
||||
**When an Act threshold is crossed:**
|
||||
- On-call engineer creates a ticket marked P2
|
||||
- Tech lead reviews within 24 hours
|
||||
- Action plan documented and scheduled within 1 sprint
|
||||
|
||||
**When an Emergency threshold is crossed:**
|
||||
- Treat as a potential incident — page on-call
|
||||
- Emergency scaling actions taken immediately (see runbook)
|
||||
- Root cause investigation starts within 2 hours
|
||||
|
||||
**Emergency scaling runbook:** [Link to oncall-runbook for capacity incidents]
|
||||
|
||||
---
|
||||
|
||||
## 8. Infrastructure Action Roadmap
|
||||
|
||||
### Immediate Actions (next 2 weeks)
|
||||
|
||||
| Action | Owner | Effort | Justification |
|
||||
|---|---|---|---|
|
||||
| [e.g. Increase DB connection pool limit to X] | [Name] | [2 hours] | [DB connections at X% — hitting ceiling in X weeks] |
|
||||
| [e.g. Enable storage auto-scaling on RDS] | [Name] | [30 min] | [Storage at X% — prevents emergency at X months] |
|
||||
| [e.g. Add S3 lifecycle policy for [bucket]] | [Name] | [1 hour] | [Storage growing at $X/month unnecessarily] |
|
||||
|
||||
### This Quarter (within 3 months)
|
||||
|
||||
| Action | Owner | Effort | Justification |
|
||||
|---|---|---|---|
|
||||
| [e.g. Add read replica to production DB] | [Name] | [1 day] | [DB CPU projected to hit 65% in 2 months] |
|
||||
| [e.g. Increase max auto-scaling limit from X to Y] | [Name] | [2 hours] | [Current max is too close to expected peak] |
|
||||
| [e.g. Configure PgBouncer for connection pooling] | [Name] | [3 days] | [Reduce per-connection overhead; headroom for growth] |
|
||||
|
||||
### Next Quarter (3–6 months)
|
||||
|
||||
| Action | Owner | Effort | Justification |
|
||||
|---|---|---|---|
|
||||
| [e.g. Upgrade DB instance class — [current] → [next]] | [Name] | [2 hours — blue/green] | [DB CPU projected to hit 70% by Q[X]] |
|
||||
| [e.g. Implement caching for [high-read endpoint]] | [Name] | [1 week] | [Reduce DB read load by estimated [X%]] |
|
||||
| [e.g. Evaluate horizontal DB sharding] | [Name] | [2 weeks (spike)] | [At 12-month projections, single DB hits limits] |
|
||||
|
||||
### Horizon (6–12 months)
|
||||
|
||||
| Action | Description | Trigger condition |
|
||||
|---|---|---|
|
||||
| [e.g. Multi-region deployment] | [Active-passive setup in eu-west-2] | [DAU exceeds X or SLA requires 99.99%] |
|
||||
| [e.g. Database sharding or migration to distributed DB] | [Evaluate CockroachDB / Vitess] | [Single-node DB projected to hit ceiling] |
|
||||
| [e.g. CDN expansion] | [Add PoPs in [region]] | [Latency SLO breached for [geography]] |
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Every resource has a quantified current utilisation and a projected months-to-ceiling — no hand-waving
|
||||
- [ ] The most critical constraint is called out in the executive summary with a specific timeline
|
||||
- [ ] Growth projections state their assumptions and confidence level — not presented as certainties
|
||||
- [ ] Capacity triggers define amber/red thresholds and name who acts at each level
|
||||
- [ ] Cost projections include unit economics, not just absolute totals
|
||||
- [ ] The infrastructure roadmap has named owners and effort estimates — not just a wish list
|
||||
- [ ] Auto-scaling configuration includes both scale-out AND scale-in triggers, and a min/max range
|
||||
- [ ] Actions are ordered by urgency — immediate items are genuinely immediate, not backlog filler
|
||||
@@ -0,0 +1,89 @@
|
||||
---
|
||||
name: changelog-generator
|
||||
description: "Convert a git log, commit list, or release notes into a polished, user-facing changelog. Use when writing release notes, generating a CHANGELOG.md entry, or documenting what changed in a version. Produces a structured changelog section with version header, categorised changes, and migration notes."
|
||||
---
|
||||
|
||||
# Changelog Generator Skill
|
||||
|
||||
Converts raw git commits, a diff summary, or developer release notes into a polished changelog entry — categorised, user-facing, and following Keep a Changelog conventions.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask for these if not provided:
|
||||
- **Commits or release notes** (paste `git log --oneline`, raw commit messages, or a description of what changed)
|
||||
- **Version number** (e.g. 2.4.0, v1.0.0-beta.2)
|
||||
- **Release date** (or "today")
|
||||
- **Audience** (developers using an API / end users of a product / internal team — affects language)
|
||||
- **Any breaking changes** (flag these explicitly if known)
|
||||
- **Previous version behaviour** (optional — paste the previous changelog entry or describe what is changing; needed for accurate "Changed" entries)
|
||||
- **Scope** (whole product / specific package or module — e.g. "payments SDK only", "iOS app", "all services")
|
||||
|
||||
## Output Format
|
||||
|
||||
Follow [Keep a Changelog](https://keepachangelog.com) format:
|
||||
|
||||
---
|
||||
|
||||
## [X.Y.Z] — YYYY-MM-DD
|
||||
|
||||
### Breaking Changes ⚠️
|
||||
[Only include if there are breaking changes]
|
||||
- **[Breaking change]:** [What changed and what it breaks]
|
||||
- **Migration required:** [Specific action the user must take]
|
||||
|
||||
### Added
|
||||
- [New feature or capability, written from the user's perspective]
|
||||
- [Another addition]
|
||||
|
||||
### Changed
|
||||
- [Changed behaviour — what it did before vs. what it does now]
|
||||
- [Performance improvement with measurable impact if known]
|
||||
|
||||
### Fixed
|
||||
- [Bug fixed — describe what was broken, not the fix implementation]
|
||||
- [Another fix]
|
||||
|
||||
### Deprecated
|
||||
- [Deprecated thing] — use [replacement] instead. Will be removed in [version].
|
||||
|
||||
### Removed
|
||||
- [Removed thing] — was deprecated in [version]
|
||||
|
||||
### Security
|
||||
- [Security fix — describe the vulnerability class, not exploit details]
|
||||
|
||||
---
|
||||
|
||||
---
|
||||
|
||||
> **Skill guidance — do not include the following section in the delivered changelog:**
|
||||
|
||||
## Formatting Rules Applied
|
||||
|
||||
**Language:** Write for the reader, not the committer. "Add dark mode support" not "implement ThemeProvider with dark palette variant".
|
||||
|
||||
**Breaking changes:** Always call these out first with ⚠️. Include a migration path.
|
||||
|
||||
**Bug fixes:** Describe what was broken, not what was changed. "Fix crash when user has no profile picture" not "null-check avatar URL before rendering".
|
||||
|
||||
**Granularity:** Group related commits into one line. Don't list every micro-commit separately.
|
||||
|
||||
**Tone:** Active voice, imperative mood. "Add", "Fix", "Remove" — not "Added", "Fixed", "Removed".
|
||||
|
||||
**Empty sections:** Omit any section with no entries. Don't include empty `### Fixed` blocks.
|
||||
|
||||
## Quality Checks
|
||||
- [ ] Breaking changes are at the top with migration instructions
|
||||
- [ ] All entries are user-facing language (no internal variable names or implementation details)
|
||||
- [ ] Related commits are grouped into single entries (not listed individually)
|
||||
- [ ] Version and date header is correct
|
||||
- [ ] Empty sections are omitted
|
||||
- [ ] No entries start with past-tense verbs (no "Added", "Fixed", "Removed" — use "Add", "Fix", "Remove")
|
||||
- [ ] Every breaking change entry includes a specific migration action (not just "update your code")
|
||||
|
||||
## Usage Examples
|
||||
- "Write a changelog for version [X]" + [paste commits]
|
||||
- "Generate release notes from these commits"
|
||||
- "Turn this git log into a CHANGELOG entry"
|
||||
- "Write the CHANGELOG.md update for this release"
|
||||
- "What changed in this release?" + [paste commit list]
|
||||
@@ -0,0 +1,301 @@
|
||||
---
|
||||
name: cicd-playbook
|
||||
description: "Write a CI/CD pipeline playbook for a service or team. Use when asked to document a CI/CD pipeline, write a deployment process, define release gates, document build and test stages, or create a deployment guide. Produces a structured playbook covering pipeline stages, environment definitions, deployment gates, rollback procedures, and on-call responsibilities."
|
||||
---
|
||||
|
||||
# CI/CD Playbook Skill
|
||||
|
||||
Produce a complete, actionable CI/CD playbook for a service or team — covering everything a new engineer needs to understand, contribute to, and operate the pipeline safely.
|
||||
|
||||
A good playbook is not a diagram. It is a document that answers: what runs, when, why, who owns it, and what to do when it breaks.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask for these if not already provided:
|
||||
- **Service name** and brief description
|
||||
- **Tech stack** — language, framework, containerisation (Docker, etc.)
|
||||
- **Source control** — GitHub / GitLab / Bitbucket, branching strategy
|
||||
- **CI platform** — GitHub Actions / CircleCI / Jenkins / BuildKite / other
|
||||
- **CD platform / deployment target** — Kubernetes, ECS, Lambda, Heroku, VMs, etc.
|
||||
- **Environments** — e.g. dev, staging, production (and any canary / feature environments)
|
||||
- **Deployment frequency** — how often does the team ship?
|
||||
- **Any existing gates** — manual approvals, smoke tests, feature flags
|
||||
- **On-call setup** — who's responsible during deploys?
|
||||
|
||||
## Output Format
|
||||
|
||||
---
|
||||
|
||||
# CI/CD Playbook: [Service Name]
|
||||
|
||||
**Service:** [Name] | **Team:** [Team name]
|
||||
**Last updated:** [Date] | **Owner:** [Name / role]
|
||||
**Pipeline platform:** [CI tool] → [CD tool / platform]
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
[2–3 sentences describing what this service does and why the CI/CD pipeline is structured the way it is. Include the deployment target and how frequently the team ships.]
|
||||
|
||||
**Deployment frequency:** [Multiple times per day / Daily / Weekly / On-demand]
|
||||
**Average pipeline duration:** [X minutes]
|
||||
**Rollback time (p95):** [X minutes]
|
||||
|
||||
---
|
||||
|
||||
## Pipeline Stages
|
||||
|
||||
```
|
||||
[Branch push]
|
||||
│
|
||||
▼
|
||||
[1. Build & Lint] ──fail──▶ ❌ Block PR
|
||||
│
|
||||
▼
|
||||
[2. Unit Tests] ──fail──▶ ❌ Block PR
|
||||
│
|
||||
▼
|
||||
[3. Integration Tests] ──fail──▶ ❌ Block PR
|
||||
│
|
||||
▼
|
||||
[4. Security Scan] ──fail──▶ ⚠️ [Block / Warn — specify]
|
||||
│
|
||||
▼
|
||||
[5. Build Artefact / Container Image]
|
||||
│
|
||||
▼
|
||||
[6. Deploy to Staging] ──fail──▶ ❌ Block promotion
|
||||
│
|
||||
▼
|
||||
[7. Smoke Tests (Staging)]
|
||||
│
|
||||
▼
|
||||
[8. Manual Approval Gate] ──(if required)
|
||||
│
|
||||
▼
|
||||
[9. Deploy to Production] ──fail──▶ 🔁 Auto-rollback (if configured)
|
||||
│
|
||||
▼
|
||||
[10. Post-deploy checks]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Stage Definitions
|
||||
|
||||
### Stage 1 — Build & Lint
|
||||
|
||||
**What runs:** [Build command] + [Linter — e.g. ESLint, golangci-lint, flake8]
|
||||
**Trigger:** Every commit to any branch
|
||||
**Blocking:** Yes — PR cannot be merged if this fails
|
||||
**Typical duration:** [X minutes]
|
||||
**Owner if it fails:** PR author
|
||||
|
||||
**Common failure causes:**
|
||||
- [e.g. Missing dependency — run `npm install` locally before pushing]
|
||||
- [e.g. Lint rule violation — run `npm run lint --fix` to auto-fix most issues]
|
||||
|
||||
---
|
||||
|
||||
### Stage 2 — Unit Tests
|
||||
|
||||
**What runs:** [Test command — e.g. `npm test`, `go test ./...`, `pytest`]
|
||||
**Coverage gate:** [X]% minimum — pipeline fails below this threshold
|
||||
**Trigger:** Every commit
|
||||
**Blocking:** Yes
|
||||
**Typical duration:** [X minutes]
|
||||
|
||||
**Coverage report:** [Where to find it — e.g. uploaded to Codecov, available in CI artifacts]
|
||||
|
||||
---
|
||||
|
||||
### Stage 3 — Integration Tests
|
||||
|
||||
**What runs:** [Test suite description — e.g. "API integration tests against a test database using Docker Compose"]
|
||||
**Environment:** [Ephemeral test environment / shared test DB / etc.]
|
||||
**Trigger:** Every commit to `main` and feature branches targeting `main`
|
||||
**Blocking:** Yes
|
||||
**Typical duration:** [X minutes]
|
||||
|
||||
**If slow:** [e.g. "Integration tests can be skipped locally with `SKIP_INTEGRATION=true` — never skip in CI"]
|
||||
|
||||
---
|
||||
|
||||
### Stage 4 — Security Scan
|
||||
|
||||
**Tools:** [e.g. Snyk, Trivy, OWASP Dependency Check, Semgrep]
|
||||
**What it checks:** [Dependency vulnerabilities / SAST / secrets detection — list what applies]
|
||||
**Blocking on:** Critical and High severity findings
|
||||
**Non-blocking on:** Medium and Low (flagged, not blocking)
|
||||
**Trigger:** Every commit to `main`
|
||||
|
||||
**How to handle a flagged vulnerability:**
|
||||
1. Check if a fix is available — upgrade the dependency
|
||||
2. If no fix available, open a security ticket and add a suppression with justification
|
||||
3. Never suppress without a ticket and owner
|
||||
|
||||
---
|
||||
|
||||
### Stage 5 — Build Artefact
|
||||
|
||||
**What is produced:** [Docker image / binary / zip — be specific]
|
||||
**Registry:** [ECR / GCR / Docker Hub / Artifactory — URL]
|
||||
**Tagging convention:** `[service-name]:[git-sha]` (also tagged `:latest` on `main`)
|
||||
**Trigger:** Commits to `main` only (not feature branches)
|
||||
|
||||
---
|
||||
|
||||
### Stage 6 — Deploy to Staging
|
||||
|
||||
**Deployment method:** [e.g. Helm upgrade / kubectl apply / ecs deploy / Terraform apply]
|
||||
**Staging URL:** [URL]
|
||||
**Trigger:** Automatic on successful artefact build from `main`
|
||||
**Who can deploy to staging:** Any engineer (automatic)
|
||||
|
||||
**Environment variables:** Managed in [Vault / AWS SSM / GitHub Secrets / etc.]
|
||||
**Staging is not production:** [Any differences in config, scale, or data — state them here]
|
||||
|
||||
---
|
||||
|
||||
### Stage 7 — Smoke Tests (Staging)
|
||||
|
||||
**What runs:** [Description — e.g. "10 critical path tests covering login, core API endpoints, and payment flow"]
|
||||
**Tool:** [e.g. Playwright / Postman / custom script]
|
||||
**Pass criteria:** All smoke tests pass within [X seconds] timeout
|
||||
**Blocking:** Yes — production deploy will not proceed if smoke tests fail
|
||||
|
||||
**Smoke test suite location:** [Link to test files or folder]
|
||||
|
||||
---
|
||||
|
||||
### Stage 8 — Manual Approval Gate
|
||||
|
||||
**Required for:** [Production deploys / deploys affecting >X% of traffic / deploys to specific regions]
|
||||
**Who can approve:** [e.g. Any engineer on the team / Lead engineer / On-call engineer]
|
||||
**Approval timeout:** [e.g. 24 hours — auto-cancelled if no approval]
|
||||
**How to approve:** [GitHub Actions approve step / Slack command / other — with link]
|
||||
|
||||
**When to withhold approval:**
|
||||
- Active incident in production
|
||||
- Deploy is outside the deployment window (see below)
|
||||
- On-call engineer has not been notified
|
||||
|
||||
---
|
||||
|
||||
### Stage 9 — Deploy to Production
|
||||
|
||||
**Deployment method:** [Same as staging or different — specify]
|
||||
**Deployment window:** [e.g. Monday–Thursday 09:00–16:00 UTC — no deploys on Fridays or before bank holidays]
|
||||
**Canary / progressive rollout:** [Yes — X% initial traffic, full rollout after Y minutes / No — full deploy]
|
||||
**Deployment notifications:** [Slack channel — #deployments]
|
||||
|
||||
**Who is on-call during deploy:** Deploying engineer is responsible until post-deploy checks pass.
|
||||
|
||||
---
|
||||
|
||||
### Stage 10 — Post-Deploy Checks
|
||||
|
||||
**Automated checks (run for [X minutes] after deploy):**
|
||||
- [ ] Error rate: <[X]% (baseline: [Y]%)
|
||||
- [ ] P99 latency: <[X]ms (baseline: [Y]ms)
|
||||
- [ ] [Key business metric]: within [X]% of baseline
|
||||
|
||||
**Where to watch:** [Datadog / Grafana / CloudWatch dashboard — link]
|
||||
|
||||
**If a check fails:** See Rollback Procedure below.
|
||||
|
||||
---
|
||||
|
||||
## Environments
|
||||
|
||||
| Environment | Purpose | Deploy trigger | URL | Data |
|
||||
|---|---|---|---|---|
|
||||
| **Dev** | Local development | Manual | localhost | Seeded test data |
|
||||
| **Staging** | Pre-production validation | Automatic (main) | [URL] | Anonymised prod copy |
|
||||
| **Production** | Live traffic | Manual approval | [URL] | Live data |
|
||||
|
||||
---
|
||||
|
||||
## Branching Strategy
|
||||
|
||||
**Model:** [Trunk-based / GitFlow / GitHub Flow — describe briefly]
|
||||
|
||||
| Branch | Purpose | Who merges | Deploy target |
|
||||
|---|---|---|---|
|
||||
| `main` | Production-ready code | PR + review | Staging → Production |
|
||||
| `feature/*` | Feature development | Author | None (CI only) |
|
||||
| `hotfix/*` | Critical production fixes | Lead engineer | Can bypass staging gate with approval |
|
||||
|
||||
**Hotfix process:** [Describe when and how to use a hotfix branch — what level of incident justifies bypassing the standard process]
|
||||
|
||||
---
|
||||
|
||||
## Rollback Procedure
|
||||
|
||||
**Automated rollback:** [Yes — triggered if post-deploy error rate exceeds [X]% / No — manual only]
|
||||
|
||||
**Manual rollback steps:**
|
||||
```bash
|
||||
# 1. Identify the last known good image tag
|
||||
[command to list recent deployments]
|
||||
|
||||
# 2. Deploy the previous version
|
||||
[deployment command with previous tag]
|
||||
|
||||
# 3. Confirm rollback is live
|
||||
[smoke test command or health check URL]
|
||||
|
||||
# 4. Notify the team
|
||||
[Slack command or template]
|
||||
```
|
||||
|
||||
**Rollback decision authority:** Any engineer on-call can initiate a rollback without waiting for approval.
|
||||
|
||||
**After a rollback:**
|
||||
1. Create a post-deploy incident report (see [incident-postmortem skill])
|
||||
2. Do not re-deploy the same commit without fixing the root cause
|
||||
3. Notify [stakeholder / support team] of the rollback and expected fix timeline
|
||||
|
||||
---
|
||||
|
||||
## Secrets and Configuration Management
|
||||
|
||||
**Secret store:** [Vault / AWS SSM / GitHub Secrets / Doppler — specify]
|
||||
**How to add a new secret:**
|
||||
1. [Step 1]
|
||||
2. [Step 2]
|
||||
**Who has access:** [Role or team]
|
||||
**Rotation policy:** [How often secrets are rotated and who owns it]
|
||||
|
||||
**Never do:** Commit secrets to source control, even in `.env` files. The pipeline includes secret scanning (Stage 4) which will flag this.
|
||||
|
||||
---
|
||||
|
||||
## Common Failures and Fixes
|
||||
|
||||
| Failure | Likely cause | Fix |
|
||||
|---|---|---|
|
||||
| Build fails with "module not found" | Dependency not installed | Run `[install command]` and commit `lock file` |
|
||||
| Integration tests timeout | Test DB not seeded / external service down | Check [service] status; re-run pipeline |
|
||||
| Smoke tests fail after staging deploy | Environment variable missing | Check [config location]; compare staging and prod env vars |
|
||||
| Production deploy stuck at approval | Approver not notified | Tag `@[on-call handle]` in `#deployments` |
|
||||
| Post-deploy error rate spike | Bad deploy / upstream dependency | Check [dashboard]; initiate rollback if >5 min |
|
||||
|
||||
---
|
||||
|
||||
## On-Call Responsibilities During Deploy
|
||||
|
||||
- The deploying engineer is responsible for monitoring post-deploy checks for [X minutes] after a production deploy
|
||||
- If you cannot monitor after deploying, hand off explicitly to another engineer in `#deployments`
|
||||
- For deploys outside business hours: only hotfixes — always page the on-call engineer before deploying
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Every stage has a clear owner when it fails
|
||||
- [ ] Rollback procedure is tested — not theoretical
|
||||
- [ ] Secrets management section names the actual tool used (not "use secrets management")
|
||||
- [ ] Deployment window is specific — not "during business hours"
|
||||
- [ ] Post-deploy check thresholds are calibrated to actual baseline metrics
|
||||
@@ -0,0 +1,114 @@
|
||||
---
|
||||
name: code-review-checklist
|
||||
description: "Generate a tailored code review checklist for any pull request based on the language, type of change, and risk level. Use when asked to review code, check a PR, review a pull request, or generate a code review checklist. Produces a focused checklist with language-specific checks, risk-level-appropriate depth, and a clear approve/request-changes recommendation."
|
||||
---
|
||||
|
||||
# Code Review Checklist Skill
|
||||
|
||||
Produces a tailored code review checklist for a specific pull request — scaled to the language, type of change, and risk level. Not a generic template.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Language and framework** (e.g. TypeScript + React / Python + FastAPI / Go)
|
||||
- **Type of change** (feature / bug fix / refactor / dependency upgrade / security patch / performance)
|
||||
- **Risk level** (low / medium / high / critical)
|
||||
- **PR description** (paste the description or link to the PR)
|
||||
- **Code or diff** (optional — paste key changed files or a `git diff`; significantly improves checklist specificity)
|
||||
- **Author context** (new starter / experienced / external contributor)
|
||||
|
||||
## Output Format
|
||||
|
||||
---
|
||||
|
||||
# Code Review: [PR Title or Reference]
|
||||
|
||||
### 1. PR Overview
|
||||
**Scope assessment:** [Small / Medium / Large / Too large — should be split]
|
||||
**Recommended review depth:** [Skim / Standard / Deep dive]
|
||||
**Estimated review time:** [e.g. 20–30 min — use 5 min per 50 lines of diff as a rough guide]
|
||||
|
||||
### 2. Correctness Checks
|
||||
|
||||
Language-specific correctness checks — choose based on the language stated:
|
||||
|
||||
**For TypeScript/JavaScript:**
|
||||
- Type definitions match actual usage
|
||||
- No implicit `any` in non-test code
|
||||
- Async/await used consistently; no unhandled promises
|
||||
- Null/undefined handling is explicit
|
||||
|
||||
**For Python:**
|
||||
- Type hints present on public functions
|
||||
- Exception handling is specific (no bare except)
|
||||
- Resources are closed (context managers, with blocks)
|
||||
|
||||
**For Go:**
|
||||
- Errors are handled or explicitly ignored with a comment
|
||||
- Context propagation is correct
|
||||
- Goroutine lifetimes are bounded
|
||||
|
||||
[Include only the section matching the stated language]
|
||||
|
||||
### 3. Change-Type-Specific Checks
|
||||
|
||||
**For bug fixes:**
|
||||
- A test exists that would have caught this bug
|
||||
- The fix addresses root cause, not symptom
|
||||
- Related code paths checked for the same issue
|
||||
|
||||
**For features:**
|
||||
- Acceptance criteria met
|
||||
- Edge cases handled (empty, large, concurrent)
|
||||
- Error paths tested, not just happy path
|
||||
- Telemetry/logging added for debugging
|
||||
|
||||
**For refactors:**
|
||||
- Behaviour unchanged (tests still pass)
|
||||
- No scope creep — refactor only
|
||||
- Complexity reduced, not just moved
|
||||
|
||||
**For dependency upgrades:**
|
||||
- Breaking changes reviewed
|
||||
- Security advisories checked
|
||||
- License compatibility verified
|
||||
|
||||
[Include only the section matching the stated change type]
|
||||
|
||||
### 4. Risk-Appropriate Checks
|
||||
|
||||
**Low risk:** basic correctness, style conventions, test coverage
|
||||
**Medium risk:** above + rollback plan, monitoring updates, performance considerations
|
||||
**High risk:** above + security implications, data migration safety, feature flag/gradual rollout
|
||||
**Critical risk:** above + staging validation plan, incident response plan, post-deploy verification checklist
|
||||
|
||||
### 5. Testing Adequacy
|
||||
- Unit tests cover new logic
|
||||
- Integration tests cover the contract changes
|
||||
- Edge cases tested
|
||||
- Failure modes tested
|
||||
- Performance tests if performance-sensitive
|
||||
|
||||
### 6. Review Decision Framework
|
||||
|
||||
**Approve if:** [2-3 specific conditions based on this PR]
|
||||
**Request changes if:** [Specific blockers]
|
||||
**Comment (non-blocking) if:** [Items worth discussing but not blocking merge]
|
||||
|
||||
### 7. Common Pitfalls for This Change Type
|
||||
Based on the change type and language, flag 2-3 things reviewers typically miss for this combination.
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
- [ ] Checklist is tailored to the stated language (not generic)
|
||||
- [ ] Change-type-specific section is included
|
||||
- [ ] Risk-appropriate depth matches stated risk level
|
||||
- [ ] Decision framework includes at least one named blocking condition and one named non-blocking comment condition
|
||||
- [ ] Common pitfalls are specific to the stated language + change-type combo (not generic advice like "watch out for bugs")
|
||||
|
||||
## Usage Examples
|
||||
- "Generate a code review checklist for [PR description]"
|
||||
- "What should I check in this pull request?"
|
||||
- "Give me a code review checklist for a [language] [change type]"
|
||||
- "Review checklist for a high-risk PR in [language]"
|
||||
@@ -0,0 +1,454 @@
|
||||
---
|
||||
name: database-migration-plan
|
||||
description: "Write a safe, zero-downtime database migration plan for a schema change. Use when asked to plan a database migration, design a zero-downtime schema change, document an expand/contract migration, produce a rollback procedure for a database change, or coordinate a database schema update with a deployment. Produces a structured migration plan covering migration objectives, backward compatibility analysis, expand/contract phase breakdown, exact SQL, rollback steps per phase, data validation queries, and a deployment runbook."
|
||||
---
|
||||
|
||||
# Database Migration Plan Skill
|
||||
|
||||
Produce a complete, safe database migration plan for a schema change. A migration plan is not just the SQL — it is a coordinated sequence of steps that ensures the application stays available, data stays consistent, and every step can be rolled back independently.
|
||||
|
||||
The expand/contract pattern is the default approach: expand the schema to support both old and new states, migrate the application, then contract to remove the old state. Never combine schema changes and data backfills in a single migration that runs during deployment.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask for these if not already provided:
|
||||
- **Current schema state** — the DDL or description of the table(s) as they are now
|
||||
- **Target schema state** — the DDL or description of what the table(s) should look like after migration
|
||||
- **Migration reason** — why this change is being made (new feature, performance fix, normalization, compliance)
|
||||
- **Database engine** — PostgreSQL, MySQL, SQLite, CockroachDB, etc.
|
||||
- **Estimated data volume** — approximate number of rows in affected tables
|
||||
- **Deployment constraints** — is any downtime allowed? What is the expected traffic level during migration? Are there multiple app instances running?
|
||||
- **Rollback window** — how long after deploy can the team roll back before the migration becomes irreversible?
|
||||
|
||||
## Output Format
|
||||
|
||||
---
|
||||
|
||||
# Database Migration Plan: [Migration Name]
|
||||
|
||||
**Service:** [Name] | **Team:** [Team name]
|
||||
**Author:** [Name] | **Reviewed by:** [Name / DBA]
|
||||
**Date:** [Date] | **Target deploy date:** [Date]
|
||||
**Database engine:** [PostgreSQL X.X / MySQL X.X]
|
||||
**Ticket:** [JIRA-XXX]
|
||||
|
||||
---
|
||||
|
||||
## 1. Migration Overview
|
||||
|
||||
**What is changing:**
|
||||
[1–2 sentences: the specific schema change — e.g. "Adding a non-nullable `organisation_id` column to the `users` table and backfilling it from the `accounts` table."]
|
||||
|
||||
**Why:**
|
||||
[1–2 sentences: the business or technical reason driving the change.]
|
||||
|
||||
**Migration type:** [Additive only / Additive + backfill / Column rename / Column type change / Table restructure / Index change]
|
||||
|
||||
**Zero-downtime:** [Yes — using expand/contract / No — requires maintenance window — state duration]
|
||||
|
||||
**Estimated migration duration:**
|
||||
- Expand phase: [~X minutes]
|
||||
- Data backfill: [~X minutes/hours — based on X rows at Y rows/second]
|
||||
- Contract phase: [~X minutes after app version deployed]
|
||||
|
||||
---
|
||||
|
||||
## 2. Backward Compatibility Analysis
|
||||
|
||||
Before writing a single line of SQL, assess whether each change is backward compatible with the currently deployed application code.
|
||||
|
||||
| Change | Backward compatible? | Risk | Notes |
|
||||
|---|---|---|---|
|
||||
| [e.g. Add nullable column `org_id`] | Yes | Low | Old app ignores new column |
|
||||
| [e.g. Backfill `org_id`] | Yes | Medium | Old app unaffected; new app reads backfilled values |
|
||||
| [e.g. Add NOT NULL constraint to `org_id`] | **No** | High | Old app that inserts without `org_id` will fail |
|
||||
| [e.g. Drop old column `account_id`] | **No** | High | Old app that reads `account_id` will fail |
|
||||
| [e.g. Add index on `org_id`] | Yes | Low | Additive; no breaking change |
|
||||
| [e.g. Rename column] | **No** | High | Never rename in one step; use expand/contract |
|
||||
|
||||
**Summary:** [e.g. "This migration requires the expand/contract pattern across 3 deployment phases because steps 3 and 4 are not backward compatible."]
|
||||
|
||||
---
|
||||
|
||||
## 3. Expand/Contract Phases
|
||||
|
||||
### Phase Overview
|
||||
|
||||
```
|
||||
Phase 1 — EXPAND
|
||||
Deploy migration: add new column (nullable), create new indexes
|
||||
Old app: continues to work (ignores new column)
|
||||
New app: not yet deployed
|
||||
Duration: [~X min] | Rollback: trivial — drop new column
|
||||
|
||||
│
|
||||
▼
|
||||
|
||||
Phase 2 — BACKFILL + DUAL-WRITE
|
||||
Deploy app update: writes to both old and new columns
|
||||
Run backfill: populate new column for existing rows
|
||||
Validate: confirm 100% of rows have non-null new column
|
||||
Duration: [~X hours depending on data volume]
|
||||
Rollback: deploy previous app version; new column is still nullable
|
||||
|
||||
│
|
||||
▼
|
||||
|
||||
Phase 3 — ENFORCE + SWITCH
|
||||
Deploy migration: add NOT NULL constraint, drop old column/index
|
||||
Deploy app update: reads only from new column
|
||||
Duration: [~X min] | Rollback: requires forward-fix (constraint must be dropped first)
|
||||
|
||||
│
|
||||
▼
|
||||
|
||||
Phase 4 — CONTRACT (optional cleanup)
|
||||
Deploy migration: drop deprecated columns, rename if needed
|
||||
Final state matches target schema
|
||||
Rollback: not recommended — contract changes are destructive
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 1 — Expand Schema
|
||||
|
||||
**Goal:** Add the new column and structures without breaking the existing application.
|
||||
**Deploy order:** Run migration first, then (optionally) deploy app.
|
||||
**Application state:** Old app running; no app changes required yet.
|
||||
|
||||
```sql
|
||||
-- Migration: 001_add_org_id_to_users.sql
|
||||
BEGIN;
|
||||
|
||||
-- Add nullable column (safe — old app ignores it)
|
||||
ALTER TABLE users
|
||||
ADD COLUMN org_id UUID NULL
|
||||
REFERENCES organisations(id) ON DELETE RESTRICT;
|
||||
|
||||
-- Add index NOW, not in Phase 3 — building index on large table during Phase 3 is risky
|
||||
CREATE INDEX CONCURRENTLY users_org_id_idx ON users (org_id);
|
||||
|
||||
-- Note: CONCURRENTLY does not lock the table; safe on live traffic
|
||||
-- Note: Cannot run CONCURRENTLY inside a transaction block; run separately if needed
|
||||
|
||||
COMMIT;
|
||||
```
|
||||
|
||||
**Validation after Phase 1:**
|
||||
```sql
|
||||
-- Confirm column exists and is nullable
|
||||
SELECT column_name, data_type, is_nullable
|
||||
FROM information_schema.columns
|
||||
WHERE table_name = 'users' AND column_name = 'org_id';
|
||||
-- Expected: is_nullable = 'YES'
|
||||
|
||||
-- Confirm index exists
|
||||
SELECT indexname, indexdef
|
||||
FROM pg_indexes
|
||||
WHERE tablename = 'users' AND indexname = 'users_org_id_idx';
|
||||
```
|
||||
|
||||
**Rollback (Phase 1 only):**
|
||||
```sql
|
||||
BEGIN;
|
||||
DROP INDEX CONCURRENTLY IF EXISTS users_org_id_idx;
|
||||
ALTER TABLE users DROP COLUMN IF EXISTS org_id;
|
||||
COMMIT;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 2 — Backfill Existing Data
|
||||
|
||||
**Goal:** Populate the new column for all existing rows before enforcing NOT NULL.
|
||||
**When to run:** After Phase 1 is live and stable. Can be run as a background job or a one-time script.
|
||||
**Application state:** Deploy app version that dual-writes to both old and new columns.
|
||||
|
||||
**App code change required:**
|
||||
```
|
||||
// All INSERT and UPDATE operations must now set BOTH old_column and new_column
|
||||
// until Phase 3 is complete. This ensures new rows are populated during the backfill window.
|
||||
```
|
||||
|
||||
**Backfill script — batch processing:**
|
||||
```sql
|
||||
-- Run in batches to avoid locking. Adjust batch size based on table size and DB load.
|
||||
-- Target: no single batch takes more than 5 seconds.
|
||||
|
||||
DO $$
|
||||
DECLARE
|
||||
batch_size INT := 1000;
|
||||
affected INT;
|
||||
BEGIN
|
||||
LOOP
|
||||
UPDATE users
|
||||
SET org_id = accounts.organisation_id
|
||||
FROM accounts
|
||||
WHERE users.account_id = accounts.id
|
||||
AND users.org_id IS NULL
|
||||
LIMIT batch_size;
|
||||
|
||||
GET DIAGNOSTICS affected = ROW_COUNT;
|
||||
EXIT WHEN affected = 0;
|
||||
|
||||
-- Pause between batches to avoid saturating I/O
|
||||
PERFORM pg_sleep(0.1);
|
||||
END LOOP;
|
||||
END $$;
|
||||
```
|
||||
|
||||
**Monitoring during backfill:**
|
||||
```sql
|
||||
-- Check progress — run periodically during backfill
|
||||
SELECT
|
||||
COUNT(*) FILTER (WHERE org_id IS NOT NULL) AS backfilled,
|
||||
COUNT(*) FILTER (WHERE org_id IS NULL) AS remaining,
|
||||
COUNT(*) AS total,
|
||||
ROUND(
|
||||
100.0 * COUNT(*) FILTER (WHERE org_id IS NOT NULL) / COUNT(*), 2
|
||||
) AS pct_complete
|
||||
FROM users;
|
||||
```
|
||||
|
||||
**Backfill completion validation:**
|
||||
```sql
|
||||
-- Must return 0 before proceeding to Phase 3
|
||||
SELECT COUNT(*) AS unbackfilled_rows
|
||||
FROM users
|
||||
WHERE org_id IS NULL;
|
||||
|
||||
-- Confirm no new rows written without org_id (dual-write working)
|
||||
SELECT COUNT(*) AS recent_missing
|
||||
FROM users
|
||||
WHERE org_id IS NULL
|
||||
AND created_at > now() - INTERVAL '1 hour';
|
||||
```
|
||||
|
||||
**Rollback (Phase 2 — app only):**
|
||||
- Deploy previous app version (single-write to old column)
|
||||
- `org_id` column remains nullable; no data is lost
|
||||
- Backfilled values remain; harmless
|
||||
|
||||
---
|
||||
|
||||
### Phase 3 — Enforce Constraints
|
||||
|
||||
**Goal:** Add NOT NULL constraint and remove dependency on the old column.
|
||||
**Prerequisites:** Phase 2 backfill must be 100% complete (zero rows with `org_id IS NULL`).
|
||||
**Deploy order:** Run migration, then deploy app version that reads only from `org_id`.
|
||||
|
||||
**PostgreSQL — use NOT VALID + VALIDATE for large tables:**
|
||||
```sql
|
||||
-- Step 1: Add constraint as NOT VALID (no full table scan — instant)
|
||||
ALTER TABLE users
|
||||
ADD CONSTRAINT users_org_id_not_null
|
||||
CHECK (org_id IS NOT NULL) NOT VALID;
|
||||
|
||||
-- Step 2: VALIDATE CONSTRAINT (takes a SHARE UPDATE EXCLUSIVE lock — allows reads and writes)
|
||||
-- Run this separately, as it can take minutes on large tables
|
||||
ALTER TABLE users
|
||||
VALIDATE CONSTRAINT users_org_id_not_null;
|
||||
|
||||
-- Step 3: Once validated, convert to actual NOT NULL
|
||||
-- (PostgreSQL trusts the validated check constraint — this is instant)
|
||||
ALTER TABLE users
|
||||
ALTER COLUMN org_id SET NOT NULL;
|
||||
|
||||
-- Step 4: Drop the now-redundant check constraint
|
||||
ALTER TABLE users
|
||||
DROP CONSTRAINT users_org_id_not_null;
|
||||
```
|
||||
|
||||
**Validation after Phase 3:**
|
||||
```sql
|
||||
-- Confirm NOT NULL is enforced
|
||||
SELECT column_name, is_nullable
|
||||
FROM information_schema.columns
|
||||
WHERE table_name = 'users' AND column_name = 'org_id';
|
||||
-- Expected: is_nullable = 'NO'
|
||||
|
||||
-- Test that insert without org_id fails (run in a transaction and roll back)
|
||||
BEGIN;
|
||||
INSERT INTO users (email) VALUES ('test@example.com');
|
||||
-- Expected: ERROR: null value in column "org_id" violates not-null constraint
|
||||
ROLLBACK;
|
||||
```
|
||||
|
||||
**Rollback (Phase 3):**
|
||||
```sql
|
||||
-- Drop the NOT NULL constraint (restores nullable state)
|
||||
ALTER TABLE users ALTER COLUMN org_id DROP NOT NULL;
|
||||
-- Then deploy previous app version (dual-write)
|
||||
-- Note: Once app code reading the new column is live, rolling back the constraint
|
||||
-- without rolling back the app will cause issues — plan this carefully.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 4 — Contract (Remove Old Column)
|
||||
|
||||
**Goal:** Remove the old column once the app no longer references it.
|
||||
**Prerequisites:** Phase 3 fully deployed and stable for at least [X days/hours rollback window].
|
||||
**Warning:** This phase is destructive — the old column's data is permanently deleted.
|
||||
|
||||
```sql
|
||||
BEGIN;
|
||||
|
||||
-- Drop the old column
|
||||
ALTER TABLE users DROP COLUMN account_id;
|
||||
|
||||
-- Drop any indexes that referenced the old column
|
||||
DROP INDEX IF EXISTS users_account_id_idx;
|
||||
|
||||
COMMIT;
|
||||
```
|
||||
|
||||
**Pre-drop validation:**
|
||||
```sql
|
||||
-- Confirm no application queries still reference the old column
|
||||
-- (Check this in code review and via a search of the codebase before running)
|
||||
-- grep -r "account_id" app/
|
||||
|
||||
-- Confirm the column is safe to drop
|
||||
SELECT COUNT(*) FROM users WHERE account_id IS NOT NULL;
|
||||
-- Should be 0 (or irrelevant once new column is canonical)
|
||||
```
|
||||
|
||||
**Rollback:** Not straightforward — dropped column data cannot be recovered. Only proceed to Phase 4 after the rollback window has passed and the change is confirmed stable.
|
||||
|
||||
---
|
||||
|
||||
## 4. Data Validation Plan
|
||||
|
||||
Run these queries before and after the full migration to confirm data integrity.
|
||||
|
||||
**Pre-migration baseline:**
|
||||
```sql
|
||||
-- Record these values before any migration step
|
||||
SELECT COUNT(*) AS total_users FROM users;
|
||||
SELECT COUNT(*) AS total_orgs FROM organisations;
|
||||
SELECT MIN(created_at), MAX(created_at) FROM users;
|
||||
|
||||
-- Check for any anomalies in the source data before backfill
|
||||
SELECT COUNT(*) AS users_without_account
|
||||
FROM users WHERE account_id IS NULL;
|
||||
```
|
||||
|
||||
**Post-backfill integrity check:**
|
||||
```sql
|
||||
-- All users have an org that exists
|
||||
SELECT COUNT(*) AS orphaned_org_refs
|
||||
FROM users u
|
||||
WHERE u.org_id IS NOT NULL
|
||||
AND NOT EXISTS (
|
||||
SELECT 1 FROM organisations o WHERE o.id = u.org_id
|
||||
);
|
||||
-- Expected: 0
|
||||
|
||||
-- org_id matches expected value from source column
|
||||
SELECT COUNT(*) AS mismatched_backfill
|
||||
FROM users u
|
||||
JOIN accounts a ON u.account_id = a.id
|
||||
WHERE u.org_id != a.organisation_id;
|
||||
-- Expected: 0
|
||||
|
||||
-- Row count unchanged (no rows created or deleted by migration)
|
||||
SELECT COUNT(*) AS total_users_after FROM users;
|
||||
-- Must match pre-migration baseline
|
||||
```
|
||||
|
||||
**Post-contract final check:**
|
||||
```sql
|
||||
-- Old column is gone
|
||||
SELECT COUNT(*) FROM information_schema.columns
|
||||
WHERE table_name = 'users' AND column_name = 'account_id';
|
||||
-- Expected: 0
|
||||
|
||||
-- New column is NOT NULL
|
||||
SELECT is_nullable FROM information_schema.columns
|
||||
WHERE table_name = 'users' AND column_name = 'org_id';
|
||||
-- Expected: NO
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Performance Impact Assessment
|
||||
|
||||
| Step | Lock type | Lock duration | Traffic impact |
|
||||
|---|---|---|---|
|
||||
| Add nullable column | ACCESS EXCLUSIVE | Milliseconds | Negligible |
|
||||
| CREATE INDEX CONCURRENTLY | SHARE UPDATE EXCLUSIVE | Minutes (proportional to table size) | Reads and writes continue |
|
||||
| Batch backfill | Row-level locks only | <5s per batch | Low if batches are small |
|
||||
| ADD CONSTRAINT NOT VALID | ACCESS EXCLUSIVE | Milliseconds | Negligible |
|
||||
| VALIDATE CONSTRAINT | SHARE UPDATE EXCLUSIVE | Minutes | Reads and writes continue |
|
||||
| ALTER COLUMN SET NOT NULL | ACCESS EXCLUSIVE | Milliseconds (if check constraint validated) | Negligible |
|
||||
| DROP COLUMN | ACCESS EXCLUSIVE | Milliseconds | Negligible |
|
||||
|
||||
**Expected load increase during backfill:**
|
||||
- DB CPU: [estimated % increase during batch writes]
|
||||
- DB I/O: [estimated increase]
|
||||
- Monitoring threshold to pause backfill: [e.g. DB CPU > 80% for >2 minutes]
|
||||
|
||||
**Backfill rate estimate:**
|
||||
- Table size: [X million rows]
|
||||
- Batch size: [1000 rows]
|
||||
- Pause between batches: [100ms]
|
||||
- Estimated total duration: [X hours at Y rows/second]
|
||||
|
||||
---
|
||||
|
||||
## 6. Deployment Runbook
|
||||
|
||||
Follow this checklist on the day of migration. Mark each step as done before proceeding.
|
||||
|
||||
**Pre-migration (day before):**
|
||||
- [ ] DBA / tech lead has reviewed the migration plan
|
||||
- [ ] Performance impact assessed; monitoring dashboards ready
|
||||
- [ ] Backfill script tested on a staging DB with production-scale data
|
||||
- [ ] Rollback procedure tested on staging
|
||||
- [ ] On-call engineer briefed; Slack channel [#db-migrations] set up for coordination
|
||||
- [ ] Maintenance window scheduled (if required)
|
||||
|
||||
**Phase 1 — Expand (T+0):**
|
||||
- [ ] Take a manual DB snapshot / verify automated backup is recent
|
||||
- [ ] Run `001_expand_add_org_id.sql` on production
|
||||
- [ ] Run Phase 1 validation queries — confirm pass
|
||||
- [ ] Deploy app version with dual-write
|
||||
- [ ] Monitor error rate for [10 minutes]
|
||||
|
||||
**Phase 2 — Backfill (T+[X hours]):**
|
||||
- [ ] Confirm Phase 1 has been stable for [X hours]
|
||||
- [ ] Start backfill script in a screen/tmux session
|
||||
- [ ] Monitor progress via backfill progress query every [5 minutes]
|
||||
- [ ] Monitor DB CPU and I/O — pause if thresholds exceeded
|
||||
- [ ] Run completion validation — confirm 0 unbackfilled rows
|
||||
- [ ] Run integrity checks — confirm 0 orphaned refs, 0 mismatches
|
||||
|
||||
**Phase 3 — Enforce (T+[X days]):**
|
||||
- [ ] Confirm backfill 100% complete and stable for [X hours]
|
||||
- [ ] Add NOT VALID constraint
|
||||
- [ ] Run VALIDATE CONSTRAINT (monitor duration and lock waits)
|
||||
- [ ] Alter column to NOT NULL
|
||||
- [ ] Run Phase 3 validation queries
|
||||
- [ ] Deploy app version reading only from new column
|
||||
- [ ] Monitor error rate for [30 minutes]
|
||||
|
||||
**Phase 4 — Contract (T+[X days after rollback window]):**
|
||||
- [ ] Confirm rollback window has passed — no incidents, no rollback needed
|
||||
- [ ] Search codebase for references to old column — confirm zero
|
||||
- [ ] Run DROP COLUMN migration
|
||||
- [ ] Run final integrity checks
|
||||
- [ ] Close migration ticket; update schema documentation
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Every migration phase has an independent rollback procedure — no phase assumes the next one has run
|
||||
- [ ] Batch backfill script includes a pause between batches to avoid saturating I/O
|
||||
- [ ] NOT NULL constraints use the NOT VALID + VALIDATE pattern on tables with >100k rows
|
||||
- [ ] The app dual-write period is explicitly defined — old column writes are not dropped until Phase 3 is deployed
|
||||
- [ ] Data validation queries include a row count check to confirm no data loss
|
||||
- [ ] Lock types are identified for every DDL statement — no "should be fine" assumptions
|
||||
- [ ] The deployment runbook names who runs each step, not just what to run
|
||||
- [ ] Phase 4 (contract) is explicitly gated on the rollback window passing — not run on the same day as Phase 3
|
||||
@@ -0,0 +1,356 @@
|
||||
---
|
||||
name: database-schema-design
|
||||
description: "Document or design a database schema with entity relationships, table definitions, constraints, indexes, and access patterns. Use when asked to design a database, document an existing schema, model entities and relationships, define table structures, plan an index strategy, or produce a data model for review. Produces a structured schema document covering an ER diagram, table DDL definitions, index strategy, access pattern analysis, normalization decisions, and migration notes."
|
||||
---
|
||||
|
||||
# Database Schema Design Skill
|
||||
|
||||
Produce a complete database schema design document for a given domain. A schema document is not just a list of tables — it is a record of decisions: what was modelled, how entities relate, which queries the schema is optimised for, and what trade-offs were made.
|
||||
|
||||
A good schema design document lets an engineer understand the data model, query it correctly, extend it safely, and write migrations without breaking things.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask for these if not already provided:
|
||||
- **Domain description** — what the system does; what business objects are being modelled
|
||||
- **Entities and relationships** — the main things in the domain and how they relate (e.g. "a User has many Orders; an Order has many OrderItems; an OrderItem references a Product")
|
||||
- **Expected query patterns** — the most important read and write queries (e.g. "fetch all orders for a user, sorted by date"; "look up a product by SKU")
|
||||
- **Database engine** — PostgreSQL, MySQL, SQLite, CockroachDB, etc. — this affects DDL syntax and available types
|
||||
- **Expected data volume** — approximate row counts, growth rate, and any partitioning needs
|
||||
- **Constraints** — any existing conventions, naming standards, or migration constraints to respect
|
||||
|
||||
## Output Format
|
||||
|
||||
---
|
||||
|
||||
# Database Schema Design: [Domain / Service Name]
|
||||
|
||||
**Service:** [Name] | **Team:** [Team name]
|
||||
**Author:** [Name] | **Reviewed by:** [Name]
|
||||
**Date:** [Date] | **Database engine:** [PostgreSQL X.X / MySQL X.X / etc.]
|
||||
**Status:** [Draft / Reviewed / Approved]
|
||||
|
||||
---
|
||||
|
||||
## 1. Overview
|
||||
|
||||
[2–3 sentences describing the domain being modelled, the scope of this schema, and any key design philosophy (e.g. "this schema prioritises read performance for the customer-facing API over write simplicity", or "designed for eventual migration to multi-tenancy")]
|
||||
|
||||
**In scope:**
|
||||
- [Entity or subsystem]
|
||||
- [Entity or subsystem]
|
||||
|
||||
**Out of scope:**
|
||||
- [e.g. Analytics / reporting tables — separate schema]
|
||||
- [e.g. Audit log tables — covered in separate design doc]
|
||||
|
||||
---
|
||||
|
||||
## 2. Entity Relationship Diagram
|
||||
|
||||
```
|
||||
┌───────────────────┐ ┌───────────────────────┐
|
||||
│ users │ │ organisations │
|
||||
│───────────────── │ │─────────────────────── │
|
||||
│ id (PK) │ ┌───▶│ id (PK) │
|
||||
│ org_id (FK) ─────┼────┘ │ name │
|
||||
│ email │ │ plan │
|
||||
│ display_name │ │ created_at │
|
||||
│ created_at │ └───────────────────────┘
|
||||
│ updated_at │
|
||||
└─────────┬─────────┘
|
||||
│ 1
|
||||
│
|
||||
│ N
|
||||
┌─────────▼─────────┐ ┌───────────────────────┐
|
||||
│ [table_a] │ │ [table_b] │
|
||||
│───────────────── │ │─────────────────────── │
|
||||
│ id (PK) │ N │ id (PK) │
|
||||
│ user_id (FK) ─────┼────────▶│ [table_a]_id (FK) │
|
||||
│ [field] │ │ │ [field] │
|
||||
│ [field] │ │ │ [field] │
|
||||
│ created_at │ │ created_at │
|
||||
└───────────────────┘ └───────────────────────┘
|
||||
```
|
||||
|
||||
**Relationship summary:**
|
||||
|
||||
| Entity A | Relationship | Entity B | Notes |
|
||||
|---|---|---|---|
|
||||
| organisations | has many | users | An org can have many users |
|
||||
| users | has many | [table_a] | Soft-deleted on user deletion |
|
||||
| [table_a] | has many | [table_b] | Cascade delete |
|
||||
| [table_b] | belongs to | [table_a] | Non-nullable FK |
|
||||
| [table_c] | many-to-many (via [join_table]) | [table_d] | Join table with metadata |
|
||||
|
||||
---
|
||||
|
||||
## 3. Table Definitions
|
||||
|
||||
### `organisations`
|
||||
|
||||
[1 sentence describing what this table stores and its role in the domain.]
|
||||
|
||||
```sql
|
||||
CREATE TABLE organisations (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
name VARCHAR(255) NOT NULL,
|
||||
slug VARCHAR(100) NOT NULL UNIQUE,
|
||||
plan VARCHAR(50) NOT NULL DEFAULT 'free'
|
||||
CHECK (plan IN ('free', 'pro', 'enterprise')),
|
||||
settings JSONB NOT NULL DEFAULT '{}',
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
|
||||
);
|
||||
```
|
||||
|
||||
| Column | Type | Nullable | Default | Notes |
|
||||
|---|---|---|---|---|
|
||||
| id | UUID | No | gen_random_uuid() | Surrogate PK — UUID preferred over serial for distributed use |
|
||||
| name | VARCHAR(255) | No | — | Display name; not unique |
|
||||
| slug | VARCHAR(100) | No | — | URL-safe identifier; unique across all orgs |
|
||||
| plan | VARCHAR(50) | No | 'free' | Constrained to known values via CHECK |
|
||||
| settings | JSONB | No | {} | Flexible config; avoid for queryable fields |
|
||||
| created_at | TIMESTAMPTZ | No | now() | Always use TIMESTAMPTZ, not TIMESTAMP |
|
||||
| updated_at | TIMESTAMPTZ | No | now() | Updated via trigger (see below) |
|
||||
|
||||
---
|
||||
|
||||
### `users`
|
||||
|
||||
[1 sentence describing what this table stores.]
|
||||
|
||||
```sql
|
||||
CREATE TABLE users (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
org_id UUID NOT NULL REFERENCES organisations(id)
|
||||
ON DELETE RESTRICT,
|
||||
email VARCHAR(254) NOT NULL,
|
||||
display_name VARCHAR(255) NOT NULL DEFAULT '',
|
||||
role VARCHAR(50) NOT NULL DEFAULT 'member'
|
||||
CHECK (role IN ('owner', 'admin', 'member', 'viewer')),
|
||||
email_verified BOOLEAN NOT NULL DEFAULT false,
|
||||
deleted_at TIMESTAMPTZ NULL,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||
|
||||
CONSTRAINT users_email_org_unique UNIQUE (email, org_id)
|
||||
);
|
||||
```
|
||||
|
||||
| Column | Type | Nullable | Default | Notes |
|
||||
|---|---|---|---|---|
|
||||
| id | UUID | No | gen_random_uuid() | — |
|
||||
| org_id | UUID | No | — | FK to organisations; RESTRICT prevents orphaning |
|
||||
| email | VARCHAR(254) | No | — | RFC 5321 max length; unique per org (not globally) |
|
||||
| role | VARCHAR(50) | No | 'member' | Application-level RBAC |
|
||||
| deleted_at | TIMESTAMPTZ | Yes | NULL | Soft delete; NULL = active |
|
||||
|
||||
**Soft delete policy:** Rows with `deleted_at IS NOT NULL` are considered deleted. All application queries MUST filter `WHERE deleted_at IS NULL` unless explicitly fetching deleted records. Use a view or ORM scope to enforce this.
|
||||
|
||||
---
|
||||
|
||||
### `[table_a]`
|
||||
|
||||
[Description of what this table models.]
|
||||
|
||||
```sql
|
||||
CREATE TABLE [table_a] (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
|
||||
[field_1] VARCHAR(255) NOT NULL,
|
||||
[field_2] TEXT NULL,
|
||||
[field_3] INTEGER NOT NULL DEFAULT 0 CHECK ([field_3] >= 0),
|
||||
status VARCHAR(50) NOT NULL DEFAULT 'pending'
|
||||
CHECK (status IN ('pending', 'active', 'archived')),
|
||||
metadata JSONB NOT NULL DEFAULT '{}',
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
|
||||
);
|
||||
```
|
||||
|
||||
| Column | Type | Nullable | Notes |
|
||||
|---|---|---|---|
|
||||
| user_id | UUID | No | CASCADE delete — when user is deleted, their [table_a] rows are too |
|
||||
| [field_1] | VARCHAR(255) | No | [Reason for length constraint] |
|
||||
| status | VARCHAR(50) | No | State machine: pending → active → archived (no other transitions) |
|
||||
| metadata | JSONB | No | [What is stored here and why it's not a typed column] |
|
||||
|
||||
---
|
||||
|
||||
### `[join_table]` *(Many-to-many)*
|
||||
|
||||
[Description of the relationship this table represents.]
|
||||
|
||||
```sql
|
||||
CREATE TABLE [join_table] (
|
||||
[table_c]_id UUID NOT NULL REFERENCES [table_c](id) ON DELETE CASCADE,
|
||||
[table_d]_id UUID NOT NULL REFERENCES [table_d](id) ON DELETE CASCADE,
|
||||
granted_by UUID NOT NULL REFERENCES users(id) ON DELETE RESTRICT,
|
||||
granted_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||
|
||||
PRIMARY KEY ([table_c]_id, [table_d]_id)
|
||||
);
|
||||
```
|
||||
|
||||
**Why a composite PK:** The combination of `[table_c]_id + [table_d]_id` is the natural key — each association is unique and the primary key doubles as the uniqueness constraint without needing a separate index.
|
||||
|
||||
---
|
||||
|
||||
## 4. Index Strategy
|
||||
|
||||
For each table, define which indexes are created and why. Include the query they are designed to serve.
|
||||
|
||||
| Table | Index name | Columns | Type | Query served | Notes |
|
||||
|---|---|---|---|---|---|
|
||||
| users | `users_org_id_idx` | `(org_id)` | B-tree | `SELECT * FROM users WHERE org_id = $1` | FK lookup; required for join performance |
|
||||
| users | `users_email_lower_idx` | `(lower(email))` | B-tree (functional) | `WHERE lower(email) = lower($1)` | Case-insensitive email lookup |
|
||||
| users | `users_active_by_org_idx` | `(org_id, created_at DESC)` | B-tree | `WHERE org_id = $1 AND deleted_at IS NULL ORDER BY created_at DESC` | Partial index candidate (see below) |
|
||||
| [table_a] | `[table_a]_user_id_status_idx` | `(user_id, status)` | B-tree | `WHERE user_id = $1 AND status = 'active'` | Compound — order matters |
|
||||
| [table_a] | `[table_a]_metadata_gin_idx` | `metadata` | GIN | `WHERE metadata @> '{"key": "value"}'` | Only add if JSONB queried frequently |
|
||||
|
||||
**Partial indexes (PostgreSQL):**
|
||||
|
||||
```sql
|
||||
-- Index only active (non-deleted) users — dramatically smaller for soft-delete tables
|
||||
CREATE INDEX users_active_email_idx
|
||||
ON users (email, org_id)
|
||||
WHERE deleted_at IS NULL;
|
||||
|
||||
-- Index only pending items — avoids indexing the majority of rows
|
||||
CREATE INDEX [table_a]_pending_idx
|
||||
ON [table_a] (user_id, created_at)
|
||||
WHERE status = 'pending';
|
||||
```
|
||||
|
||||
**Index design principles applied:**
|
||||
- FKs that appear in JOIN conditions always have an index
|
||||
- Compound indexes follow selectivity order: most selective column first
|
||||
- Functional indexes for case-insensitive lookups
|
||||
- GIN indexes only where JSONB containment queries are frequent
|
||||
- Partial indexes for status-filtered queries on large tables
|
||||
|
||||
---
|
||||
|
||||
## 5. Access Pattern Analysis
|
||||
|
||||
Document the primary queries this schema is designed to serve. For each, show the query, the indexes used, and any caveats.
|
||||
|
||||
### AP-1: Fetch all active users for an organisation (paginated)
|
||||
|
||||
**Frequency:** Very high — called on every dashboard load
|
||||
**Query:**
|
||||
```sql
|
||||
SELECT id, email, display_name, role, created_at
|
||||
FROM users
|
||||
WHERE org_id = $1
|
||||
AND deleted_at IS NULL
|
||||
ORDER BY created_at DESC
|
||||
LIMIT 50 OFFSET $2;
|
||||
```
|
||||
**Index used:** `users_active_by_org_idx` (org_id, created_at DESC)
|
||||
**Notes:** Use keyset pagination (`WHERE created_at < $cursor`) at scale; OFFSET degrades past ~10k rows.
|
||||
|
||||
---
|
||||
|
||||
### AP-2: Look up a user by email (case-insensitive)
|
||||
|
||||
**Frequency:** High — every authentication attempt
|
||||
**Query:**
|
||||
```sql
|
||||
SELECT id, org_id, role, email_verified
|
||||
FROM users
|
||||
WHERE lower(email) = lower($1)
|
||||
AND deleted_at IS NULL;
|
||||
```
|
||||
**Index used:** `users_email_lower_idx`
|
||||
**Notes:** Returns multiple rows if same email exists across orgs. Application resolves by org context.
|
||||
|
||||
---
|
||||
|
||||
### AP-3: Fetch [table_a] items for a user by status
|
||||
|
||||
**Frequency:** High
|
||||
**Query:**
|
||||
```sql
|
||||
SELECT *
|
||||
FROM [table_a]
|
||||
WHERE user_id = $1
|
||||
AND status = $2
|
||||
ORDER BY created_at DESC
|
||||
LIMIT 25;
|
||||
```
|
||||
**Index used:** `[table_a]_user_id_status_idx`
|
||||
**Notes:** Compound index covers both filter columns. Status filter must come second in the index because user_id is more selective.
|
||||
|
||||
---
|
||||
|
||||
### AP-4: [Add further access patterns as needed]
|
||||
|
||||
---
|
||||
|
||||
## 6. Normalization Decisions
|
||||
|
||||
Document deliberate choices to normalize or denormalize, with reasoning.
|
||||
|
||||
| Decision | Approach | Reasoning |
|
||||
|---|---|---|
|
||||
| [e.g. Organisation name on users table?] | **Not denormalized** — always join to organisations | Avoid stale copies; org name changes are infrequent and joining is cheap |
|
||||
| [e.g. Status history] | **Not in this table** — separate `[table_a]_status_history` if needed | Current status is all that's needed for 99% of queries; history is auditing, not application data |
|
||||
| [e.g. JSONB `settings` column on organisations] | **Denormalized into JSONB** | Settings are read together; never queried by field; schema changes don't require migrations |
|
||||
| [e.g. Computed aggregate counts] | **Not stored** — computed at query time | Counts are small; maintaining a counter column requires careful locking; use `SELECT COUNT(*)` with the index |
|
||||
|
||||
---
|
||||
|
||||
## 7. Triggers and Automation
|
||||
|
||||
```sql
|
||||
-- Automatically update updated_at on any row modification
|
||||
CREATE OR REPLACE FUNCTION set_updated_at()
|
||||
RETURNS TRIGGER AS $$
|
||||
BEGIN
|
||||
NEW.updated_at = now();
|
||||
RETURN NEW;
|
||||
END;
|
||||
$$ LANGUAGE plpgsql;
|
||||
|
||||
-- Apply to all tables with updated_at
|
||||
CREATE TRIGGER users_updated_at
|
||||
BEFORE UPDATE ON users
|
||||
FOR EACH ROW EXECUTE FUNCTION set_updated_at();
|
||||
|
||||
CREATE TRIGGER [table_a]_updated_at
|
||||
BEFORE UPDATE ON [table_a]
|
||||
FOR EACH ROW EXECUTE FUNCTION set_updated_at();
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Migration Notes
|
||||
|
||||
If this schema is being introduced to an existing system, note the migration approach.
|
||||
|
||||
| Step | Description | Backward compatible | Risk |
|
||||
|---|---|---|---|
|
||||
| 1 | Create `organisations` table | Yes — additive | Low |
|
||||
| 2 | Create `users` table | Yes — additive | Low |
|
||||
| 3 | Backfill `org_id` on existing users | **Requires dual-write period** | Medium |
|
||||
| 4 | Add NOT NULL constraint on `org_id` | Requires backfill to be 100% complete | Medium |
|
||||
| 5 | Remove deprecated columns | Requires app code updated first | Low once app deployed |
|
||||
|
||||
**Backfill strategy:** [Describe how to handle existing data — batch size, rate limiting, validation queries]
|
||||
|
||||
**Rollback:** Each migration step should be independently reversible. See [database-migration-plan skill] for the full rollback procedure template.
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Every table has a primary key and a `created_at` column — no implicit ordering by row insertion
|
||||
- [ ] Every foreign key has a corresponding index — no missing FK indexes that would cause full table scans on joins
|
||||
- [ ] All TIMESTAMPTZ columns, not TIMESTAMP — timezone awareness is explicit
|
||||
- [ ] Soft-delete tables document the convention and where the filter is enforced (ORM scope, view, or query standard)
|
||||
- [ ] Every access pattern in the design has a supporting index or an explicit note that a full table scan is acceptable
|
||||
- [ ] JSONB columns are justified — not used as a substitute for proper schema design on queryable fields
|
||||
- [ ] Normalization decisions are documented with reasoning, not just stated
|
||||
- [ ] Migration notes address existing data if this is a schema change, not a greenfield schema
|
||||
@@ -0,0 +1,87 @@
|
||||
---
|
||||
name: debugging-log-analyser
|
||||
description: "Parse error logs, stack traces, and crash reports into a structured root cause diagnosis. Use when sharing a log, stack trace, error output, or crash dump. Produces a structured diagnosis with probable root cause, affected code path, suggested fix, and next debugging steps."
|
||||
---
|
||||
|
||||
# Debugging Log Analyser Skill
|
||||
|
||||
Parses raw error logs, stack traces, and crash reports into a structured diagnosis with probable root cause, affected code path, and specific next steps — no hand-waving.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask for these if not provided:
|
||||
- **The log / stack trace / error output** (paste directly or describe the error)
|
||||
- **Language and framework** (e.g. Node.js + Express, Python + Django, Java Spring, Go)
|
||||
- **Context** (what changed before this started — e.g. recent deploy, config change, increased traffic, new input data; or "nothing changed" is also useful)
|
||||
- **Frequency** (one-off / intermittent / consistent / regression after a specific change)
|
||||
- **Environment** (local dev / staging / production)
|
||||
- **What they've already tried** (if anything)
|
||||
|
||||
## Output Format
|
||||
|
||||
---
|
||||
|
||||
# Debugging Report: [Service/App Name]
|
||||
|
||||
### 1. Error Classification
|
||||
**Error type:** [Runtime exception / Build error / Config error / Network error / Memory error / Unknown]
|
||||
**Severity:** [Fatal / Critical / Warning / Informational]
|
||||
**Recurrence pattern:** [One-off / Intermittent / Consistent / On-startup / Under load]
|
||||
|
||||
### 2. Stack Trace Analysis
|
||||
|
||||
Walk the stack frame by frame, starting from the origin:
|
||||
- **Origin frame:** [File, line, function where it started]
|
||||
- **Propagation path:** [How it travelled through the call stack]
|
||||
- **Crash point:** [Where it ultimately threw/panicked/exited]
|
||||
|
||||
For each significant frame, note whether it is:
|
||||
- User code (fixable here)
|
||||
- Framework/library code (usually a misuse issue)
|
||||
- System/runtime code (usually a config or environment issue)
|
||||
|
||||
### 3. Root Cause Assessment
|
||||
**Probable root cause:** [1–2 sentence plain English statement]
|
||||
**Confidence:** [High / Medium / Low — and why]
|
||||
**Alternative causes to rule out:** [If confidence is not high]
|
||||
|
||||
### 4. Affected Code Path
|
||||
**Entry point:** [Where the triggering call began]
|
||||
**Key function(s) involved:** [Specific functions/methods named in the trace]
|
||||
**Data that triggered it:** [If inferable from the log — e.g. null value, malformed JSON]
|
||||
|
||||
### 5. Suggested Fix
|
||||
Provide a concrete, code-level suggestion:
|
||||
- What to change (the minimal fix)
|
||||
- Why this fixes the root cause
|
||||
- Any trade-offs or risks in the fix
|
||||
- A short code snippet if helpful
|
||||
|
||||
### 6. Next Debugging Steps
|
||||
If the root cause is uncertain, provide an ordered list of 3–5 specific debugging actions:
|
||||
1. [Specific thing to check — file, log line, config value]
|
||||
2. [Specific reproduction step or isolation test]
|
||||
3. [Specific tool command — e.g. `strace`, `pprof`, `--verbose`, add logging at X]
|
||||
|
||||
### 7. Prevention
|
||||
One or two concrete things that would prevent this class of error recurring:
|
||||
- Better input validation at [point]
|
||||
- Add monitoring/alerting for [condition]
|
||||
- Test that covers [scenario]
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
- [ ] Root cause is specific (not "there might be a null pointer issue")
|
||||
- [ ] At least one concrete code-level fix is suggested
|
||||
- [ ] Next steps are actionable commands, not vague advice
|
||||
- [ ] Suggested fix references the actual language/framework in the input (not a generic fix that could apply to any language)
|
||||
- [ ] Confidence level includes a stated reason (not just "High" or "Low" with no explanation)
|
||||
- [ ] Prevention is proactive (not just "add error handling")
|
||||
|
||||
## Usage Examples
|
||||
- "Why is this crashing?" + [paste log]
|
||||
- "Can you analyse this stack trace?"
|
||||
- "I'm getting this error, what does it mean?"
|
||||
- "Debug this log for me"
|
||||
- "What's causing this exception?"
|
||||
@@ -0,0 +1,332 @@
|
||||
---
|
||||
name: dependency-audit
|
||||
description: "Conduct a dependency audit for a project — checking for security vulnerabilities, license compliance issues, outdated packages, and transitive dependency risk. Use when asked to audit dependencies, review package security, check license compliance, assess dependency health, or produce a vulnerability report. Produces a vulnerability findings table, license compliance matrix, update priority matrix, dependency health score, and 30-day remediation plan."
|
||||
---
|
||||
|
||||
# Dependency Audit Skill
|
||||
|
||||
Produce a complete dependency audit report for a project — covering security vulnerabilities (with CVE references), license compliance against policy, outdated packages prioritised by risk, transitive dependency risk analysis, and a concrete remediation plan with timeline. A good dependency audit gives the team a clear, prioritised action list — not a raw dump of audit output that no one acts on.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask for these if not already provided:
|
||||
- **Project language and ecosystem** — npm, pip/PyPI, Maven/Gradle, Go modules, Cargo, RubyGems, NuGet, or mixed
|
||||
- **Dependency list or package manifest** — paste the contents of `package.json`, `requirements.txt`, `go.mod`, `pom.xml`, etc., or provide the audit tool output
|
||||
- **License policy** — which licenses are allowed, which are restricted (e.g. "GPL is prohibited", "MIT/Apache/BSD only", or "no policy yet — recommend one")
|
||||
- **Current security tooling** — Dependabot, Snyk, OWASP Dependency-Check, npm audit, pip-audit, or none
|
||||
|
||||
## Output Format
|
||||
|
||||
---
|
||||
|
||||
# Dependency Audit Report: [Project Name]
|
||||
|
||||
**Ecosystem:** [npm / pip / Maven / Go / etc.]
|
||||
**Audit date:** [Date]
|
||||
**Auditor:** [Name]
|
||||
**Total direct dependencies:** [N]
|
||||
**Total transitive dependencies:** [N]
|
||||
**Audit tool(s) used:** [npm audit / pip-audit / Snyk / OWASP Dependency-Check / etc.]
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
| Category | Finding | Risk level |
|
||||
|---|---|---|
|
||||
| Critical vulnerabilities | [N] CVEs requiring immediate action | [Critical / High / Low] |
|
||||
| High vulnerabilities | [N] CVEs — fix within 7 days | [High / Medium] |
|
||||
| License violations | [N] packages with non-compliant licenses | [High / Low] |
|
||||
| Severely outdated packages | [N] packages > 2 major versions behind | [Medium] |
|
||||
| Packages with no active maintenance | [N] packages — no commits in 12+ months | [Medium] |
|
||||
| **Overall dependency health score** | **[Score]/100** | **[Red / Amber / Green]** |
|
||||
|
||||
**Scoring methodology:** Critical CVEs: −20 each. High CVEs: −10 each. License violations: −15 each. Abandoned packages: −5 each. Maximum deduction: 100. Score ≥80 = Green, 60–79 = Amber, <60 = Red.
|
||||
|
||||
**Immediate actions required:**
|
||||
1. [Most critical action — e.g. "Upgrade lodash from 4.17.11 to 4.17.21 to fix CVE-2021-23337 (Critical — prototype pollution)"]
|
||||
2. [Second action]
|
||||
3. [Third action]
|
||||
|
||||
---
|
||||
|
||||
## 1. Security Vulnerability Findings
|
||||
|
||||
### Critical and High Severity (Act within 24–72 hours)
|
||||
|
||||
| Package | Installed version | Fix version | CVE | Severity | CVSS score | Description | Exploitability |
|
||||
|---|---|---|---|---|---|---|---|
|
||||
| [package-name] | [X.Y.Z] | [A.B.C] | [CVE-YYYY-NNNNN] | Critical | [9.x] | [e.g. Prototype pollution via `merge` function — remote code execution possible] | [Known exploit / PoC available / No known exploit] |
|
||||
| [package-name] | [X.Y.Z] | [A.B.C] | [CVE-YYYY-NNNNN] | High | [7.x] | [e.g. Path traversal in file serving utility] | [PoC available] |
|
||||
| [package-name] | [X.Y.Z] | [A.B.C] | [CVE-YYYY-NNNNN] | High | [7.x] | [e.g. Regular expression denial of service (ReDoS)] | [No known exploit] |
|
||||
|
||||
### Medium Severity (Fix within 30 days)
|
||||
|
||||
| Package | Installed version | Fix version | CVE | Severity | CVSS score | Description |
|
||||
|---|---|---|---|---|---|---|
|
||||
| [package-name] | [X.Y.Z] | [A.B.C] | [CVE-YYYY-NNNNN] | Medium | [5.x] | [Description] |
|
||||
| [package-name] | [X.Y.Z] | [A.B.C] | [CVE-YYYY-NNNNN] | Medium | [4.x] | [Description] |
|
||||
|
||||
### Low Severity (Fix within 90 days or accept risk)
|
||||
|
||||
| Package | Installed version | Fix version | CVE | Severity | Description |
|
||||
|---|---|---|---|---|---|
|
||||
| [package-name] | [X.Y.Z] | [A.B.C] | Low | [Description] |
|
||||
|
||||
### Vulnerabilities With No Fix Available
|
||||
|
||||
| Package | CVE | Severity | Recommended mitigation |
|
||||
|---|---|---|---|
|
||||
| [package-name] | [CVE-YYYY-NNNNN] | [High] | [e.g. "Remove this package — alternative: [replacement]"] |
|
||||
| [package-name] | [CVE-YYYY-NNNNN] | [Medium] | [e.g. "Vendor has a fix in progress — track issue [URL]. Mitigate by [X]"] |
|
||||
|
||||
---
|
||||
|
||||
## 2. License Compliance Matrix
|
||||
|
||||
### License Policy Reference
|
||||
|
||||
| License | Category | Policy | Notes |
|
||||
|---|---|---|---|
|
||||
| MIT | Permissive | Allowed | Attribution required in distributed products |
|
||||
| Apache 2.0 | Permissive | Allowed | Attribution + NOTICE file required |
|
||||
| BSD 2-Clause / 3-Clause | Permissive | Allowed | Attribution required |
|
||||
| ISC | Permissive | Allowed | |
|
||||
| MPL 2.0 | Weak copyleft | Allowed with review | Source disclosure required for modified MPL files only |
|
||||
| LGPL v2 / v3 | Weak copyleft | Allowed with review | Dynamic linking permitted; static linking may require disclosure |
|
||||
| GPL v2 / v3 | Strong copyleft | **Restricted** | May require open-sourcing the entire codebase — legal review required |
|
||||
| AGPL v3 | Strong copyleft | **Restricted** | Network use triggers copyleft — especially risky for SaaS |
|
||||
| SSPL | Source available | **Prohibited** | Not OSI-approved — treat as proprietary |
|
||||
| Proprietary / Commercial | Commercial | **Requires contract** | Verify license covers current use case and scale |
|
||||
| Unknown / Unlicensed | — | **Prohibited** | No license = all rights reserved — cannot use legally |
|
||||
|
||||
### Findings: Packages With Compliance Issues
|
||||
|
||||
| Package | License | Issue | Recommendation | Risk if unaddressed |
|
||||
|---|---|---|---|---|
|
||||
| [package-name] | GPL v3 | Copyleft — may require open-sourcing this project | Replace with [alternative] or get legal sign-off | Legal / IP risk |
|
||||
| [package-name] | AGPL v3 | Network copyleft — SaaS use triggers disclosure | Replace with [alternative] | Legal / IP risk |
|
||||
| [package-name] | Proprietary | License may not cover current usage tier | Verify license scope with vendor | Contract breach |
|
||||
| [package-name] | Unknown | No license declared in package metadata | Contact maintainer or replace | Cannot use legally |
|
||||
|
||||
### All Licenses in Use (Full Inventory)
|
||||
|
||||
| License | Package count | Compliance status |
|
||||
|---|---|---|
|
||||
| MIT | [N] | Compliant |
|
||||
| Apache 2.0 | [N] | Compliant |
|
||||
| BSD-3-Clause | [N] | Compliant |
|
||||
| ISC | [N] | Compliant |
|
||||
| MPL 2.0 | [N] | Review required |
|
||||
| GPL v3 | [N] | **Non-compliant** |
|
||||
| Unknown | [N] | **Non-compliant** |
|
||||
|
||||
---
|
||||
|
||||
## 3. Outdated Package Analysis
|
||||
|
||||
### Severely Outdated (2+ major versions behind — high upgrade effort)
|
||||
|
||||
| Package | Installed | Latest stable | Versions behind | Last updated | Breaking changes summary |
|
||||
|---|---|---|---|---|---|
|
||||
| [package-name] | [1.x.x] | [3.x.x] | 2 major | [Date] | [e.g. "API redesign in v2; async support added in v3"] |
|
||||
| [package-name] | [0.x.x] | [2.x.x] | 2 major | [Date] | [Summary] |
|
||||
|
||||
### Moderately Outdated (1 major version behind)
|
||||
|
||||
| Package | Installed | Latest stable | Versions behind | Security fix in newer version? |
|
||||
|---|---|---|---|---|
|
||||
| [package-name] | [2.x.x] | [3.x.x] | 1 major | [Yes — CVE-YYYY-NNNNN / No] |
|
||||
| [package-name] | [4.x.x] | [5.x.x] | 1 major | [No] |
|
||||
|
||||
### Minor/Patch Updates Available (Low risk to update)
|
||||
|
||||
| Package | Installed | Latest | Contains security fix? |
|
||||
|---|---|---|---|
|
||||
| [package-name] | [2.3.1] | [2.3.9] | [Yes / No] |
|
||||
| [package-name] | [1.0.0] | [1.2.1] | [No] |
|
||||
|
||||
---
|
||||
|
||||
## 4. Dependency Graph Risk Analysis
|
||||
|
||||
### Transitive Dependency Risk
|
||||
|
||||
Transitive (indirect) dependencies carry risk because they are not explicitly managed. These are the highest-risk transitive dependencies in this project:
|
||||
|
||||
| Vulnerable transitive dep | Pulled in by | Installed version | Fix available | Action |
|
||||
|---|---|---|---|---|
|
||||
| [transitive-package] | [direct-parent] | [X.Y.Z] | [Yes — upgrade [parent] to [version]] | Upgrade direct dependency [parent] |
|
||||
| [transitive-package] | [direct-parent] | [X.Y.Z] | [No] | Remove [parent] or use [alternative] |
|
||||
|
||||
### Dependency Concentration Risk
|
||||
|
||||
These packages are depended on by many other packages in the project — a vulnerability or deprecation would have cascading effects:
|
||||
|
||||
| Package | Depended on by (N packages) | Actively maintained? | Risk level |
|
||||
|---|---|---|---|
|
||||
| [package-name] | [N] | [Yes / No — last commit: date] | [High / Medium] |
|
||||
| [package-name] | [N] | [Yes] | [Medium] |
|
||||
|
||||
### Abandoned / Unmaintained Packages
|
||||
|
||||
| Package | Last release | Last commit | Weekly downloads | Recommended alternative |
|
||||
|---|---|---|---|---|
|
||||
| [package-name] | [Date] | [Date] | [N] | [alternative-package] |
|
||||
| [package-name] | [Date] | [Date] | [N] | [Maintained fork: URL] |
|
||||
|
||||
---
|
||||
|
||||
## 5. Remediation Plan
|
||||
|
||||
### 30-Day Plan
|
||||
|
||||
**Week 1 — Critical vulnerabilities (Days 1–7)**
|
||||
|
||||
| Action | Owner | Package | Effort | Notes |
|
||||
|---|---|---|---|---|
|
||||
| Upgrade [package] [old] → [new] | [Name] | [package-name] | [30 min] | [No API changes / check breaking changes guide: URL] |
|
||||
| Replace [package] with [alternative] | [Name] | [package-name] | [2 hours] | [No fix available — must replace] |
|
||||
| Patch override for [transitive-dep] | [Name] | [transitive-dep] | [15 min] | [Add resolutions/overrides entry in manifest] |
|
||||
|
||||
```bash
|
||||
# Commands for Week 1 upgrades:
|
||||
|
||||
# npm
|
||||
npm install [package]@[target-version]
|
||||
npm audit fix --force # use with caution — may introduce breaking changes
|
||||
|
||||
# pip
|
||||
pip install --upgrade [package]==[target-version]
|
||||
pip-audit --fix # if using pip-audit
|
||||
|
||||
# Go
|
||||
go get [module]@[version]
|
||||
go mod tidy
|
||||
|
||||
# Maven
|
||||
# Update pom.xml version property, then:
|
||||
mvn versions:use-latest-releases -DallowMajorUpdates=false
|
||||
mvn dependency:resolve
|
||||
```
|
||||
|
||||
**Week 2 — High vulnerabilities and license violations (Days 8–14)**
|
||||
|
||||
| Action | Owner | Package | Effort | Notes |
|
||||
|---|---|---|---|---|
|
||||
| Upgrade [package] | [Name] | [package-name] | [1 hour] | |
|
||||
| Replace GPL-licensed [package] | [Name] | [package-name] | [4 hours] | [Alternative: [package]] |
|
||||
| Legal review for [package] license | Legal team | [package-name] | [Legal team SLA] | [Submit via [process]] |
|
||||
|
||||
**Week 3 — Medium vulnerabilities and abandoned packages (Days 15–21)**
|
||||
|
||||
| Action | Owner | Package | Effort | Notes |
|
||||
|---|---|---|---|---|
|
||||
| Upgrade [package] | [Name] | [package-name] | [30 min] | |
|
||||
| Replace abandoned [package] | [Name] | [package-name] | [2 hours] | [Maintained fork or alternative: [URL]] |
|
||||
|
||||
**Week 4 — Process improvements (Days 22–30)**
|
||||
|
||||
| Action | Owner | Effort | Notes |
|
||||
|---|---|---|---|
|
||||
| Enable Dependabot / Renovate for automated PRs | [Name] | [2 hours] | [Config in Section 6] |
|
||||
| Add `npm audit` / `pip-audit` to CI — fail on Critical/High | [Name] | [1 hour] | [Config in Section 6] |
|
||||
| Document license policy in CONTRIBUTING.md | [Name] | [1 hour] | [Based on policy in Section 2] |
|
||||
| Schedule next quarterly audit | [Name] | [15 min] | [Add to team calendar] |
|
||||
|
||||
---
|
||||
|
||||
## 6. Policy Recommendations
|
||||
|
||||
### Automated Vulnerability Scanning in CI
|
||||
|
||||
Add the following to your CI pipeline to catch vulnerabilities before they merge:
|
||||
|
||||
```yaml
|
||||
# GitHub Actions — adapt for your CI platform
|
||||
dependency-audit:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
|
||||
# npm
|
||||
- name: npm audit
|
||||
run: npm audit --audit-level=high
|
||||
# Fails build on High or Critical vulnerabilities
|
||||
|
||||
# pip
|
||||
- name: pip-audit
|
||||
run: |
|
||||
pip install pip-audit
|
||||
pip-audit --requirement requirements.txt --severity high
|
||||
|
||||
# Go
|
||||
- name: govulncheck
|
||||
run: |
|
||||
go install golang.org/x/vuln/cmd/govulncheck@latest
|
||||
govulncheck ./...
|
||||
```
|
||||
|
||||
### Dependabot / Renovate Configuration
|
||||
|
||||
```yaml
|
||||
# .github/dependabot.yml — automated dependency update PRs
|
||||
version: 2
|
||||
updates:
|
||||
- package-ecosystem: "[npm / pip / gomod / maven]"
|
||||
directory: "/"
|
||||
schedule:
|
||||
interval: "weekly"
|
||||
day: "monday"
|
||||
open-pull-requests-limit: 10
|
||||
labels:
|
||||
- "dependencies"
|
||||
- "automated"
|
||||
ignore:
|
||||
# Ignore major version bumps — review these manually
|
||||
- dependency-name: "*"
|
||||
update-types: ["version-update:semver-major"]
|
||||
```
|
||||
|
||||
### License Scanning
|
||||
|
||||
```bash
|
||||
# npm — license checker
|
||||
npx license-checker --onlyAllow 'MIT;Apache-2.0;BSD-2-Clause;BSD-3-Clause;ISC' \
|
||||
--failOn 'GPL;AGPL;LGPL'
|
||||
|
||||
# Python — pip-licenses
|
||||
pip install pip-licenses
|
||||
pip-licenses --allow-only="MIT;Apache Software License;BSD License;ISC License" \
|
||||
--fail-on="GNU General Public License"
|
||||
|
||||
# Go — go-licenses
|
||||
go install github.com/google/go-licenses@latest
|
||||
go-licenses check ./... --allowed_licenses=MIT,Apache-2.0,BSD-2-Clause,BSD-3-Clause
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Dependency Health Score Detail
|
||||
|
||||
| Category | Max points | Score | Notes |
|
||||
|---|---|---|---|
|
||||
| No critical vulnerabilities | 30 | [N]/30 | −20 per critical CVE |
|
||||
| No high vulnerabilities | 20 | [N]/20 | −10 per high CVE |
|
||||
| License compliance | 20 | [N]/20 | −15 per violation |
|
||||
| No abandoned packages | 15 | [N]/15 | −5 per abandoned package |
|
||||
| Up-to-date major versions | 10 | [N]/10 | −2 per major version behind |
|
||||
| Automated scanning enabled | 5 | [N]/5 | All-or-nothing |
|
||||
| **Total** | **100** | **[Score]/100** | **[Red / Amber / Green]** |
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Every Critical and High CVE has a named owner and a resolution date in the 30-day plan
|
||||
- [ ] License findings have been reviewed by legal or a named engineer with authority to accept the risk
|
||||
- [ ] Transitive dependency vulnerabilities are included — not just direct dependencies
|
||||
- [ ] Abandoned packages have a concrete replacement recommendation, not just "consider replacing"
|
||||
- [ ] CI pipeline change is included — the audit findings should be the last time these are caught manually
|
||||
- [ ] The dependency health score is calculated from actual findings, not estimated
|
||||
- [ ] Remediation plan actions are specific commands or steps, not "upgrade package X" without version targets
|
||||
@@ -0,0 +1,332 @@
|
||||
---
|
||||
name: developer-onboarding-doc
|
||||
description: "Write a developer onboarding document for a service, codebase, or team. Use when asked to write a developer guide, service README, onboarding doc for a new engineer, codebase orientation, or getting-started guide for a technical team. Produces a structured doc covering service overview, architecture, local setup, key patterns, testing, deployment, and who to ask for what."
|
||||
---
|
||||
|
||||
# Developer Onboarding Document Skill
|
||||
|
||||
Produce a complete developer onboarding document for a service or team — covering everything a new engineer needs to be productive within their first week.
|
||||
|
||||
A good onboarding doc is not a wiki dump. It answers the questions a new engineer actually has on day one, in the order they'll have them.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask for these if not already provided:
|
||||
- **Service name** and what it does
|
||||
- **Team** responsible for it
|
||||
- **Tech stack** — language(s), framework(s), database(s), message queues, etc.
|
||||
- **Key external dependencies** — upstream services, third-party APIs
|
||||
- **Deployment target** — Kubernetes, ECS, Lambda, bare metal, etc.
|
||||
- **Local dev setup** — how to run locally (Docker Compose, local DB, etc.)
|
||||
- **Testing approach** — unit, integration, E2E; test commands
|
||||
- **Deployment process** — summary of how code gets to production
|
||||
- **On-call setup** — who's on-call, how alerts work
|
||||
- **Contacts** — tech lead, platform team, related service owners
|
||||
|
||||
## Output Format
|
||||
|
||||
---
|
||||
|
||||
# Developer Onboarding: [Service Name]
|
||||
|
||||
**Team:** [Team name] | **Tech lead:** [Name]
|
||||
**Last updated:** [Date] | **Updated by:** [Name]
|
||||
|
||||
> If something in this doc is wrong or out of date, fix it now — it will affect every engineer who onboards after you.
|
||||
|
||||
---
|
||||
|
||||
## What This Service Does
|
||||
|
||||
[3–5 sentences. What problem does this service solve? Who calls it, and who does it call? What would break if this service went down?]
|
||||
|
||||
**Service type:** [API / Background worker / Event consumer / Data pipeline / etc.]
|
||||
**Consumers:** [List internal services or external clients that depend on this service]
|
||||
**Dependencies:** [List upstream services, databases, and third-party APIs this service calls]
|
||||
|
||||
**Architecture diagram:** [Link or embed — even a rough ASCII diagram helps]
|
||||
|
||||
```
|
||||
[Caller A] ──→ [This Service] ──→ [Database]
|
||||
│
|
||||
└──→ [Downstream Service]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Codebase Orientation
|
||||
|
||||
**Repository:** [Link]
|
||||
**Main branch:** `[main / master]`
|
||||
**Language:** [e.g. Go 1.22 / Node.js 20 / Python 3.12]
|
||||
**Framework:** [e.g. Express / FastAPI / Gin / Rails]
|
||||
|
||||
### Key directories
|
||||
|
||||
```
|
||||
[repo-root]/
|
||||
├── [src/ or cmd/] # Application code
|
||||
│ ├── [handlers/] # HTTP handlers / controllers
|
||||
│ ├── [services/] # Business logic
|
||||
│ ├── [repository/] # Database access layer
|
||||
│ └── [models/] # Data models / types
|
||||
├── [tests/] # Test files
|
||||
├── [migrations/] # Database migrations
|
||||
├── [scripts/] # Utility scripts
|
||||
├── [.github/workflows/] # CI/CD pipeline definitions
|
||||
└── [docs/] # Additional documentation
|
||||
```
|
||||
|
||||
**Where to start reading:** [Point to 2–3 key files that give the best orientation — e.g. `main.go`, `routes.js`, `app.py`]
|
||||
|
||||
### Things that might surprise you
|
||||
|
||||
- [Unusual pattern 1 — e.g. "We use event sourcing — state is derived from an event log, not stored directly"]
|
||||
- [Unusual pattern 2 — e.g. "Auth is handled by the gateway — this service trusts the `X-User-Id` header"]
|
||||
- [Unusual pattern 3 — any non-obvious decisions or legacy choices]
|
||||
|
||||
---
|
||||
|
||||
## Local Development Setup
|
||||
|
||||
**Estimated setup time:** [X minutes for a fresh machine]
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- [ ] [Tool 1] — version [X] — [install link]
|
||||
- [ ] [Tool 2] — version [X] — [install link]
|
||||
- [ ] Access to [repo / internal package registry] — request from [who]
|
||||
- [ ] [Any secrets or credentials needed] — request from [who]
|
||||
|
||||
### Step-by-step setup
|
||||
|
||||
```bash
|
||||
# 1. Clone the repo
|
||||
git clone [repo URL]
|
||||
cd [repo-name]
|
||||
|
||||
# 2. Copy and configure environment variables
|
||||
cp .env.example .env
|
||||
# Edit .env — see "Environment Variables" section below
|
||||
|
||||
# 3. Start dependencies (database, cache, etc.)
|
||||
[docker compose up -d / make deps / etc.]
|
||||
|
||||
# 4. Install dependencies
|
||||
[npm install / go mod download / pip install -r requirements.txt]
|
||||
|
||||
# 5. Run database migrations
|
||||
[migration command]
|
||||
|
||||
# 6. Start the service
|
||||
[start command]
|
||||
|
||||
# 7. Verify it's working
|
||||
curl http://localhost:[PORT]/health
|
||||
# Expected: {"status":"ok"}
|
||||
```
|
||||
|
||||
**If this doesn't work:** Check [Troubleshooting section below] or ask in `#[channel]`.
|
||||
|
||||
### Environment Variables
|
||||
|
||||
| Variable | Required | Description | Example |
|
||||
|---|---|---|---|
|
||||
| `DATABASE_URL` | Yes | Connection string for the primary DB | `postgres://localhost:5432/[db]` |
|
||||
| `[VAR_2]` | Yes | [Description] | [Example] |
|
||||
| `[VAR_3]` | No | [Description — default value] | [Example] |
|
||||
|
||||
**Secrets for local dev:** [Where to get them — e.g. "Run `[command]` to pull from Vault" or "Ask [person] in #[channel]"]
|
||||
|
||||
### Useful local commands
|
||||
|
||||
```bash
|
||||
[start command] # Start the service
|
||||
[test command] # Run all tests
|
||||
[lint command] # Run linter
|
||||
[format command] # Format code
|
||||
[migration command] # Run pending migrations
|
||||
[seed command] # Seed local database
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
**Testing philosophy:** [e.g. "We test at the integration layer — unit tests for pure functions, integration tests for anything touching the DB or external services"]
|
||||
|
||||
### Running tests
|
||||
|
||||
```bash
|
||||
# All tests
|
||||
[test command]
|
||||
|
||||
# Unit tests only
|
||||
[unit test command]
|
||||
|
||||
# Integration tests (requires local deps running)
|
||||
[integration test command]
|
||||
|
||||
# A specific test file or test case
|
||||
[test command with filter]
|
||||
```
|
||||
|
||||
**Test coverage:** [X]% (minimum required to pass CI: [Y]%)
|
||||
**Coverage report:** [Where to find it]
|
||||
|
||||
### Writing tests
|
||||
|
||||
- **Unit tests:** [Where to put them — e.g. alongside source files as `*_test.go`]
|
||||
- **Integration tests:** [Where to put them — e.g. `tests/integration/`]
|
||||
- **Test database:** [How it works — e.g. "Each test gets a clean transaction that rolls back on teardown — see `tests/helpers/db.go`"]
|
||||
- **Mocking:** [Policy — e.g. "We mock at the repository layer — don't mock the DB directly"]
|
||||
|
||||
---
|
||||
|
||||
## Making Changes
|
||||
|
||||
### Branching
|
||||
|
||||
[Branch naming convention — e.g. `feature/[ticket-id]-short-description`, `fix/[ticket-id]-short-description`]
|
||||
|
||||
### Before opening a PR
|
||||
|
||||
- [ ] Tests pass locally
|
||||
- [ ] Linter passes (`[lint command]`)
|
||||
- [ ] New behaviour has test coverage
|
||||
- [ ] Any new environment variables are added to `.env.example` and documented
|
||||
- [ ] Database migrations are backward-compatible (old code can run against new schema)
|
||||
|
||||
### Code review
|
||||
|
||||
- **Reviewers:** [Who to request review from — e.g. "Any engineer on [team]; lead review required for auth changes"]
|
||||
- **Expected review time:** [X hours / 1 business day]
|
||||
- **PR template:** [Link or auto-generated by GitHub]
|
||||
|
||||
### Database migrations
|
||||
|
||||
```bash
|
||||
# Create a new migration
|
||||
[migration create command]
|
||||
|
||||
# Apply pending migrations
|
||||
[migration up command]
|
||||
|
||||
# Roll back last migration
|
||||
[migration down command]
|
||||
```
|
||||
|
||||
**Migration rules:**
|
||||
- All migrations must be backward-compatible — old code must run against the new schema
|
||||
- Never rename or drop a column in a single migration — do it in two steps (add new, migrate data, drop old)
|
||||
- Test your rollback before merging
|
||||
|
||||
---
|
||||
|
||||
## Deployment
|
||||
|
||||
**How code gets to production:** [1–2 sentence summary — link to full CI/CD playbook if it exists]
|
||||
|
||||
1. Merge to `main` → automatic deploy to staging
|
||||
2. Smoke tests run on staging
|
||||
3. Manual approval → deploy to production
|
||||
4. Post-deploy monitoring for [X minutes]
|
||||
|
||||
**Deployment docs:** [Link to CI/CD playbook or pipeline docs]
|
||||
|
||||
**Who can deploy:** [Any engineer / Lead engineer / On-call engineer — specify]
|
||||
|
||||
**Deployment channel:** `#[deployments channel]`
|
||||
|
||||
---
|
||||
|
||||
## Monitoring and Observability
|
||||
|
||||
**Dashboard:** [Datadog / Grafana / CloudWatch — link]
|
||||
**Logs:** [Log aggregation tool and link — e.g. "Logs are in Datadog under service:[name]"]
|
||||
**Traces:** [Tracing tool and link if applicable]
|
||||
**Alerts:** [Where alerts fire — e.g. PagerDuty / Slack #alerts-[service]]
|
||||
|
||||
**Key metrics to know:**
|
||||
- **Error rate:** Should be <[X]% (alert at [Y]%)
|
||||
- **P99 latency:** Should be <[X]ms
|
||||
- **[Business metric]:** [e.g. "Queue depth should be <100 items"]
|
||||
|
||||
---
|
||||
|
||||
## On-Call
|
||||
|
||||
**On-call schedule:** [PagerDuty / Opsgenie link]
|
||||
**Who's on-call now:** [Link to current schedule or `#oncall` channel]
|
||||
**Escalation:** [On-call → [team lead] → [EM] — after [X] minutes unacknowledged]
|
||||
|
||||
**If you get paged:**
|
||||
1. Acknowledge the alert
|
||||
2. Check [dashboard link] for the first clue
|
||||
3. Common alert runbooks: [link to oncall-runbook or runbook-writer output]
|
||||
4. If you can't resolve in [X minutes], escalate to [person/channel]
|
||||
|
||||
---
|
||||
|
||||
## Key Contacts
|
||||
|
||||
| Role | Name | Best way to reach |
|
||||
|---|---|---|
|
||||
| Tech lead | [Name] | Slack: @[handle] |
|
||||
| On-call rotation | [Team] | PagerDuty / `#on-call` |
|
||||
| Platform / infra | [Team] | `#platform` Slack channel |
|
||||
| Database / DBA | [Name or team] | `#database` Slack channel |
|
||||
| [Upstream service] owner | [Name] | Slack: @[handle] |
|
||||
|
||||
**Where to ask questions:**
|
||||
- General engineering: `#engineering`
|
||||
- This service specifically: `#[service-name]`
|
||||
- Urgent / production issues: `#incidents`
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "The service won't start locally"
|
||||
|
||||
1. Check that Docker / dependencies are running: `[command]`
|
||||
2. Check `.env` is populated — missing values cause silent failures
|
||||
3. Check logs: `[log command]`
|
||||
4. Ask in `#[channel]`
|
||||
|
||||
### "Tests are failing locally but passing in CI"
|
||||
|
||||
- Check your local dependency versions match CI: `[version check command]`
|
||||
- Try a clean install: `[clean install command]`
|
||||
- Integration tests need local deps running — `[start deps command]`
|
||||
|
||||
### "I can't access [internal tool / system]"
|
||||
|
||||
- Request access through [process — e.g. Okta self-serve / ask your manager]
|
||||
|
||||
### "Something looks wrong in production"
|
||||
|
||||
1. Check [dashboard] for the error spike
|
||||
2. Check recent deploys in `#deployments`
|
||||
3. If it's an active incident, page on-call via [PagerDuty / Slack command]
|
||||
|
||||
---
|
||||
|
||||
## Further Reading
|
||||
|
||||
- [Architecture Decision Records (ADRs)](./docs/decisions/) — why the codebase is the way it is
|
||||
- [API documentation](./docs/api/) or [link to external docs]
|
||||
- [Incident runbooks](./docs/runbooks/)
|
||||
- [CI/CD pipeline documentation](./docs/cicd/)
|
||||
- [Team working agreements](./docs/team/)
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Local setup instructions work on a fresh machine — tested recently
|
||||
- [ ] Environment variables table is complete and accurate
|
||||
- [ ] "Things that might surprise you" captures the actual surprises (ask a recent joiner)
|
||||
- [ ] On-call section has real links, not placeholders
|
||||
- [ ] Contacts are current — team members with real Slack handles
|
||||
- [ ] Troubleshooting covers the top 3 actual questions new joiners ask
|
||||
@@ -0,0 +1,560 @@
|
||||
---
|
||||
name: disaster-recovery-plan
|
||||
description: "Write a disaster recovery plan for a service or system — covering RPO/RTO targets, failure scenario runbooks, backup and restore procedures, DR testing cadence, and communication templates. Use when asked to write a DR plan, document failover procedures, create recovery runbooks, define RTO/RPO targets, or prepare for a disaster recovery game day. Produces a full DR document with per-scenario recovery runbooks, backup validation procedures, testing schedule, and communication templates."
|
||||
---
|
||||
|
||||
# Disaster Recovery Plan Skill
|
||||
|
||||
Produce a complete disaster recovery plan for a service or system — giving engineers, SREs, and on-call responders everything they need to recover from a disaster scenario in the shortest possible time. A good DR plan is tested regularly, has exact commands (not vague instructions), and makes RTO/RPO targets measurable so the team knows whether recovery succeeded.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask for these if not already provided:
|
||||
- **Service name** and what it does (business function and technical role)
|
||||
- **Criticality tier** — business impact of extended downtime (e.g. Tier 1 = revenue-critical, Tier 2 = ops impact, Tier 3 = internal only)
|
||||
- **Current infrastructure setup** — cloud provider, regions/zones, deployment model (Kubernetes, ECS, VMs, serverless)
|
||||
- **RPO/RTO requirements** — Recovery Point Objective (how much data loss is acceptable) and Recovery Time Objective (how long can it be down)
|
||||
- **Backup strategy** — what is backed up, how often, where backups are stored, retention policy
|
||||
- **On-call contacts** — names and contact details for the responder chain
|
||||
|
||||
## Output Format
|
||||
|
||||
---
|
||||
|
||||
# Disaster Recovery Plan: [Service Name]
|
||||
|
||||
**Team:** [Team name] | **Tech lead:** [Name]
|
||||
**Criticality tier:** [Tier 1 / Tier 2 / Tier 3] | **Last tested:** [Date]
|
||||
**Next DR test:** [Date] | **Document owner:** [Name]
|
||||
**Last updated:** [Date] | **Review cycle:** Quarterly
|
||||
|
||||
> **Emergency? Skip to Section 3 — Failure Scenario Runbooks.** Find the scenario that matches your situation and follow the steps exactly.
|
||||
|
||||
---
|
||||
|
||||
## 1. Recovery Targets
|
||||
|
||||
| Target | Value | Rationale |
|
||||
|---|---|---|
|
||||
| RPO (Recovery Point Objective) | [X minutes/hours] | [e.g. "Last committed transaction — database replication is synchronous"] |
|
||||
| RTO (Recovery Time Objective) | [Y minutes/hours] | [e.g. "Revenue impact begins at 30 min; target recovery in 15 min"] |
|
||||
| MTTR target (non-disaster) | [Z minutes] | [Operational incidents, not DR events] |
|
||||
| Data retention (backups) | [N days/weeks] | [Compliance requirement or operational policy] |
|
||||
| Backup frequency | [Every X hours] | [RPO-driven — backup interval must be ≤ RPO] |
|
||||
|
||||
**What these mean in practice:**
|
||||
- If a database is corrupted, we can lose at most [X minutes] of transactions before the business impact is unacceptable.
|
||||
- The service must be operational again within [Y minutes/hours] of declaring a DR event.
|
||||
- If either target cannot be met, escalate to [Engineering Manager] immediately.
|
||||
|
||||
---
|
||||
|
||||
## 2. Failure Scenario Inventory
|
||||
|
||||
| Scenario | Likelihood | Impact | RTO target | RPO target | Runbook |
|
||||
|---|---|---|---|---|---|
|
||||
| Single availability zone failure | Medium | [Partial / Full outage] | [15 min] | [0 — no data loss] | Section 3.1 |
|
||||
| Full region failure | Low | Full outage | [60 min] | [5 min] | Section 3.2 |
|
||||
| Database corruption / data loss | Low | Full outage | [90 min] | [RPO value] | Section 3.3 |
|
||||
| Critical dependency outage | High | [Partial degradation] | [30 min] | [N/A] | Section 3.4 |
|
||||
| Security breach / ransomware | Very low | Full outage + investigation | [4 hours] | [Last clean backup] | Section 3.5 |
|
||||
| Accidental bulk data deletion | Low | Partial or full data loss | [60 min] | [RPO value] | Section 3.6 |
|
||||
|
||||
---
|
||||
|
||||
## 3. Failure Scenario Runbooks
|
||||
|
||||
### 3.1 Single Availability Zone Failure
|
||||
|
||||
**Trigger:** One AZ becomes unreachable — pods/instances in that zone stop responding.
|
||||
**Detection:** PagerDuty alert `[AlertName]` fires, or cloud provider status page shows AZ degradation.
|
||||
**Expected RTO:** [15 minutes] | **Expected RPO:** Zero (no data loss if multi-AZ replication is working)
|
||||
|
||||
**Step 1 — Confirm the failure**
|
||||
```bash
|
||||
# Check pod/instance health across zones
|
||||
kubectl get pods -o wide -n [namespace] | grep -v Running
|
||||
|
||||
# Check which nodes are affected
|
||||
kubectl get nodes -o wide | grep -v Ready
|
||||
|
||||
# Verify cloud provider AZ status
|
||||
# AWS: https://health.aws.amazon.com/health/status
|
||||
# GCP: https://status.cloud.google.com
|
||||
```
|
||||
|
||||
**Step 2 — Assess whether auto-recovery has occurred**
|
||||
```bash
|
||||
# If using auto-scaling, check if replacement instances launched
|
||||
kubectl get pods -n [namespace] --watch
|
||||
|
||||
# Check deployment replica count
|
||||
kubectl get deployment [service-name] -n [namespace]
|
||||
|
||||
# Verify load balancer health checks are passing
|
||||
[cloud provider CLI command to check target group health]
|
||||
```
|
||||
|
||||
**Step 3 — Force rescheduling if auto-recovery stalled**
|
||||
```bash
|
||||
# Cordon the affected node so no new pods schedule on it
|
||||
kubectl cordon [node-name]
|
||||
|
||||
# Drain the node — moves all pods to healthy nodes
|
||||
kubectl drain [node-name] --ignore-daemonsets --delete-emptydir-data
|
||||
|
||||
# Verify pods have rescheduled successfully
|
||||
kubectl get pods -o wide -n [namespace]
|
||||
```
|
||||
|
||||
**Step 4 — Verify service health**
|
||||
```bash
|
||||
# Smoke test key endpoints
|
||||
curl -s -o /dev/null -w "%{http_code}" https://[service-url]/health
|
||||
curl -s -o /dev/null -w "%{http_code}" https://[service-url]/[critical-endpoint]
|
||||
|
||||
# Check error rate in monitoring
|
||||
[dashboard link or query]
|
||||
```
|
||||
|
||||
**Recovery confirmed when:** All pods are Running, health check returns 200, error rate is at baseline.
|
||||
|
||||
---
|
||||
|
||||
### 3.2 Full Region Failure
|
||||
|
||||
**Trigger:** The primary region is entirely unavailable.
|
||||
**Detection:** All service health checks failing, cloud provider status page confirms region-wide event.
|
||||
**Expected RTO:** [60 minutes] | **Expected RPO:** [5 minutes — based on cross-region replication lag]
|
||||
|
||||
**Step 1 — Confirm regional failure (5 minutes)**
|
||||
```bash
|
||||
# Confirm the primary region is unreachable
|
||||
ping [primary-region-endpoint] || echo "Primary region unreachable"
|
||||
|
||||
# Check replication lag on standby region database
|
||||
[command to check replica lag — e.g. for RDS: aws rds describe-db-instances --region [dr-region]]
|
||||
```
|
||||
|
||||
**Step 2 — Declare DR event and notify (2 minutes)**
|
||||
|
||||
Post to `#incidents`:
|
||||
```
|
||||
🔴 DR EVENT — [Service Name] — Region Failure
|
||||
Primary region: [region] — UNREACHABLE
|
||||
Activating failover to: [dr-region]
|
||||
Incident commander: [Name]
|
||||
Next update: 15 minutes
|
||||
```
|
||||
|
||||
Page [Engineering Manager] and [CTO/VP Eng] via PagerDuty.
|
||||
|
||||
**Step 3 — Promote DR database (10 minutes)**
|
||||
```bash
|
||||
# AWS RDS — promote read replica to primary
|
||||
aws rds promote-read-replica \
|
||||
--db-instance-identifier [dr-replica-identifier] \
|
||||
--region [dr-region]
|
||||
|
||||
# Wait for promotion to complete
|
||||
aws rds wait db-instance-available \
|
||||
--db-instance-identifier [dr-replica-identifier] \
|
||||
--region [dr-region]
|
||||
|
||||
# Record the new database endpoint
|
||||
aws rds describe-db-instances \
|
||||
--db-instance-identifier [dr-replica-identifier] \
|
||||
--region [dr-region] \
|
||||
--query 'DBInstances[0].Endpoint.Address'
|
||||
```
|
||||
|
||||
**Step 4 — Deploy service in DR region (20 minutes)**
|
||||
```bash
|
||||
# Update service configuration to point at DR database
|
||||
kubectl set env deployment/[service-name] \
|
||||
DATABASE_URL=[new-dr-database-url] \
|
||||
-n [namespace] \
|
||||
--context [dr-region-context]
|
||||
|
||||
# Scale up the DR deployment
|
||||
kubectl scale deployment/[service-name] --replicas=[N] \
|
||||
-n [namespace] \
|
||||
--context [dr-region-context]
|
||||
|
||||
# Verify all pods are running
|
||||
kubectl get pods -n [namespace] --context [dr-region-context]
|
||||
```
|
||||
|
||||
**Step 5 — Cut over DNS / load balancer (5 minutes)**
|
||||
```bash
|
||||
# Update DNS to point to DR region load balancer
|
||||
# AWS Route 53:
|
||||
aws route53 change-resource-record-sets \
|
||||
--hosted-zone-id [zone-id] \
|
||||
--change-batch file://dr-failover-dns.json
|
||||
|
||||
# Verify DNS propagation (may take up to [TTL] seconds)
|
||||
dig [service-domain] @8.8.8.8
|
||||
```
|
||||
|
||||
**Step 6 — Verify end-to-end**
|
||||
```bash
|
||||
# Full smoke test against DR endpoint
|
||||
curl -s https://[service-url]/health
|
||||
[run automated smoke test suite if available]
|
||||
```
|
||||
|
||||
**Recovery confirmed when:** DNS resolves to DR region, smoke tests pass, error rate is at baseline.
|
||||
|
||||
**Post-failover actions (not urgent — after service is stable):**
|
||||
- Do not fail back to primary until root cause is confirmed resolved
|
||||
- Document data loss window (check replication lag at time of failure)
|
||||
- Begin post-incident review — see [incident-postmortem skill]
|
||||
|
||||
---
|
||||
|
||||
### 3.3 Database Corruption or Data Loss
|
||||
|
||||
**Trigger:** Data in the database is corrupted, deleted, or otherwise incorrect due to a software bug, operator error, or hardware fault.
|
||||
**Detection:** Application errors referencing missing/invalid data, monitoring alerts on query error rate, user reports.
|
||||
**Expected RTO:** [90 minutes] | **Expected RPO:** [Backup interval — e.g. 1 hour]
|
||||
|
||||
**Step 1 — Stop the bleeding immediately**
|
||||
```bash
|
||||
# Put the service into maintenance mode to prevent further writes to corrupted data
|
||||
[command to enable maintenance mode — e.g. kubectl set env deployment/[name] MAINTENANCE_MODE=true]
|
||||
|
||||
# Or: scale down the service to zero to prevent writes
|
||||
kubectl scale deployment/[service-name] --replicas=0 -n [namespace]
|
||||
```
|
||||
|
||||
**Step 2 — Assess scope of corruption**
|
||||
```bash
|
||||
# Identify which tables/records are affected
|
||||
[SQL query to check data integrity — e.g.]
|
||||
# psql $DATABASE_URL -c "SELECT COUNT(*) FROM [table] WHERE [integrity check condition]"
|
||||
|
||||
# Determine when corruption started (cross-reference with deploy times and error logs)
|
||||
[log query to find earliest error — e.g. in Datadog:]
|
||||
# service:[service-name] status:error "[corruption error message]" | sort by timestamp asc
|
||||
```
|
||||
|
||||
**Step 3 — Identify the correct restore point**
|
||||
```bash
|
||||
# List available backups
|
||||
[command to list backups — e.g. for RDS:]
|
||||
aws rds describe-db-snapshots \
|
||||
--db-instance-identifier [db-identifier] \
|
||||
--query 'DBSnapshots[*].[SnapshotCreateTime,DBSnapshotIdentifier]' \
|
||||
--output table
|
||||
|
||||
# Choose the most recent backup BEFORE corruption started
|
||||
# Record the chosen snapshot ID: [snapshot-id]
|
||||
```
|
||||
|
||||
**Step 4 — Restore from backup**
|
||||
```bash
|
||||
# Restore to a NEW database instance (never overwrite production directly)
|
||||
aws rds restore-db-instance-from-db-snapshot \
|
||||
--db-instance-identifier [service-name]-restored-[date] \
|
||||
--db-snapshot-identifier [snapshot-id] \
|
||||
--region [region]
|
||||
|
||||
# Wait for restore to complete
|
||||
aws rds wait db-instance-available \
|
||||
--db-instance-identifier [service-name]-restored-[date]
|
||||
|
||||
# Get the restored instance endpoint
|
||||
aws rds describe-db-instances \
|
||||
--db-instance-identifier [service-name]-restored-[date] \
|
||||
--query 'DBInstances[0].Endpoint.Address'
|
||||
```
|
||||
|
||||
**Step 5 — Validate restored data**
|
||||
```bash
|
||||
# Connect to restored database and verify integrity
|
||||
psql [restored-db-endpoint] -U [user] -d [database] -c "[data integrity query]"
|
||||
|
||||
# Confirm record counts match expectations
|
||||
psql [restored-db-endpoint] -U [user] -d [database] -c "SELECT COUNT(*) FROM [critical-table]"
|
||||
```
|
||||
|
||||
**Step 6 — Point service at restored database**
|
||||
```bash
|
||||
kubectl set env deployment/[service-name] \
|
||||
DATABASE_URL=postgres://[user]:[pass]@[restored-endpoint]/[db] \
|
||||
-n [namespace]
|
||||
|
||||
kubectl scale deployment/[service-name] --replicas=[N] -n [namespace]
|
||||
```
|
||||
|
||||
**Recovery confirmed when:** Service is running against restored database, data integrity checks pass, error rate is at baseline.
|
||||
|
||||
---
|
||||
|
||||
### 3.4 Critical Dependency Outage
|
||||
|
||||
**Trigger:** A service that [service name] depends on is unavailable or degraded.
|
||||
**Detection:** Increased error rate or latency on endpoints that call [dependency], alerts from dependency owner.
|
||||
**Expected RTO:** Depends on dependency — [30 minutes for mitigation, resolution depends on dependency owner]
|
||||
|
||||
**Dependency map:**
|
||||
|
||||
| Dependency | Criticality | Degraded behaviour | Mitigation |
|
||||
|---|---|---|---|
|
||||
| [Database] | Critical — all writes fail | Full outage | Activate DR database (Section 3.3) |
|
||||
| [Cache — Redis] | High — latency increases | Performance degradation | Bypass cache, serve from DB |
|
||||
| [Auth service] | Critical — auth fails | All authenticated endpoints fail | Return cached tokens (if implemented) |
|
||||
| [Message queue] | Medium — async processing delays | Writes succeed, async jobs queue | Queue backlog — see on-call runbook |
|
||||
| [External API — name] | Low — feature X unavailable | Graceful degradation | Feature flag to disable feature X |
|
||||
|
||||
**Mitigation steps:**
|
||||
```bash
|
||||
# Enable circuit breaker / fallback for [dependency] if implemented
|
||||
kubectl set env deployment/[service-name] [DEPENDENCY]_CIRCUIT_BREAKER=open -n [namespace]
|
||||
|
||||
# Enable feature flag to disable [dependency-backed feature]
|
||||
[feature flag CLI command or dashboard link]
|
||||
|
||||
# Check if dependency has a status page
|
||||
# [Dependency status URL]
|
||||
```
|
||||
|
||||
**Escalation:** Contact [dependency] on-call via [PagerDuty / Slack `#[channel]`]. Share your service's error rate and the time dependency errors started.
|
||||
|
||||
---
|
||||
|
||||
### 3.5 Security Breach or Ransomware
|
||||
|
||||
**Trigger:** Evidence of unauthorized access, data exfiltration, or encryption of service data.
|
||||
**Detection:** Security tooling alert, unusual access patterns, user reports of data exposure.
|
||||
**Expected RTO:** [4+ hours — prioritise containment over speed] | **Expected RPO:** [Last verified clean backup]
|
||||
|
||||
**Step 1 — Isolate immediately**
|
||||
```bash
|
||||
# Take the service offline — do not attempt to recover while breach is active
|
||||
kubectl scale deployment/[service-name] --replicas=0 -n [namespace]
|
||||
|
||||
# Revoke all API keys and service account credentials immediately
|
||||
[command to rotate secrets — e.g. via Vault or cloud provider]
|
||||
|
||||
# Block all external access at network level
|
||||
[firewall/security group command to deny all inbound traffic]
|
||||
```
|
||||
|
||||
**Step 2 — Notify security team immediately**
|
||||
Page [Security lead] via PagerDuty. Do NOT attempt to remediate without security team involvement.
|
||||
|
||||
Post to `#security-incidents` (private channel, not `#incidents`):
|
||||
```
|
||||
🔴 SECURITY INCIDENT — [Service Name]
|
||||
Time detected: [Time]
|
||||
Evidence: [One sentence — what was observed]
|
||||
Actions taken: Service isolated, credentials revoked
|
||||
Awaiting: Security team guidance
|
||||
```
|
||||
|
||||
**Step 3 — Preserve evidence**
|
||||
```bash
|
||||
# Export current logs before any remediation
|
||||
[log export command — preserve evidence for forensics]
|
||||
|
||||
# Snapshot the current state of all infrastructure
|
||||
[snapshot/image command]
|
||||
```
|
||||
|
||||
**Steps 4+ — Follow security team guidance.** Do not restore from backup until security team confirms the attack vector is closed.
|
||||
|
||||
---
|
||||
|
||||
### 3.6 Accidental Bulk Data Deletion
|
||||
|
||||
**Trigger:** An operator, script, or application bug has deleted records in bulk.
|
||||
**Detection:** Sudden drop in record counts, user reports of missing data, application errors.
|
||||
**Expected RTO:** [60 minutes] | **Expected RPO:** [Backup interval]
|
||||
|
||||
```bash
|
||||
# Step 1 — Stop further writes immediately
|
||||
kubectl scale deployment/[service-name] --replicas=0 -n [namespace]
|
||||
|
||||
# Step 2 — Determine what was deleted and when
|
||||
psql $DATABASE_URL -c "
|
||||
SELECT schemaname, tablename,
|
||||
n_dead_tup, last_autovacuum
|
||||
FROM pg_stat_user_tables
|
||||
ORDER BY n_dead_tup DESC LIMIT 10;
|
||||
"
|
||||
|
||||
# Step 3 — Check if deletion is recoverable via MVCC (PostgreSQL)
|
||||
# Records may still be recoverable if VACUUM has not run
|
||||
psql $DATABASE_URL -c "
|
||||
SELECT * FROM [table]
|
||||
WHERE xmax != 0 -- recently deleted rows
|
||||
LIMIT 100;
|
||||
"
|
||||
|
||||
# Step 4 — If not recoverable via MVCC, restore from backup
|
||||
# Follow Section 3.3 (Database Corruption runbook) from Step 3 onward
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Backup and Restore Procedures
|
||||
|
||||
### Backup Configuration
|
||||
|
||||
| Data store | Backup type | Frequency | Retention | Location |
|
||||
|---|---|---|---|---|
|
||||
| [Primary database] | Automated snapshots | Every [N] hours | [N] days | [S3 bucket / cloud storage path] |
|
||||
| [Primary database] | Transaction log backups | Continuous | [N] days | [Location] |
|
||||
| [Secondary store — e.g. Redis] | RDB dump | Daily | [N] days | [Location] |
|
||||
| [Blob/object storage] | Cross-region replication | Continuous | [N] days | [DR region bucket] |
|
||||
| [Config / secrets] | Terraform state + Vault backup | On change | Indefinite | [Location] |
|
||||
|
||||
### Backup Validation (Run Weekly)
|
||||
|
||||
```bash
|
||||
# Test restore of latest database backup to a throwaway instance
|
||||
aws rds restore-db-instance-from-db-snapshot \
|
||||
--db-instance-identifier [service-name]-backup-test-$(date +%Y%m%d) \
|
||||
--db-snapshot-identifier $(aws rds describe-db-snapshots \
|
||||
--db-instance-identifier [db-id] \
|
||||
--query 'sort_by(DBSnapshots, &SnapshotCreateTime)[-1].DBSnapshotIdentifier' \
|
||||
--output text)
|
||||
|
||||
# Wait for restore, then run integrity checks
|
||||
psql [test-instance-endpoint] -c "[integrity check query]"
|
||||
|
||||
# Confirm row counts match recent production values (allow ≤ RPO difference)
|
||||
psql [test-instance-endpoint] -c "SELECT COUNT(*) FROM [critical-table]"
|
||||
|
||||
# Destroy the test instance
|
||||
aws rds delete-db-instance \
|
||||
--db-instance-identifier [service-name]-backup-test-$(date +%Y%m%d) \
|
||||
--skip-final-snapshot
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. DR Testing Cadence
|
||||
|
||||
Regular testing is mandatory. An untested DR plan is not a DR plan.
|
||||
|
||||
| Test type | Frequency | Who runs it | Pass criteria |
|
||||
|---|---|---|---|
|
||||
| Backup restore validation | Weekly (automated) | On-call rotation | Restore completes, integrity checks pass |
|
||||
| Zone failover drill | Monthly | Engineering team | RTO target met, zero data loss |
|
||||
| Region failover drill | Quarterly | Engineering + SRE | RTO/RPO targets met |
|
||||
| Full DR game day | Annually | Engineering + stakeholders | All scenarios exercised, gaps documented |
|
||||
| Chaos engineering (infra failures) | Weekly (automated) | Chaos engineering tooling | Service degrades gracefully, recovers automatically |
|
||||
|
||||
### Game Day Procedure
|
||||
|
||||
1. **Pre-game day (1 week before):** Notify all stakeholders, freeze production changes for the day, prepare DR environment.
|
||||
2. **Scope definition:** Choose 2–3 scenarios from Section 2. Document expected outcomes before the test.
|
||||
3. **Execute:** One person acts as incident commander, others execute runbook steps while another observes and times.
|
||||
4. **Measure:** Record actual RTO and RPO against targets for each scenario.
|
||||
5. **Debrief (same day):** Document gaps, runbook inaccuracies, and automation opportunities.
|
||||
6. **Action items:** File tickets for every gap found. Priority: P1 items must be fixed before next game day.
|
||||
|
||||
---
|
||||
|
||||
## 6. Communication Plan
|
||||
|
||||
### Internal Communication During DR Event
|
||||
|
||||
**Incident commander responsibilities:**
|
||||
- Declare the DR event and open the incident channel
|
||||
- Post updates every 15 minutes minimum
|
||||
- Make the call to fail over (do not let the team decide by committee)
|
||||
- Notify business stakeholders of expected recovery time
|
||||
|
||||
**Notify these people at DR event start:**
|
||||
|
||||
| Role | Name | Contact | When to notify |
|
||||
|---|---|---|---|
|
||||
| Engineering manager | [Name] | [Slack / Phone] | Immediately |
|
||||
| CTO / VP Engineering | [Name] | [Phone] | Tier 1 services: immediately |
|
||||
| Customer success lead | [Name] | [Slack] | If customer-facing impact |
|
||||
| Security lead | [Name] | [Slack / PagerDuty] | If breach suspected |
|
||||
| Legal / compliance | [Name] | [Email / Phone] | If data loss involves PII |
|
||||
|
||||
### Communication Templates
|
||||
|
||||
**DR event declared:**
|
||||
```
|
||||
🔴 DR EVENT — [Service Name]
|
||||
Time: [HH:MM UTC]
|
||||
Scenario: [Zone failure / Region failure / Data loss / etc.]
|
||||
Impact: [Who is affected and how]
|
||||
RTO target: [X minutes]
|
||||
Incident commander: [Name]
|
||||
War room: [Slack channel / call link]
|
||||
Next update: [Time + 15 min]
|
||||
```
|
||||
|
||||
**Status update (every 15 minutes):**
|
||||
```
|
||||
🔴 DR UPDATE — [Service Name] — [HH:MM UTC]
|
||||
Status: [Investigating / Executing recovery / Verifying]
|
||||
Progress: [One sentence on current step]
|
||||
Blockers: [Any — or "None"]
|
||||
Updated RTO estimate: [Time]
|
||||
Next update: [Time + 15 min]
|
||||
```
|
||||
|
||||
**Recovery confirmed:**
|
||||
```
|
||||
✅ DR RESOLVED — [Service Name] — [HH:MM UTC]
|
||||
Total downtime: [X minutes]
|
||||
Data loss: [None / X minutes of transactions]
|
||||
RTO target: [X min] — Actual: [Y min] — [MET / MISSED]
|
||||
RPO target: [X min] — Actual: [Y min] — [MET / MISSED]
|
||||
Root cause: [One sentence]
|
||||
Post-incident review: [Scheduled for / Link when created]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. DR Readiness Checklist
|
||||
|
||||
Run this checklist quarterly and before any major infrastructure change:
|
||||
|
||||
**Backups:**
|
||||
- [ ] Automated backups are running and alerts fire if they fail
|
||||
- [ ] Most recent backup restore was tested within the last 7 days
|
||||
- [ ] Backup retention meets RPO and compliance requirements
|
||||
- [ ] Backups are stored in a separate region / account from primary
|
||||
|
||||
**Failover infrastructure:**
|
||||
- [ ] DR region / environment exists and is provisioned (not just documented)
|
||||
- [ ] DNS failover procedure is documented with exact commands
|
||||
- [ ] DR database replica is current (replication lag is within RPO)
|
||||
- [ ] Service can be deployed in DR region with a single command or automated pipeline
|
||||
|
||||
**Runbooks:**
|
||||
- [ ] All runbooks in Section 3 have been tested within the last quarter
|
||||
- [ ] Runbook commands have been verified against current infrastructure (no stale references)
|
||||
- [ ] Contact list is current (no departed employees)
|
||||
|
||||
**Access:**
|
||||
- [ ] On-call engineers have access to DR region console / CLI
|
||||
- [ ] Service account credentials for DR region are provisioned and tested
|
||||
- [ ] Break-glass accounts exist for emergency access if SSO is unavailable
|
||||
|
||||
**Monitoring:**
|
||||
- [ ] Monitoring exists in DR region (not just primary)
|
||||
- [ ] Alerts fire correctly when DR environment has issues
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] RPO and RTO targets are specific numbers, not ranges, and are agreed with the business
|
||||
- [ ] Every command in every runbook has been run by a human in the last quarter — not copied from documentation untested
|
||||
- [ ] DR database exists in the DR region and replication lag is monitored
|
||||
- [ ] Backup restore has been tested end-to-end within the last 7 days
|
||||
- [ ] The game day schedule is on the team calendar — not just documented here
|
||||
- [ ] Contact list contains current phone numbers, not just Slack handles (Slack may be down during a DR event)
|
||||
- [ ] Security breach runbook (3.5) explicitly names the security team contact and does not attempt self-remediation
|
||||
- [ ] All thresholds (RTO/RPO) are visible in the monitoring dashboard so actual vs. target is measurable in real time
|
||||
@@ -0,0 +1,338 @@
|
||||
---
|
||||
name: engineering-hiring-rubric
|
||||
description: "Build an engineering hiring rubric and technical interview scorecard for evaluating software engineers at a specific level. Use when asked to create an interview rubric, design a hiring process, build a technical scorecard, or standardize engineer evaluation. Produces a full interview scorecard, behavioral question bank, technical question set with evaluation criteria, system design rubric, and debrief agenda."
|
||||
---
|
||||
|
||||
# Engineering Hiring Rubric
|
||||
|
||||
Produce a complete hiring rubric and interview scorecard for evaluating software engineers at a specific role and level. The rubric must be specific enough that two interviewers who have never compared notes will score the same candidate within one level of each other. That requires: explicit behavioral anchors (what does "Strong Hire" look like vs. "Hire" for each competency), calibrated technical questions with written evaluation criteria, and a structured debrief format that surfaces signal rather than recency bias. Include calibration notes to help interviewers recognize and counter common evaluation biases.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask for these if not already provided:
|
||||
- **Role** — backend, frontend, fullstack, SRE/platform, data, ML, or mobile engineer
|
||||
- **Level** — junior (L3/IC2), mid (L4/IC3), senior (L5/IC4), or staff (L6/IC5); clarify the company's level naming if different
|
||||
- **Team context** — what the team builds, team size, and what problems this hire will work on in the first year
|
||||
- **Tech stack** — primary languages and frameworks for the technical questions; list the stack explicitly
|
||||
- **Interview format** — which rounds are used (phone screen, coding, system design, behavioral, take-home); if not specified, produce a recommended format
|
||||
|
||||
## Output Format
|
||||
|
||||
---
|
||||
|
||||
# Engineering Hiring Rubric: [Role] — [Level]
|
||||
|
||||
**Role:** [e.g., Senior Backend Engineer]
|
||||
**Level equivalent:** [e.g., L5 / IC4 / Senior]
|
||||
**Team:** [Team name and one-sentence description of what they build]
|
||||
**Tech stack:** [Languages and frameworks]
|
||||
**Interview loop:** [List the rounds in order]
|
||||
|
||||
---
|
||||
|
||||
## 1. Role Definition and Level Expectations
|
||||
|
||||
### What This Role Does
|
||||
|
||||
[2–3 sentences describing the scope of work: what systems they'll own, what problems they'll solve, and who they'll work with. Make this specific to the team context provided.]
|
||||
|
||||
### Level Bar
|
||||
|
||||
Define the minimum bar for a Hire recommendation at this level. This is not the ideal candidate description — it is the floor.
|
||||
|
||||
| Dimension | [Level] Floor | One Level Below (No Hire) | One Level Above (Stretch) |
|
||||
|-----------|--------------|---------------------------|---------------------------|
|
||||
| Technical scope | [e.g., "Owns a service or major feature area end-to-end with minimal guidance"] | [e.g., "Completes well-defined tasks; needs guidance on scope and approach"] | [e.g., "Leads cross-team technical initiatives; sets technical direction"] |
|
||||
| Problem solving | [e.g., "Breaks ambiguous problems into concrete sub-problems independently"] | [e.g., "Solves defined problems well; struggles with ambiguity"] | [e.g., "Identifies problems others miss; structures organization-level technical challenges"] |
|
||||
| Code quality | [e.g., "Writes production-ready code; anticipates edge cases; reviewable without significant rework"] | [e.g., "Writes working code that requires significant review feedback"] | [e.g., "Sets code quality standards; designs reusable abstractions adopted by others"] |
|
||||
| Communication | [e.g., "Communicates technical decisions clearly to peers and stakeholders"] | [e.g., "Communicates well with direct team; struggles with cross-team or stakeholder comms"] | [e.g., "Drives technical consensus across teams; writes documents others reference"] |
|
||||
| Ownership | [e.g., "Sees work to production; monitors after deploy; follows up on issues proactively"] | [e.g., "Delivers assigned work; escalates issues but doesn't drive them to resolution"] | [e.g., "Owns outcomes across teams; improves team processes and systems beyond their own work"] |
|
||||
|
||||
---
|
||||
|
||||
## 2. Interview Loop Structure
|
||||
|
||||
| Round | Format | Duration | Interviewer | Competencies Assessed |
|
||||
|-------|--------|----------|-------------|----------------------|
|
||||
| Phone screen | Video call, technical questions | 45 min | [Hiring manager or senior engineer] | Problem solving, communication, basic technical depth |
|
||||
| Coding interview 1 | Live coding — [platform] | 60 min | [Engineer] | Coding, data structures, code quality |
|
||||
| Coding interview 2 | Live coding — [platform] | 60 min | [Engineer] | Algorithms, debugging, code quality |
|
||||
| System design | Whiteboard / shared doc | 60 min | [Senior/Staff engineer] | System design, scalability, technical communication |
|
||||
| Behavioral | Structured interview | 45 min | [Hiring manager] | Ownership, collaboration, growth mindset |
|
||||
| [Optional] Take-home | Asynchronous project | [X hours] | [Reviewer] | Code quality, thoroughness, real-world problem solving |
|
||||
|
||||
**Interview coverage matrix:** Each competency dimension must be assessed by at least 2 independent interviewers.
|
||||
|
||||
| Competency | Phone Screen | Coding 1 | Coding 2 | System Design | Behavioral |
|
||||
|-----------|-------------|---------|---------|--------------|-----------|
|
||||
| Coding | ○ | ● | ● | ○ | |
|
||||
| System design | ○ | | | ● | |
|
||||
| Problem solving | ● | ● | ● | ● | |
|
||||
| Code quality | | ● | ● | | |
|
||||
| Communication | ● | ● | ● | ● | ● |
|
||||
| Ownership | ○ | | | ○ | ● |
|
||||
| Debugging | | ● | ● | | |
|
||||
|
||||
● = Primary signal ○ = Secondary signal
|
||||
|
||||
---
|
||||
|
||||
## 3. Coding Interview Guide
|
||||
|
||||
### Question Selection
|
||||
|
||||
Choose 1–2 problems per coding round. Problems should be solvable in 30–40 minutes with the remaining time for discussion and follow-ups. Prefer problems with multiple solution tiers so you can see how far candidates take their thinking.
|
||||
|
||||
### Problem Template
|
||||
|
||||
**Problem: [Title]**
|
||||
|
||||
*Prompt (read to candidate):*
|
||||
> [Problem statement — be specific. Include constraints (input size, value ranges). Avoid ambiguity that tests problem-reading rather than problem-solving.]
|
||||
|
||||
*Example:*
|
||||
> Given a list of integers representing stock prices at each minute of a trading day, return the maximum profit you could achieve by making exactly one buy and one sell. You may not sell before you buy.
|
||||
|
||||
**Clarifying questions a strong candidate will ask:**
|
||||
- [e.g., "Can the list be empty?" / "Are all values positive?" / "Can profit be negative — i.e., should we return 0 if no profit is possible?"]
|
||||
|
||||
**Solution tiers:**
|
||||
|
||||
| Tier | Approach | Time Complexity | Space Complexity | Signals |
|
||||
|------|----------|-----------------|-----------------|---------|
|
||||
| Baseline | [Brute force — O(n²) nested loop] | O(n²) | O(1) | Can solve the problem; understands correctness |
|
||||
| Expected | [Single pass, tracking min price seen so far] | O(n) | O(1) | Strong problem solver; explains tradeoff |
|
||||
| Strong | [Generalizes to k transactions, or extends to cooldown variant without prompting] | O(n) | O(1) | Staff-level generalization thinking |
|
||||
|
||||
**Follow-up questions:**
|
||||
- [e.g., "What if you could make at most k trades?"]
|
||||
- [e.g., "How would you test this function? Write me 3 test cases."]
|
||||
- [e.g., "Walk me through your code as if you're explaining it in a code review."]
|
||||
|
||||
**Evaluation rubric for this problem:**
|
||||
|
||||
| Signal | Strong Hire | Hire | No Hire |
|
||||
|--------|------------|------|---------|
|
||||
| Problem comprehension | Asks 1–2 clarifying questions immediately; identifies edge cases before coding | Understands the problem after 1 prompt; misses 1–2 edge cases | Misunderstands the problem or requires repeated clarification |
|
||||
| Solution quality | O(n) solution; clean code; handles all edge cases | O(n) with hints; code is readable but has minor issues | O(n²) with hints, or correct solution with significant issues |
|
||||
| Code quality | Well-named variables; logical structure; would pass code review | Functional but verbose or inconsistently named | Hard to follow; would require significant review feedback |
|
||||
| Communication | Narrates thinking throughout; explains complexity; self-corrects | Explains solution when asked; answers follow-ups well | Silent during coding; unable to explain their approach |
|
||||
| Follow-ups | Extends solution confidently; identifies further improvements | Handles follow-ups with moderate prompting | Unable to extend or explain tradeoffs |
|
||||
|
||||
---
|
||||
|
||||
## 4. System Design Interview Guide
|
||||
|
||||
### [Level]-Appropriate Design Scope
|
||||
|
||||
At [Level], expect the candidate to:
|
||||
- [e.g., Senior: "Design a complete system with capacity estimates, component breakdown, and discussion of failure modes"]
|
||||
- [e.g., Mid: "Design the core components of a system; may need prompting on scalability and failure handling"]
|
||||
- [e.g., Junior: "Design a simple client-server system; focus on clarity of thinking over complete distributed systems knowledge"]
|
||||
|
||||
### Sample Design Question
|
||||
|
||||
**Question:** "Design [a URL shortener / a rate limiter / a notification service / a ride-matching system — choose one relevant to the team's domain]."
|
||||
|
||||
**Evaluation dimensions:**
|
||||
|
||||
| Dimension | What to assess | Strong Hire | Hire | No Hire |
|
||||
|-----------|---------------|------------|------|---------|
|
||||
| Requirements clarification | Does the candidate ask before designing? | Asks scope, scale, SLA, and key use cases before drawing anything | Asks some questions; may miss scale or SLA | Starts designing immediately without clarifying |
|
||||
| High-level design | Can they describe the major components? | Clear component breakdown with justified choices; covers data flow | Reasonable breakdown; may overcomplicate or undercomplicate | Missing key components or cannot explain data flow |
|
||||
| Data model | Can they design a schema or data structure for the system? | Models the core entities with normalization/denormalization tradeoffs discussed | Reasonable schema; may miss indexing or partitioning needs | Cannot model the data or produces clearly wrong schema |
|
||||
| Scalability | Can they identify and address bottlenecks? | Identifies bottlenecks proactively; proposes horizontal scaling, caching, or sharding as appropriate | Discusses scaling when prompted; reasonable solutions | Cannot identify bottlenecks or proposes solutions that don't match the scale |
|
||||
| Failure handling | Do they think about what happens when things break? | Proactively discusses failure modes: single points of failure, retry logic, idempotency | Discusses failure when prompted; identifies some failure modes | Does not think about failure; assumes happy path |
|
||||
| Communication | Is the design explained clearly? | Could run this meeting with a team of engineers at a real company | Clear enough to follow; some gaps in explanation | Difficult to follow; interviewer cannot understand the design |
|
||||
|
||||
### Design Probing Questions
|
||||
|
||||
Use these to probe depth after the candidate presents their design:
|
||||
- "Walk me through what happens when a write request comes in at peak load — 10,000 requests per second."
|
||||
- "Your primary database just failed. What happens to the system?"
|
||||
- "You estimated X QPS. How would your design change if it needed to handle 100× that?"
|
||||
- "Where is the first place this system would fall over under load?"
|
||||
- "How would you monitor this in production? What would your on-call runbook look like?"
|
||||
|
||||
---
|
||||
|
||||
## 5. Behavioral Interview Question Bank
|
||||
|
||||
Map every question to a competency. Ask 4–6 questions per behavioral round using STAR format (Situation, Task, Action, Result). Do not ask leading questions.
|
||||
|
||||
### Competency: Ownership and Delivery
|
||||
|
||||
1. "Tell me about a time you owned something end-to-end — from design through production monitoring. What did you do when something went wrong after launch?"
|
||||
- *Strong signal:* Describes proactive monitoring setup, a specific incident they caught themselves, and what they changed
|
||||
- *Weak signal:* Describes writing the code and handing off; no discussion of production behavior
|
||||
|
||||
2. "Describe a project that was significantly delayed or failed. What was your role, and what did you take responsibility for?"
|
||||
- *Strong signal:* Direct ownership of their contribution to the failure; specific changes to how they work
|
||||
- *Weak signal:* Attributes all delay to external factors; no reflection on their own actions
|
||||
|
||||
### Competency: Technical Judgment
|
||||
|
||||
3. "Tell me about a significant technical decision you made. What options did you consider, and how did you decide?"
|
||||
- *Strong signal:* Named alternatives with clear tradeoffs; explains who they consulted; reflects on whether they'd decide the same way today
|
||||
- *Weak signal:* "I knew X was the right answer" without describing the decision process
|
||||
|
||||
4. "Describe a time you had to push back on a technical direction — either from management or from peers. What happened?"
|
||||
- *Strong signal:* Evidence-based disagreement; constructive communication; willing to commit once decision was made even if they lost the argument
|
||||
- *Weak signal:* Either never pushed back or pushed back emotionally without evidence
|
||||
|
||||
### Competency: Collaboration and Communication
|
||||
|
||||
5. "Tell me about a time you had to explain a complex technical concept to a non-technical stakeholder. How did you approach it?"
|
||||
- *Strong signal:* Used analogy or simplified model; confirmed understanding; adapted to the audience
|
||||
- *Weak signal:* "I explained it technically and told them to trust me"
|
||||
|
||||
6. "Describe a situation where you and a peer strongly disagreed on an approach. How did it resolve?"
|
||||
- *Strong signal:* Sought a third opinion or data; focused on the right outcome, not being right; maintained relationship
|
||||
- *Weak signal:* Escalated immediately or capitulated without engaging
|
||||
|
||||
### Competency: Growth and Learning
|
||||
|
||||
7. "What is a significant technical mistake you made in the last two years? What did you learn from it?"
|
||||
- *Strong signal:* Specific mistake, clear causal analysis, concrete behavioral change afterward
|
||||
- *Weak signal:* Cannot name a specific mistake; describes a minor issue to avoid vulnerability
|
||||
|
||||
8. "How do you stay current in [relevant technical area]? Give me a specific example of something you learned recently and applied."
|
||||
- *Strong signal:* Named sources, applied learning in a specific project with a concrete outcome
|
||||
- *Weak signal:* "I read blogs" with no specifics; no applied example
|
||||
|
||||
---
|
||||
|
||||
## 6. Full Interview Scorecard
|
||||
|
||||
Complete one scorecard per interview round. Collect all scorecards before the debrief.
|
||||
|
||||
```
|
||||
INTERVIEW SCORECARD
|
||||
===================
|
||||
Candidate: ______________________
|
||||
Interviewer: ______________________
|
||||
Round: ______________________
|
||||
Date: ______________________
|
||||
Interview format: ______________________
|
||||
|
||||
COMPETENCY RATINGS
|
||||
Rate each dimension independently. Do not average.
|
||||
Scale: 1 = Strong No Hire | 2 = No Hire | 3 = Hire | 4 = Strong Hire
|
||||
|
||||
1 2 3 4 Notes
|
||||
Coding / Technical skill [ ] [ ] [ ] [ ] ___________________________
|
||||
Problem solving [ ] [ ] [ ] [ ] ___________________________
|
||||
System design [ ] [ ] [ ] [ ] ___________________________
|
||||
Code quality [ ] [ ] [ ] [ ] ___________________________
|
||||
Debugging [ ] [ ] [ ] [ ] ___________________________
|
||||
Communication [ ] [ ] [ ] [ ] ___________________________
|
||||
Ownership [ ] [ ] [ ] [ ] ___________________________
|
||||
Collaboration [ ] [ ] [ ] [ ] ___________________________
|
||||
|
||||
SPECIFIC EVIDENCE
|
||||
What did the candidate do or say that drove your rating?
|
||||
(Required — write observable behaviors, not impressions)
|
||||
|
||||
Strongest signal (positive):
|
||||
___________________________________________________________________________
|
||||
|
||||
Strongest concern or gap:
|
||||
___________________________________________________________________________
|
||||
|
||||
OVERALL RECOMMENDATION
|
||||
[ ] Strong Hire [ ] Hire [ ] No Hire [ ] Strong No Hire
|
||||
|
||||
OVERALL RECOMMENDATION RATIONALE
|
||||
(Required — 3–5 sentences minimum. State your recommendation, the evidence
|
||||
that supports it, and the specific gap or risk if not a Strong Hire)
|
||||
___________________________________________________________________________
|
||||
___________________________________________________________________________
|
||||
___________________________________________________________________________
|
||||
|
||||
Level signal: This candidate demonstrated [ L_ / L_ ] level behaviors.
|
||||
|
||||
SHOULD INTERVIEWERS DISCUSS BEFORE DEBRIEF?
|
||||
[ ] No — I have a clear independent signal
|
||||
[ ] Yes — I need context on [specific area] to complete my assessment
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Hiring Recommendation Framework
|
||||
|
||||
| Recommendation | Meaning | When to use |
|
||||
|---------------|---------|-------------|
|
||||
| **Strong Hire** | Confident the candidate will exceed the level bar and be a high performer on the team | Evidence across 3+ competencies at above-bar level; no significant concerns |
|
||||
| **Hire** | Confident the candidate meets the level bar; will perform well | Meets bar on all must-have competencies; may have 1 area to develop |
|
||||
| **No Hire** | Does not meet the level bar | Below bar on 1+ must-have competency, or gap too large to close quickly |
|
||||
| **Strong No Hire** | Clear mismatch — well below the bar, or a specific disqualifying signal | Significant gaps across multiple competencies, or a values/behavior concern |
|
||||
|
||||
**Must-hire competencies for [Role] at [Level]:** [List 3–4 competencies where a No Hire score on any one of them means the overall recommendation must be No Hire, regardless of performance elsewhere. Example: "Coding and System Design are must-hire competencies for a Senior Backend Engineer. Strong performance on Behavioral dimensions cannot compensate for a No Hire on Coding."]
|
||||
|
||||
**Debrief rule:** A Strong Hire can override one No Hire only if: (a) the No Hire is not on a must-hire competency, and (b) the Strong Hire interviewer can articulate why the concern is not disqualifying. A Strong No Hire cannot be overridden — escalate to hiring manager.
|
||||
|
||||
---
|
||||
|
||||
## 8. Debrief Agenda
|
||||
|
||||
Run the debrief before scorecards are shared verbally. Everyone submits a written scorecard first.
|
||||
|
||||
```
|
||||
DEBRIEF AGENDA — [Candidate Name]
|
||||
Duration: 45 minutes
|
||||
Facilitator: [Hiring Manager]
|
||||
|
||||
0:00 – 0:05 SCORECARD REVIEW
|
||||
Each interviewer states their overall recommendation only (no rationale yet).
|
||||
Facilitator notes alignment and disagreements on whiteboard/doc.
|
||||
|
||||
0:05 – 0:15 EVIDENCE ROUND
|
||||
Go around the table. Each interviewer shares:
|
||||
- Their strongest positive signal (observable behavior, not impression)
|
||||
- Their biggest concern (observable behavior, not impression)
|
||||
No discussion yet — just evidence gathering.
|
||||
|
||||
0:15 – 0:30 DISCUSS DISAGREEMENTS
|
||||
Address only the competency dimensions where interviewers disagree.
|
||||
Anchor discussion on: "What did you observe?" not "What do you think?"
|
||||
If interviewers assessed different competencies, disagreement may reflect
|
||||
insufficient signal — note this.
|
||||
|
||||
0:30 – 0:40 DECISION
|
||||
Reach a decision on overall recommendation.
|
||||
If consensus: state the recommendation and rationale.
|
||||
If not consensus: hiring manager makes the call and states why.
|
||||
|
||||
0:40 – 0:45 PROCESS NOTES
|
||||
- Were any questions unclear or hard to compare across candidates?
|
||||
- Any bias signals observed during the debrief? (see Section 9)
|
||||
- Feedback to improve the process for next time.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. Calibration and Bias Reduction Notes
|
||||
|
||||
Brief every interviewer on these before they conduct their first interview for this role.
|
||||
|
||||
| Bias | How it manifests | Counter-measure |
|
||||
|------|-----------------|-----------------|
|
||||
| Halo effect | Strong performance in round 1 colors ratings in round 2 | Submit scorecard before reading others; rate each competency independently |
|
||||
| Similarity bias | "I liked them" correlates with "they think like me" | Require observable evidence for every rating; check: "Is this a signal about their ability or their similarity to me?" |
|
||||
| Recency bias | Final impression dominates overall rating | Take notes during the interview; write evidence immediately after; debrief uses written evidence, not memory |
|
||||
| Expectation anchoring | First interviewer's opinion anchors all others | No verbal discussion between interviewers before debrief; written scorecards submitted before debrief starts |
|
||||
| Culture fit as cover | "Not a culture fit" without specific behavioral evidence | "Culture fit" is not a valid dimension on this scorecard; use Collaboration and Communication with evidence |
|
||||
| Credential bias | Degree or previous employer overweights rating | Do not list educational background in pre-interview briefing documents; focus on demonstrated behaviors |
|
||||
| Confidence ≠ Competence | Articulate candidates rated higher regardless of correctness | Grade the answer quality, not the delivery style; use written rubrics per question |
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Level bar table defines a concrete floor for the level — not aspirational traits — with a comparison to one level below and above
|
||||
- [ ] Every behavioral question includes explicit Strong Hire and Weak/No Hire signal descriptions — not just the question text
|
||||
- [ ] Coding problem(s) include solution tiers with time and space complexity, plus a per-question rubric with behavioral anchors
|
||||
- [ ] System design rubric evaluates at minimum: requirements clarification, component design, data model, scalability, and failure handling
|
||||
- [ ] Scorecard uses observable behavior fields ("What did the candidate do or say") — not impression fields
|
||||
- [ ] Must-hire competencies are explicitly named for the role and level
|
||||
- [ ] Debrief agenda enforces written scorecard submission before verbal discussion to prevent anchoring
|
||||
@@ -0,0 +1,164 @@
|
||||
---
|
||||
name: engineering-weekly-report
|
||||
description: "Write a weekly engineering status report for a team, service, or initiative. Use when asked to write a team update, weekly engineering report, sprint status email, or standing team communication to stakeholders. Produces a concise, scannable weekly report covering shipping progress, metrics, decisions, blockers, and next-week priorities."
|
||||
---
|
||||
|
||||
# Engineering Weekly Report
|
||||
|
||||
Produce a weekly engineering status report that a team can send to stakeholders, their engineering manager, and the team itself. The format is fixed week-over-week so readers know exactly where to look — shipping progress at the top, decisions in the middle, risks and next steps at the bottom. The report must be readable in under 2 minutes. Avoid prose walls: use bullet points, status tags, and short tables. If metrics are not provided, leave the metrics section with [data needed] markers rather than fabricating numbers.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask for these if not already provided:
|
||||
- **Team name and report period** — team name plus week number or date range (e.g., "Platform Team, Week 21, May 12–16")
|
||||
- **Work items shipped this week** — what was completed and released or merged
|
||||
- **Work items in progress** — what is actively being worked on, with rough percent-complete if known
|
||||
- **Blocked items** — what is blocked, who owns the block, and what is needed to unblock
|
||||
- **Key decisions made** — any architecture, process, or priority decisions made this week
|
||||
- **Decisions needed next week** — any decisions that need to be made soon and who needs to make them
|
||||
- **Risks and escalations** — anything that threatens next week's commitments or needs leadership visibility
|
||||
- **Next week's top priorities** — the 3–5 things the team plans to accomplish next week
|
||||
|
||||
Optional but useful:
|
||||
- **Key metrics** — reliability (error rate, p99 latency), velocity (story points completed), or other health indicators
|
||||
- **Team health notes** — PTO, new joins, attrition, morale signals worth noting
|
||||
- **Sprint or iteration number** — if the team runs sprints
|
||||
|
||||
## Output Format
|
||||
|
||||
---
|
||||
|
||||
# Engineering Weekly Report — [Team Name]
|
||||
**Week:** [Week Number] | [Date Range, e.g., May 12–16, 2025]
|
||||
**Author:** [Name or Team Lead]
|
||||
**Distribution:** [e.g., Eng leadership, Product, Team]
|
||||
|
||||
---
|
||||
|
||||
## Shipping Progress
|
||||
|
||||
### Shipped This Week
|
||||
|
||||
| Item | Description | Impact |
|
||||
|------|-------------|--------|
|
||||
| [Feature / Fix / Infra change] | [One-line description] | [Who benefits / what it unblocks] |
|
||||
| [Feature / Fix / Infra change] | [One-line description] | [Who benefits / what it unblocks] |
|
||||
| [Feature / Fix / Infra change] | [One-line description] | [Who benefits / what it unblocks] |
|
||||
|
||||
### In Progress
|
||||
|
||||
| Item | Owner | Status | Target Ship |
|
||||
|------|-------|--------|-------------|
|
||||
| [Work item] | [Name] | [~40% / On Track / At Risk] | [Date or Sprint] |
|
||||
| [Work item] | [Name] | [~70% / On Track / At Risk] | [Date or Sprint] |
|
||||
| [Work item] | [Name] | [~20% / On Track / At Risk] | [Date or Sprint] |
|
||||
|
||||
### Blocked
|
||||
|
||||
| Item | Blocked Since | Blocker Description | Owner | Needed To Unblock |
|
||||
|------|--------------|--------------------|----|-------------------|
|
||||
| [Work item] | [Date] | [What is blocking progress] | [Name] | [Specific ask — decision, resource, dependency] |
|
||||
|
||||
If no items are blocked: *No active blockers.*
|
||||
|
||||
---
|
||||
|
||||
## Key Metrics
|
||||
|
||||
*Metrics reported as of [Date]. Prior week in parentheses.*
|
||||
|
||||
| Metric | This Week | Last Week | Trend | Target |
|
||||
|--------|-----------|-----------|-------|--------|
|
||||
| Error rate (5xx) | [X%] | [X%] | [↑ / ↓ / →] | < [threshold] |
|
||||
| p99 latency | [Xms] | [Xms] | [↑ / ↓ / →] | < [threshold] |
|
||||
| Deployment frequency | [X deploys] | [X deploys] | [↑ / ↓ / →] | [target] |
|
||||
| Story points completed | [X] | [X] | [↑ / ↓ / →] | [sprint target] |
|
||||
| On-call page volume | [X pages] | [X pages] | [↑ / ↓ / →] | < [threshold] |
|
||||
|
||||
**Metrics notes:** [Any context that makes the numbers meaningful — e.g., "Error rate spike on Tuesday tied to downstream dependency outage, resolved by EOD."]
|
||||
|
||||
If metrics are not provided: replace table rows with `[data needed — provide metric values for this section]`.
|
||||
|
||||
---
|
||||
|
||||
## Decisions
|
||||
|
||||
### Made This Week
|
||||
|
||||
| Decision | Rationale | Owner | Stakeholders Informed |
|
||||
|----------|-----------|-------|----------------------|
|
||||
| [Decision description] | [Why — 1 sentence] | [Name] | [Yes / No — who] |
|
||||
| [Decision description] | [Why — 1 sentence] | [Name] | [Yes / No — who] |
|
||||
|
||||
If no decisions were made: *No major decisions this week.*
|
||||
|
||||
### Needed Next Week
|
||||
|
||||
| Decision | Context | Deadline | Decision Owner |
|
||||
|----------|---------|----------|----------------|
|
||||
| [What needs to be decided] | [Why it matters, what happens if delayed] | [Date] | [Name or role] |
|
||||
|
||||
If no decisions are pending: *No decisions pending.*
|
||||
|
||||
---
|
||||
|
||||
## Risks and Escalations
|
||||
|
||||
| Risk | Likelihood | Impact | Mitigation | Escalate To |
|
||||
|------|-----------|--------|-----------|-------------|
|
||||
| [Risk description] | [High/Med/Low] | [High/Med/Low] | [What we're doing about it] | [Name/role if escalation needed] |
|
||||
|
||||
**Escalations this week:** [Any item that needs immediate leadership attention — call it out explicitly here, do not bury it in a table row. If none: "None."]
|
||||
|
||||
---
|
||||
|
||||
## Team Health
|
||||
|
||||
| Item | Status |
|
||||
|------|--------|
|
||||
| Team capacity this week | [X of Y people at full capacity] |
|
||||
| PTO / out of office | [Names and dates, or "None"] |
|
||||
| New joins / departures | [Name, role, and date, or "None"] |
|
||||
| On-call this week | [Name] |
|
||||
| On-call next week | [Name] |
|
||||
|
||||
**Team notes:** [Any morale, workload, or team dynamic signals worth surfacing — keep this factual and constructive. If nothing to note: omit this line.]
|
||||
|
||||
---
|
||||
|
||||
## Next Week's Priorities
|
||||
|
||||
*The [3–5] things this team will ship or meaningfully advance next week.*
|
||||
|
||||
1. **[Priority item]** — [One sentence: what done looks like and who owns it]
|
||||
2. **[Priority item]** — [One sentence: what done looks like and who owns it]
|
||||
3. **[Priority item]** — [One sentence: what done looks like and who owns it]
|
||||
4. **[Priority item]** — [One sentence: what done looks like and who owns it]
|
||||
5. **[Priority item]** — [One sentence: what done looks like and who owns it]
|
||||
|
||||
**Capacity risk:** [If the team is at reduced capacity next week (PTO, incidents, etc.), note it here so stakeholders calibrate expectations.]
|
||||
|
||||
---
|
||||
|
||||
## Appendix: Sprint Scorecard (if applicable)
|
||||
|
||||
| Sprint | Committed | Completed | Completion Rate | Carried Over |
|
||||
|--------|-----------|-----------|----------------|--------------|
|
||||
| Sprint [N-1] | [X pts] | [X pts] | [X%] | [X pts] |
|
||||
| Sprint [N] (current) | [X pts] | [X pts — partial] | [X% at midpoint] | TBD |
|
||||
|
||||
---
|
||||
|
||||
*Questions or corrections: [Slack channel or email] | Next report: [Date]*
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Every blocked item names a specific owner and states what is concretely needed to unblock it — not just "waiting on X"
|
||||
- [ ] Decisions-needed table includes a deadline and a named decision owner, not a vague "TBD"
|
||||
- [ ] Metrics table is either populated with real numbers or explicitly marked `[data needed]` — no fabricated metrics
|
||||
- [ ] Next week's priorities are written as outcomes ("ship X", "complete Y migration") not as activities ("work on X")
|
||||
- [ ] Escalations that need leadership attention are called out explicitly in the Risks section — not just buried in a table row
|
||||
- [ ] The entire report is readable in under 2 minutes — if it is longer than one printed page, trim it
|
||||
- [ ] Report period (week number and date range) is clearly stated in the header
|
||||
@@ -0,0 +1,369 @@
|
||||
---
|
||||
name: feature-flag-guide
|
||||
description: "Write a feature flag management guide and lifecycle playbook for a service or team — covering flag taxonomy, creation checklist, rollout strategy, monitoring requirements, cleanup policy, and governance. Use when asked to document feature flag practices, create a flag rollout plan, write a feature flag policy, or guide a team on flag lifecycle management. Produces a flag lifecycle playbook, taxonomy reference, per-flag creation template, rollout decision tree, and cleanup checklist."
|
||||
---
|
||||
|
||||
# Feature Flag Guide Skill
|
||||
|
||||
Produce a complete feature flag management guide for a service or team — covering how flags are named and categorised, how to create and roll out a flag safely, what to monitor during rollout, when and how to clean up flags, and who is responsible for each stage. Feature flags without discipline become permanent technical debt. This guide gives the team a repeatable process so flags are created intentionally, rolled out safely, and removed when done.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask for these if not already provided:
|
||||
- **Service or team name** — scope of the guide
|
||||
- **Feature flag platform** — LaunchDarkly, Split, Unleash, Flagsmith, Flipt, or a custom/in-house solution
|
||||
- **Flag being documented** (if writing a per-flag guide) or "general guide" (if writing team-wide policy)
|
||||
- **Rollout constraints** — any compliance, data privacy, or contractual constraints on who can see a feature (e.g. HIPAA, EU-only, enterprise customers only)
|
||||
|
||||
## Output Format
|
||||
|
||||
---
|
||||
|
||||
# Feature Flag Management Guide: [Service / Team Name]
|
||||
|
||||
**Team:** [Team name] | **Platform:** [LaunchDarkly / Split / Unleash / Custom]
|
||||
**Document owner:** [Name] | **Last updated:** [Date]
|
||||
**Review cycle:** Quarterly, and whenever the flag platform changes
|
||||
|
||||
---
|
||||
|
||||
## 1. Flag Taxonomy
|
||||
|
||||
Every flag belongs to exactly one category. The category determines default behaviour, who can enable it in production, and when it must be cleaned up.
|
||||
|
||||
| Type | Purpose | Default state | Production gate | Max lifetime |
|
||||
|---|---|---|---|---|
|
||||
| **Release flag** | Controls rollout of a new feature — decouples deploy from release | Off | Tech lead approval | 90 days from feature launch |
|
||||
| **Experiment flag** | A/B or multivariate test — measures impact of a change | Off (control group) | Product + tech lead | Duration of experiment + 30 days |
|
||||
| **Ops flag** | Operational control — circuit breaker, kill switch, throttle | On (normal behaviour) | On-call engineer can toggle | Indefinite (review annually) |
|
||||
| **Permission flag** | Gates access by user segment, tier, or region | Off (restricted) | Product + Account owner | Indefinite (review annually) |
|
||||
|
||||
**When in doubt:** If the flag is temporary (tied to a specific feature launch), it is a Release flag. If it will exist forever as a control knob, it is an Ops flag.
|
||||
|
||||
---
|
||||
|
||||
## 2. Flag Naming Convention
|
||||
|
||||
All flags must follow this naming scheme:
|
||||
|
||||
```
|
||||
[type]-[service]-[feature-description]
|
||||
```
|
||||
|
||||
| Segment | Values | Example |
|
||||
|---|---|---|
|
||||
| type | `release`, `exp`, `ops`, `perm` | `release` |
|
||||
| service | Short service identifier, lowercase, hyphenated | `payments` |
|
||||
| feature-description | Kebab-case description, max 5 words | `new-checkout-flow` |
|
||||
|
||||
**Full examples:**
|
||||
- `release-payments-new-checkout-flow` — release flag for a new checkout feature in the payments service
|
||||
- `exp-search-personalized-ranking` — experiment on personalized search ranking
|
||||
- `ops-api-rate-limit-override` — operational flag to override API rate limits
|
||||
- `perm-dashboard-beta-users-only` — permission flag gating dashboard for beta users
|
||||
|
||||
**Do not:**
|
||||
- Use ticket numbers in flag names (`release-JIRA-1234` → not searchable or self-describing)
|
||||
- Use dates in flag names (`release-dark-mode-jan-2024` → flags outlive their dates)
|
||||
- Use vague names (`release-new-thing` → not useful when you have 50 flags)
|
||||
|
||||
---
|
||||
|
||||
## 3. Flag Creation Checklist
|
||||
|
||||
Complete every item before creating a flag in the production environment.
|
||||
|
||||
**Before creating the flag:**
|
||||
- [ ] Flag type determined from taxonomy (Section 1)
|
||||
- [ ] Flag name follows naming convention (Section 2)
|
||||
- [ ] Flag owner assigned — one named engineer responsible for cleanup
|
||||
- [ ] Cleanup date set in the flag description field (for Release and Experiment flags)
|
||||
- [ ] Rollout strategy defined — see Section 4
|
||||
- [ ] Monitoring plan defined — see Section 5
|
||||
- [ ] Code review approved with flag guard in place
|
||||
|
||||
**Flag description field (required):**
|
||||
```
|
||||
Type: [Release / Experiment / Ops / Permission]
|
||||
Owner: [Name]
|
||||
Linked ticket: [JIRA-XXXX or GitHub issue URL]
|
||||
Purpose: [One sentence — what this flag controls]
|
||||
Cleanup by: [Date — required for Release and Experiment flags; "Annual review" for Ops/Permission]
|
||||
Rollout plan: [Link to this document or inline summary]
|
||||
```
|
||||
|
||||
**Code requirements:**
|
||||
```python
|
||||
# Good — behaviour is clear when flag is off, and cleanup is obvious
|
||||
if flag_client.is_enabled("release-[service]-[feature]", user_context):
|
||||
return new_feature_handler(request)
|
||||
else:
|
||||
return existing_handler(request)
|
||||
|
||||
# Bad — nested flags, ternaries, and implicit defaults make cleanup error-prone
|
||||
result = new_handler() if (f1 and not f2) or f3 else old_handler()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Rollout Strategy
|
||||
|
||||
### Decision Tree
|
||||
|
||||
Use this decision tree to pick the right rollout strategy for a Release or Experiment flag:
|
||||
|
||||
```
|
||||
Is the change reversible without a deploy?
|
||||
├── No → Use an Ops flag with manual enable, not a percentage rollout
|
||||
└── Yes → Continue
|
||||
|
||||
Is there a user-level identifier available (user ID, session ID)?
|
||||
├── No → Use server-side percentage (stateless, but inconsistent per user)
|
||||
└── Yes → Use user-based percentage (consistent experience per user) ← preferred
|
||||
|
||||
Is the change risky (touches payments, auth, or data writes)?
|
||||
├── Yes → Start at 1% → 5% → 25% → 50% → 100%, with 24-hour holds
|
||||
└── No → Start at 10% → 50% → 100%, with 4-hour holds
|
||||
|
||||
Does the change affect specific customer tiers or geographies?
|
||||
├── Yes → Use segment-based targeting, not percentage rollout
|
||||
└── No → Use percentage rollout
|
||||
```
|
||||
|
||||
### Rollout Stages
|
||||
|
||||
| Stage | Percentage | Hold duration | Pass criteria before advancing |
|
||||
|---|---|---|---|
|
||||
| Canary | 1% | 24 hours | Error rate within SLO, no P1 incidents |
|
||||
| Early rollout | 5–10% | 24 hours | Error rate and latency match control group |
|
||||
| Partial rollout | 25–50% | 24–48 hours | Business metrics not degraded vs. control |
|
||||
| Majority | 75% | 24 hours | Final check — no regressions |
|
||||
| Full rollout | 100% | 48 hours | Stable — schedule cleanup |
|
||||
|
||||
**Do not skip stages for Release flags on production.** Speed of rollout is not worth a production incident.
|
||||
|
||||
### Segment-Based Targeting
|
||||
|
||||
Use segment targeting when the rollout must be restricted:
|
||||
|
||||
```yaml
|
||||
# LaunchDarkly segment example — adapt for your platform
|
||||
targeting_rules:
|
||||
- clause:
|
||||
attribute: "subscription_tier"
|
||||
operator: "in"
|
||||
values: ["enterprise", "team"]
|
||||
serve: "on"
|
||||
- clause:
|
||||
attribute: "country"
|
||||
operator: "in"
|
||||
values: ["US", "CA", "GB"]
|
||||
serve: "on"
|
||||
default: "off"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Monitoring Requirements
|
||||
|
||||
Every flag that is not at 0% or 100% rollout requires active monitoring. Do not roll out a flag and walk away.
|
||||
|
||||
### Required Metrics Per Flag
|
||||
|
||||
| Metric | What to compare | Alert threshold |
|
||||
|---|---|---|
|
||||
| Error rate | Flag-on cohort vs. flag-off cohort | >2× baseline error rate in flag-on group |
|
||||
| p99 latency | Flag-on vs. flag-off | >20% higher latency in flag-on group |
|
||||
| [Primary business metric] | Flag-on vs. flag-off | >5% degradation in flag-on group |
|
||||
| [Conversion / completion rate] | Flag-on vs. flag-off | >2% drop in flag-on group |
|
||||
|
||||
**Setting up split metric monitoring in [LaunchDarkly / Split / Datadog]:**
|
||||
```
|
||||
1. Navigate to the flag → Metrics tab
|
||||
2. Add metric: [primary business metric]
|
||||
3. Add metric: error_rate (service-level)
|
||||
4. Add metric: p99_latency (endpoint-level)
|
||||
5. Set alert: notify [flag owner] in Slack #[team-channel] if metric degrades by [threshold]
|
||||
6. Set experiment duration: [N days] if this is an Experiment flag
|
||||
```
|
||||
|
||||
### Guardrail Metrics
|
||||
|
||||
These metrics must never degrade, regardless of what the primary metric shows. If a guardrail is breached, roll back immediately — do not wait for investigation.
|
||||
|
||||
- Error rate exceeds SLO threshold ([X]%)
|
||||
- p99 latency exceeds SLO threshold ([Y] ms)
|
||||
- [Service-specific guardrail — e.g. payment failure rate, auth failure rate]
|
||||
|
||||
**Immediate rollback command if guardrail is breached:**
|
||||
```bash
|
||||
# [LaunchDarkly CLI]
|
||||
ld-cli flag update [project-key] [flag-key] --default-variation off
|
||||
|
||||
# [Split CLI]
|
||||
split-cli update-treatment [flag-name] --treatment "off" --percentage 100
|
||||
|
||||
# [Unleash CLI / API]
|
||||
curl -X POST https://[unleash-host]/api/admin/features/[flag-name]/disable \
|
||||
-H "Authorization: [admin-token]"
|
||||
|
||||
# [Custom — adapt to your implementation]
|
||||
[command or dashboard step]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Per-Flag Creation Template
|
||||
|
||||
Copy this template into your flag's description field and the linked ticket when creating a new flag:
|
||||
|
||||
```markdown
|
||||
## Flag: [flag-name]
|
||||
|
||||
**Type:** [Release / Experiment / Ops / Permission]
|
||||
**Owner:** [Name] ([Slack handle])
|
||||
**Created:** [Date]
|
||||
**Cleanup by:** [Date]
|
||||
**Linked ticket:** [URL]
|
||||
|
||||
### Purpose
|
||||
[One paragraph: what this flag controls, why it exists, what "on" and "off" mean]
|
||||
|
||||
### Rollout Plan
|
||||
| Stage | Target | Date | Approved by |
|
||||
|---|---|---|---|
|
||||
| Canary | 1% | [Date] | [Name] |
|
||||
| Early | 10% | [Date] | [Name] |
|
||||
| Partial | 50% | [Date] | [Name] |
|
||||
| Full | 100% | [Date] | [Name] |
|
||||
|
||||
### Monitoring
|
||||
- Primary metric: [metric name and dashboard link]
|
||||
- Guardrail metrics: error rate < [X]%, p99 < [Y] ms
|
||||
- Alert channel: #[team-channel]
|
||||
|
||||
### Rollback Procedure
|
||||
[Exact steps to turn the flag off in an emergency — should take < 2 minutes]
|
||||
|
||||
### Cleanup Checklist
|
||||
- [ ] Flag at 100% for 48+ hours with no incidents
|
||||
- [ ] Code path for flag-off branch removed from codebase
|
||||
- [ ] Flag deleted from [platform]
|
||||
- [ ] Ticket closed
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Emergency Kill-Switch Procedure
|
||||
|
||||
When a flag needs to be disabled immediately due to a production incident:
|
||||
|
||||
**Time target: flag disabled within 2 minutes of decision.**
|
||||
|
||||
```
|
||||
1. Go to [platform URL] — bookmark this: [URL]
|
||||
2. Search for the flag by name: [flag-name]
|
||||
3. Set to 0% / "off" for ALL users
|
||||
4. Verify the service error rate drops within 60 seconds
|
||||
5. Post to #incidents:
|
||||
"🟡 Feature flag [flag-name] disabled — rolling back [feature description].
|
||||
Owner: [name]. Error rate before: [X]%. Monitoring for recovery."
|
||||
6. Page the flag owner if not already aware
|
||||
```
|
||||
|
||||
**For ops flags (kill switches that must turn OFF normally-on behaviour):**
|
||||
```bash
|
||||
# These flags are "on" by default and turned "off" to disable a feature
|
||||
# Confirm the flag polarity before toggling — "off" may mean "disabled" or "enabled" depending on naming
|
||||
# Flag [flag-name]: OFF = [feature behaviour when off]
|
||||
[kill switch command for your platform]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Stale Flag Policy and Cleanup
|
||||
|
||||
Stale flags are flags that are at 100% rollout, have been at 100% for >48 hours, or are past their cleanup date. Stale flags are technical debt.
|
||||
|
||||
### Stale Flag Definition
|
||||
|
||||
A flag is stale if ANY of the following are true:
|
||||
- It is a Release flag past its cleanup date
|
||||
- It has been at 100% (or 0%) rollout for more than 30 days
|
||||
- Its linked ticket is closed and code cleanup has not happened
|
||||
- Its owner has left the team
|
||||
|
||||
### Cleanup Checklist
|
||||
|
||||
```
|
||||
[ ] Flag is at 100% rollout and has been stable for 48+ hours
|
||||
[ ] Monitoring shows no issues for the flag-on cohort
|
||||
[ ] Code changes:
|
||||
[ ] Remove the flag check from application code
|
||||
[ ] Remove the "off" code path entirely — do not leave dead code
|
||||
[ ] Remove any flag-related tests that test the off behaviour
|
||||
[ ] Update any documentation that references the flag
|
||||
[ ] PR merged and deployed to production
|
||||
[ ] Flag deleted from [platform] (do not just disable — delete)
|
||||
[ ] Cleanup ticket closed
|
||||
[ ] Flag owner confirms cleanup in Slack: "Flag [name] has been cleaned up — [commit link]"
|
||||
```
|
||||
|
||||
**Automated stale flag detection:**
|
||||
```bash
|
||||
# Run weekly — flags past cleanup date or at 100% for > 30 days
|
||||
# [Platform-specific query — adapt:]
|
||||
|
||||
# LaunchDarkly API
|
||||
curl -s "https://app.launchdarkly.com/api/v2/flags/[project-key]" \
|
||||
-H "Authorization: [api-key]" | \
|
||||
jq '.items[] | select(.creationDate < (now - 2592000) * 1000) | {key: .key, created: .creationDate}'
|
||||
|
||||
# Notify #engineering-housekeeping with list of stale flags
|
||||
```
|
||||
|
||||
### Stale Flag Escalation
|
||||
|
||||
| Age past cleanup date | Action |
|
||||
|---|---|
|
||||
| 0–14 days | Slack reminder to flag owner |
|
||||
| 14–30 days | Slack reminder to flag owner + tech lead |
|
||||
| 30+ days | Tech lead assigns cleanup, creates ticket with P2 priority |
|
||||
| 60+ days | Engineering manager reviews — flag may be force-deleted |
|
||||
|
||||
---
|
||||
|
||||
## 9. Governance
|
||||
|
||||
### Who Can Do What
|
||||
|
||||
| Action | Who | Approval required |
|
||||
|---|---|---|
|
||||
| Create a flag (any environment) | Any engineer | None — but must complete creation checklist |
|
||||
| Enable a flag in development | Any engineer | None |
|
||||
| Enable a flag in staging | Any engineer | None |
|
||||
| Enable a flag in production (0–10%) | Flag owner | Tech lead awareness |
|
||||
| Advance rollout in production (10–100%) | Flag owner | Tech lead sign-off per stage |
|
||||
| Enable an Ops flag in production | On-call engineer | None — these are break-glass controls |
|
||||
| Delete a flag | Flag owner | Tech lead confirmation that code cleanup is done |
|
||||
| Create a Permission flag | Flag owner | Product manager approval |
|
||||
|
||||
### Audit Logging
|
||||
|
||||
All flag changes in production must be traceable. Ensure the following are configured in [platform]:
|
||||
|
||||
- **Change log:** Every production flag change logs: who changed it, what they changed, and when.
|
||||
- **Slack notifications:** Production flag changes post to `#[team]-flag-changes` automatically.
|
||||
- **Quarterly review:** Every quarter, the tech lead reviews the full flag inventory, confirms owners are current, and removes flags with no owner.
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Every flag has an owner named in its description — no orphan flags
|
||||
- [ ] Release and Experiment flags have a cleanup date set — not open-ended
|
||||
- [ ] Monitoring is configured for every flag currently between 1–99% rollout
|
||||
- [ ] The emergency kill-switch procedure has been tested — on-call engineers have bookmarked the platform URL and know the steps
|
||||
- [ ] Stale flag detection runs automatically and results are reviewed weekly
|
||||
- [ ] Code review checklist includes: "Does this PR introduce a flag? If yes, is the creation checklist complete?"
|
||||
- [ ] At least one person other than the flag owner knows how to disable any given flag in an emergency
|
||||
@@ -0,0 +1,147 @@
|
||||
---
|
||||
name: incident-postmortem
|
||||
description: "Write a structured incident postmortem or post-incident review. Use when asked to write a postmortem, incident report, P1/P2 review, outage report, or RCA (root cause analysis). Generates a blameless postmortem with timeline, root cause, contributing factors, impact summary, and action items."
|
||||
---
|
||||
|
||||
# Incident Postmortem Skill
|
||||
|
||||
This skill produces a complete, blameless incident postmortem document following industry-standard format. Output enforces blameless framing throughout — system gaps over individual failures — and drives toward specific, closeable action items rather than vague process commitments.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Incident title / ID**
|
||||
- **Severity** (P1 / P2 / P3 or SEV1 / SEV2 / SEV3)
|
||||
- **Date and duration** of the incident
|
||||
- **What happened** (rough notes are fine — the skill will structure them)
|
||||
- **Services or systems affected**
|
||||
- **Customer impact** (how many users, what was degraded)
|
||||
- **How it was detected**
|
||||
- **How it was resolved**
|
||||
- **Initial thoughts on root cause**
|
||||
- **Action items already identified** (optional)
|
||||
- **Responders** (who was on-call or responded — names or roles; used for the timeline, not for blame)
|
||||
- **Customer or external communications sent** (optional — any status page updates, emails, or support messages with timestamps)
|
||||
|
||||
## Output Format
|
||||
|
||||
---
|
||||
|
||||
# Incident Postmortem: [Incident Title]
|
||||
|
||||
**Incident ID:** [ID]
|
||||
**Severity:** [P1/P2/P3]
|
||||
**Date:** [Date]
|
||||
**Duration:** [Start time → Resolution time — total duration]
|
||||
**Status:** [Resolved / Monitoring / Ongoing]
|
||||
**Author:** [Leave blank for user to fill]
|
||||
**Last updated:** [Date]
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
[3–5 sentences. Describe what happened, who was affected, and what was done to resolve it. Written for a non-technical stakeholder. No jargon. No blame.]
|
||||
|
||||
---
|
||||
|
||||
## Impact
|
||||
|
||||
| Dimension | Details |
|
||||
|---|---|
|
||||
| **Users affected** | [Number or percentage] |
|
||||
| **Services degraded** | [List affected services] |
|
||||
| **Business impact** | [Revenue, SLA breach, support tickets, etc. if known] |
|
||||
| **Duration** | [Total time from first detection to full resolution] |
|
||||
|
||||
---
|
||||
|
||||
## Timeline
|
||||
|
||||
List events in chronological order. Each entry: `[HH:MM UTC] — [What happened. Who did what. What changed.]`
|
||||
|
||||
Rules for timeline entries:
|
||||
- Use passive or system-focused language — avoid "X made a mistake"
|
||||
- Include: first symptom, detection, escalation, hypothesis tested, fix applied, confirmation of resolution
|
||||
- Note time between key events (e.g. "22 minutes between detection and escalation")
|
||||
|
||||
---
|
||||
|
||||
## Root Cause
|
||||
|
||||
**Primary root cause:** [One clear sentence. Technical but plain. "A misconfigured deployment config caused..."]
|
||||
|
||||
**Contributing factors:**
|
||||
- [Factor 1 — e.g. lack of canary deployment meant change hit 100% of traffic immediately]
|
||||
- [Factor 2 — e.g. alert threshold was set too high to catch the initial degradation]
|
||||
- [Factor 3 — add as many as are relevant]
|
||||
|
||||
**Why did our existing safeguards not prevent this?**
|
||||
[Honest paragraph explaining why monitoring, tests, or processes didn't catch this earlier. This is where blameless analysis matters most — focus on system gaps, not individual failures.]
|
||||
|
||||
---
|
||||
|
||||
## Detection
|
||||
|
||||
- **How was it first detected?** [Customer report / automated alert / internal monitoring / manual observation]
|
||||
- **Time from incident start to detection:** [X minutes]
|
||||
- **Should we have detected this faster?** [Yes / No — and why]
|
||||
|
||||
---
|
||||
|
||||
## Resolution
|
||||
|
||||
**What fixed it?** [Clear description of the actual fix — one paragraph]
|
||||
**Why did this work?** [Brief technical explanation]
|
||||
**Was there a temporary mitigation before full resolution?** [Yes/No — describe if yes]
|
||||
|
||||
---
|
||||
|
||||
## Action Items
|
||||
|
||||
| # | Action | Owner | Due Date | Priority |
|
||||
|---|---|---|---|---|
|
||||
| 1 | [Specific, testable action] | [Team or person] | [Date] | P1/P2/P3 |
|
||||
|
||||
Rules for action items:
|
||||
- Each action must be specific enough to close as "done" or "not done" — no vague items like "improve monitoring"
|
||||
- Distinguish between: **Prevent recurrence** (fix the root cause), **Improve detection** (catch it faster next time), **Improve response** (resolve it faster next time)
|
||||
- Assign a real owner — not "team" or "TBD" if avoidable
|
||||
- Flag P1 actions as items that block the incident from being marked fully closed
|
||||
|
||||
---
|
||||
|
||||
## What Went Well
|
||||
|
||||
[3–5 honest observations about the response. Include: fast collaboration, good runbooks used, effective escalation, clear communication. This section builds team confidence and reinforces good habits.]
|
||||
|
||||
---
|
||||
|
||||
## Lessons Learned
|
||||
|
||||
[3–5 key insights from this incident that are worth sharing beyond this team. Write these as transferable lessons — e.g. "Our runbook for database failover didn't account for read-replica lag. All runbooks involving database failover should be reviewed."]
|
||||
|
||||
---
|
||||
|
||||
## Communication Log
|
||||
|
||||
[Optional — list external communications sent: status page updates, customer emails, support responses. Include timestamps.]
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Timeline has no blame-focused language
|
||||
- [ ] Root cause is specific (not "human error")
|
||||
- [ ] Root cause answers "why did this happen?" not just "what happened?" — it names a system or process gap, not a symptom
|
||||
- [ ] Contributing factors explain the systemic gaps
|
||||
- [ ] Every action item has an owner and due date
|
||||
- [ ] "What went well" section is genuine, not token
|
||||
- [ ] No action item contains vague language like "improve monitoring", "increase resilience", or "better testing" — each must name a specific change
|
||||
- [ ] Executive summary is readable by non-technical leadership
|
||||
|
||||
## Usage Examples
|
||||
- "Write a postmortem for the [incident name] outage"
|
||||
- "Help me write a P1 incident report"
|
||||
- "Generate an RCA document for [service] going down on [date]"
|
||||
- "Draft a blameless postmortem from these notes: [paste notes]"
|
||||
@@ -0,0 +1,292 @@
|
||||
---
|
||||
name: infra-as-code-review
|
||||
description: "Write an infrastructure-as-code review checklist and conduct a structured review of Terraform, CloudFormation, Pulumi, or Ansible code. Use when asked to review IaC code, audit infrastructure configurations, check cloud security posture, or produce a reusable IaC review checklist. Produces a structured review report with severity-categorized findings, remediation guidance, and a reusable checklist."
|
||||
---
|
||||
|
||||
# Infrastructure-as-Code Review
|
||||
|
||||
Produce a structured infrastructure-as-code review that applies security, reliability, and operational quality standards to a specific body of IaC code. The output serves two purposes: an actionable review report for the code at hand (with findings by severity and specific remediation steps), and a reusable checklist the team can apply to every future IaC change. If the user provides actual code, analyze it and populate the findings table with real issues. If no code is provided, produce the checklist and a template findings report.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask for these if not already provided:
|
||||
- **IaC tool** — Terraform, CloudFormation, Pulumi, Ansible, or CDK
|
||||
- **Cloud provider** — AWS, GCP, Azure, or multi-cloud
|
||||
- **What the code provisions** — a brief description (e.g., "VPC, EKS cluster, and RDS instance for the payments service")
|
||||
- **Security policies or naming standards in use** — any existing org standards to check against; if none, use sensible defaults
|
||||
- **The IaC code itself** — paste or describe it; if not provided, produce the checklist template only and note findings require code
|
||||
|
||||
## Output Format
|
||||
|
||||
---
|
||||
|
||||
# IaC Review Report: [What Is Being Provisioned]
|
||||
|
||||
**Reviewer:** [Name / Claude]
|
||||
**IaC Tool:** [Terraform / CloudFormation / Pulumi / Ansible / CDK]
|
||||
**Cloud Provider:** [AWS / GCP / Azure]
|
||||
**Code Location:** [Repo path or PR link]
|
||||
**Review Date:** [Date]
|
||||
**Overall Risk:** [Critical / High / Medium / Low]
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
| Severity | Finding Count | Resolved in This Review | Carry-Over Risk |
|
||||
|----------|---------------|------------------------|-----------------|
|
||||
| Critical | [n] | [n] | [Yes/No — explain] |
|
||||
| High | [n] | [n] | [Yes/No — explain] |
|
||||
| Medium | [n] | [n] | [Yes/No — explain] |
|
||||
| Low | [n] | [n] | [Yes/No — explain] |
|
||||
| **Total** | **[n]** | **[n]** | |
|
||||
|
||||
**Recommendation:** [Approve / Approve with Required Changes / Block — one sentence rationale]
|
||||
|
||||
---
|
||||
|
||||
## Findings
|
||||
|
||||
### Critical Findings
|
||||
|
||||
#### CRIT-01: [Finding Title]
|
||||
|
||||
| Field | Detail |
|
||||
|-------|--------|
|
||||
| **Severity** | Critical |
|
||||
| **Category** | [IAM / Secrets / Encryption / Network / State / Naming / Cost] |
|
||||
| **Resource** | `[resource_type.resource_name]` |
|
||||
| **File / Line** | `[path/to/file.tf:42]` |
|
||||
| **Risk** | [What can go wrong — be specific about the attack vector or failure mode] |
|
||||
|
||||
**Current code:**
|
||||
```hcl
|
||||
# [paste the problematic snippet]
|
||||
resource "aws_s3_bucket" "data" {
|
||||
bucket = "my-bucket"
|
||||
acl = "public-read" # PROBLEM: public read access
|
||||
}
|
||||
```
|
||||
|
||||
**Remediation:**
|
||||
```hcl
|
||||
resource "aws_s3_bucket" "data" {
|
||||
bucket = "my-bucket"
|
||||
}
|
||||
|
||||
resource "aws_s3_bucket_public_access_block" "data" {
|
||||
bucket = aws_s3_bucket.data.id
|
||||
block_public_acls = true
|
||||
block_public_policy = true
|
||||
ignore_public_acls = true
|
||||
restrict_public_buckets = true
|
||||
}
|
||||
```
|
||||
|
||||
**Why this matters:** [One sentence linking the specific risk to business impact — data exposure, compliance violation, etc.]
|
||||
|
||||
---
|
||||
|
||||
#### CRIT-02: [Next Critical Finding — repeat structure]
|
||||
|
||||
---
|
||||
|
||||
### High Findings
|
||||
|
||||
#### HIGH-01: [Finding Title]
|
||||
|
||||
| Field | Detail |
|
||||
|-------|--------|
|
||||
| **Severity** | High |
|
||||
| **Category** | [Category] |
|
||||
| **Resource** | `[resource_type.resource_name]` |
|
||||
| **File / Line** | `[path/to/file.tf:line]` |
|
||||
| **Risk** | [Specific risk description] |
|
||||
|
||||
**Current code:**
|
||||
```hcl
|
||||
# [problematic snippet]
|
||||
```
|
||||
|
||||
**Remediation:**
|
||||
```hcl
|
||||
# [fixed snippet]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Medium Findings
|
||||
|
||||
#### MED-01: [Finding Title]
|
||||
|
||||
| Field | Detail |
|
||||
|-------|--------|
|
||||
| **Severity** | Medium |
|
||||
| **Category** | [Category] |
|
||||
| **Resource** | `[resource_type.resource_name]` |
|
||||
| **File / Line** | `[path/to/file.tf:line]` |
|
||||
| **Risk** | [Specific risk description] |
|
||||
|
||||
**Remediation:** [Prose or code snippet — choose whichever is clearer for this finding]
|
||||
|
||||
---
|
||||
|
||||
### Low Findings
|
||||
|
||||
#### LOW-01: [Finding Title]
|
||||
|
||||
| Field | Detail |
|
||||
|-------|--------|
|
||||
| **Severity** | Low |
|
||||
| **Category** | [Category] |
|
||||
| **Resource** | `[resource_type.resource_name]` |
|
||||
| **File / Line** | `[path/to/file.tf:line]` |
|
||||
| **Suggestion** | [What to improve and why] |
|
||||
|
||||
---
|
||||
|
||||
## Reusable IaC Review Checklist
|
||||
|
||||
Use this checklist on every IaC pull request. Check every item; mark N/A only when the item genuinely does not apply to the resources being provisioned.
|
||||
|
||||
### 1. IAM and Access Control
|
||||
|
||||
- [ ] No wildcard actions (`"*"`) in IAM policies — policies follow least-privilege
|
||||
- [ ] No wildcard resource (`"*"`) in IAM policies unless explicitly justified with a comment
|
||||
- [ ] IAM roles use condition keys to restrict scope (e.g., `aws:RequestedRegion`, `sts:ExternalId`)
|
||||
- [ ] No IAM access keys or credentials hardcoded or in plaintext variables
|
||||
- [ ] EC2 / compute instances use instance profiles, not hardcoded credentials
|
||||
- [ ] S3 bucket policies do not allow public access unless the bucket is explicitly a public asset bucket
|
||||
- [ ] Cross-account trust policies name specific account IDs, not `"*"`
|
||||
- [ ] Service accounts (GCP) / managed identities (Azure) follow naming conventions and have documented purpose
|
||||
|
||||
### 2. Secrets Management
|
||||
|
||||
- [ ] No secrets, passwords, tokens, or API keys in plaintext in any `.tf`, `.yaml`, or `.json` file
|
||||
- [ ] No secrets in variable default values
|
||||
- [ ] Secrets sourced from Secrets Manager / Parameter Store / Vault — not from environment variables passed at plan time
|
||||
- [ ] `sensitive = true` is set on all output values and variables that contain secrets (Terraform)
|
||||
- [ ] State backend is encrypted — no unencrypted state files contain sensitive data
|
||||
- [ ] `.gitignore` or equivalent excludes `*.tfvars`, `terraform.tfstate`, and any file that may contain resolved secrets
|
||||
|
||||
### 3. Encryption at Rest
|
||||
|
||||
- [ ] Storage resources (S3, EBS, RDS, DynamoDB, GCS, Azure Blob) have encryption at rest enabled
|
||||
- [ ] Customer-managed keys (CMK/KMS) are used where required by policy — not solely AWS/GCP/Azure managed keys
|
||||
- [ ] KMS key rotation is enabled for all CMKs
|
||||
- [ ] Database snapshots have encryption enabled
|
||||
- [ ] Encryption is not disabled via `encrypted = false` or equivalent
|
||||
|
||||
### 4. Encryption in Transit
|
||||
|
||||
- [ ] Load balancers terminate TLS — HTTP-only listeners redirect to HTTPS or are absent
|
||||
- [ ] Minimum TLS version is 1.2; TLS 1.0 and 1.1 are explicitly disabled
|
||||
- [ ] RDS / database connections require SSL (`require_ssl = true` or equivalent parameter)
|
||||
- [ ] Internal service-to-service calls use TLS where the network is not fully private
|
||||
- [ ] S3 bucket policies include a `Deny` on non-TLS requests (`aws:SecureTransport: false`)
|
||||
|
||||
### 5. Network and Public Access
|
||||
|
||||
- [ ] Security groups / firewall rules do not permit `0.0.0.0/0` ingress except on ports 80/443 for public-facing services
|
||||
- [ ] SSH (port 22) and RDP (port 3389) are not open to `0.0.0.0/0`
|
||||
- [ ] Databases are in private subnets — not directly internet-routable
|
||||
- [ ] `publicly_accessible = false` on RDS instances unless explicitly required and documented
|
||||
- [ ] VPC has flow logs enabled
|
||||
- [ ] Network ACLs and security groups are layered (defense in depth)
|
||||
- [ ] S3 bucket public access block is enabled at the account and bucket level
|
||||
|
||||
### 6. Logging, Monitoring, and Audit
|
||||
|
||||
- [ ] CloudTrail / Cloud Audit Logs / Azure Monitor is enabled across all regions
|
||||
- [ ] S3 access logging is enabled on buckets containing sensitive or regulated data
|
||||
- [ ] RDS enhanced monitoring or equivalent is enabled
|
||||
- [ ] CloudWatch alarms or equivalent are defined for critical metrics (CPU, disk, error rate)
|
||||
- [ ] Log retention periods are defined — logs not retained indefinitely or deleted within 7 days
|
||||
|
||||
### 7. Naming and Tagging Standards
|
||||
|
||||
- [ ] All resources follow the team's naming convention: `[env]-[team]-[resource-type]-[identifier]`
|
||||
- [ ] Required tags are present on all taggable resources:
|
||||
- [ ] `Environment` (e.g., prod / staging / dev)
|
||||
- [ ] `Team` or `Owner`
|
||||
- [ ] `Service` or `Application`
|
||||
- [ ] `CostCenter` (if required by finance policy)
|
||||
- [ ] `ManagedBy: terraform` (or equivalent IaC tool tag)
|
||||
- [ ] No resources with default names (e.g., `default-vpc`, `launch-wizard-1`)
|
||||
|
||||
### 8. State Management and Backend
|
||||
|
||||
- [ ] Remote state backend is configured — no local state in repository
|
||||
- [ ] State backend uses locking (DynamoDB for S3 backend, etc.)
|
||||
- [ ] State backend bucket/storage has versioning enabled
|
||||
- [ ] State backend bucket/storage has access logging enabled
|
||||
- [ ] Workspaces or separate state files are used per environment — no shared state between prod and non-prod
|
||||
- [ ] `terraform.tfstate` and `*.tfstate.backup` are in `.gitignore`
|
||||
|
||||
### 9. Module and Resource Structure
|
||||
|
||||
- [ ] Modules are versioned with explicit version pins — no floating `source = "git::...?ref=main"`
|
||||
- [ ] Provider versions are pinned in `required_providers` — no unconstrained `>= x.y`
|
||||
- [ ] Terraform version is pinned in `required_version`
|
||||
- [ ] Modules have a clear single responsibility — not one module that provisions everything
|
||||
- [ ] No copy-paste duplication — repeated patterns use modules or loops (`for_each`, `count`)
|
||||
- [ ] Outputs expose only what downstream consumers need — no unnecessary output sprawl
|
||||
|
||||
### 10. Environment Parity
|
||||
|
||||
- [ ] Prod and non-prod environments use the same module code, parameterized by environment variable
|
||||
- [ ] Instance sizes and replica counts differ by environment via variables — not by separate code branches
|
||||
- [ ] Non-prod does not have security controls disabled "to save money" (encryption off, logging off)
|
||||
|
||||
### 11. Cost Impact
|
||||
|
||||
- [ ] Large instance types (e.g., `r5.16xlarge`) or storage allocations are justified in a comment
|
||||
- [ ] Data transfer costs are considered for cross-region or cross-AZ architectures
|
||||
- [ ] Reserved instance or committed use discount eligibility is noted for long-lived resources
|
||||
- [ ] Auto-scaling is configured for variable workloads — no fixed oversized fleets for spiky traffic
|
||||
- [ ] Lifecycle policies are set on S3 buckets storing time-bounded data (logs, backups)
|
||||
|
||||
### 12. Drift Risk
|
||||
|
||||
- [ ] No resources that are commonly mutated in the console are managed by IaC without import documentation
|
||||
- [ ] `lifecycle { prevent_destroy = true }` is set on stateful resources in production (databases, state buckets)
|
||||
- [ ] `ignore_changes` is used sparingly and each instance is documented with a rationale comment
|
||||
- [ ] A plan is run against the live environment as part of the PR process — no unreviewed drift
|
||||
|
||||
---
|
||||
|
||||
## Findings Summary Table
|
||||
|
||||
| ID | Title | Severity | Category | File | Status |
|
||||
|----|-------|----------|----------|------|--------|
|
||||
| CRIT-01 | [Title] | Critical | [Category] | [file:line] | Open |
|
||||
| HIGH-01 | [Title] | High | [Category] | [file:line] | Open |
|
||||
| MED-01 | [Title] | Medium | [Category] | [file:line] | Open |
|
||||
| LOW-01 | [Title] | Low | [Category] | [file:line] | Open |
|
||||
|
||||
---
|
||||
|
||||
## Required Actions Before Merge
|
||||
|
||||
List only Critical and High findings that must be resolved before this code is merged:
|
||||
|
||||
1. **CRIT-01 [Title]** — [One-line remediation instruction]
|
||||
2. **HIGH-01 [Title]** — [One-line remediation instruction]
|
||||
|
||||
Medium and Low findings should be tracked as follow-up issues with a committed resolution date.
|
||||
|
||||
---
|
||||
|
||||
*Review conducted by [Reviewer] on [Date] — checklist version [1.0]*
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Every finding includes: severity, category, specific resource name, file and line number, current code, and fixed code
|
||||
- [ ] Checklist covers all 12 categories: IAM, Secrets, Encryption at Rest, Encryption in Transit, Network, Logging, Naming/Tagging, State, Module Structure, Environment Parity, Cost, and Drift
|
||||
- [ ] Executive summary table is filled with real counts — not all zeros or all placeholders
|
||||
- [ ] "Required Actions Before Merge" section lists only Critical and High items
|
||||
- [ ] Code snippets in findings show both the problematic code AND the corrected version
|
||||
- [ ] Overall risk rating is justified by the highest-severity open finding
|
||||
- [ ] Checklist items are binary (checkable) — not narrative observations
|
||||
@@ -0,0 +1,432 @@
|
||||
---
|
||||
name: load-testing-plan
|
||||
description: "Write a load and performance testing plan for a service. Use when asked to create a performance test plan, write load testing documentation, define stress or soak test scenarios, or set performance regression gates for CI. Produces a complete test plan document with scenario definitions, k6/Locust script skeleton, threshold table, result interpretation guide, and CI integration steps."
|
||||
---
|
||||
|
||||
# Load Testing Plan Skill
|
||||
|
||||
Produce a complete load and performance testing plan for a service — covering test objectives, scenario definitions, tooling configuration, success thresholds, and CI integration. A good load testing plan eliminates ambiguity about what "performance is acceptable" means, so engineers can run tests and get a pass/fail answer without having to interpret raw numbers themselves.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask for these if not already provided:
|
||||
- **Service name and key endpoints** — which endpoints are under test (path, method, typical request/response shape)
|
||||
- **Current traffic baseline** — current requests/sec, p50/p99 latency, error rate under normal load
|
||||
- **Peak traffic expectations** — expected peak RPS (e.g. 10× baseline for flash sales, or seasonality peak)
|
||||
- **SLO targets** — latency SLOs (p99 < X ms), error rate SLO (< Y%), availability target
|
||||
- **Preferred testing tool** — k6, Locust, JMeter, Gatling, or no preference
|
||||
- **Test environment availability** — dedicated load test environment, staging, or production (with traffic shaping)
|
||||
|
||||
## Output Format
|
||||
|
||||
---
|
||||
|
||||
# Load Testing Plan: [Service Name]
|
||||
|
||||
**Author:** [Name] | **Team:** [Team name]
|
||||
**Date:** [Date] | **Review cycle:** Before each major release and quarterly
|
||||
**Testing tool:** [k6 / Locust / JMeter / Gatling]
|
||||
**Test environment:** [Environment name and URL]
|
||||
|
||||
---
|
||||
|
||||
## 1. Objectives and Scope
|
||||
|
||||
**What we are testing:** [Service name] handles [describe function — e.g. "user authentication requests from the mobile and web clients"]. This plan validates that the service meets its SLOs under expected and elevated traffic conditions.
|
||||
|
||||
**In scope:**
|
||||
- [Endpoint 1: METHOD /path — description]
|
||||
- [Endpoint 2: METHOD /path — description]
|
||||
- [Endpoint 3: METHOD /path — description]
|
||||
|
||||
**Out of scope:**
|
||||
- [Any endpoints explicitly excluded and why — e.g. "admin APIs — low traffic, excluded from load test"]
|
||||
- [Third-party integrations that cannot be load-tested — mock them instead]
|
||||
|
||||
---
|
||||
|
||||
## 2. Performance Targets (Success Criteria)
|
||||
|
||||
Every scenario has explicit pass/fail thresholds. A test run FAILS if any threshold is breached.
|
||||
|
||||
| Metric | Baseline scenario | Stress scenario | Spike scenario | Soak scenario |
|
||||
|---|---|---|---|---|
|
||||
| p50 latency | < [X] ms | < [X × 1.5] ms | < [X × 2] ms | < [X] ms |
|
||||
| p95 latency | < [Y] ms | < [Y × 1.5] ms | < [Y × 2] ms | < [Y] ms |
|
||||
| p99 latency | < [Z] ms | < [Z × 2] ms | < [Z × 3] ms | < [Z] ms |
|
||||
| Error rate | < [0.1]% | < [1]% | < [2]% | < [0.1]% |
|
||||
| Throughput | ≥ [N] RPS | ≥ [N × 3] RPS | N/A | ≥ [N] RPS |
|
||||
| Failed requests | 0 (5xx) | < [threshold] | < [threshold] | 0 (5xx) |
|
||||
|
||||
**SLO reference:** These thresholds are derived from the service SLOs — p99 < [Z ms], error rate < [0.1]%, availability [99.9]%.
|
||||
|
||||
---
|
||||
|
||||
## 3. Traffic Model
|
||||
|
||||
**Baseline traffic (current production):**
|
||||
- Average RPS: [N] req/sec
|
||||
- Peak RPS (observed): [N] req/sec
|
||||
- Request distribution by endpoint:
|
||||
- [Endpoint 1]: [X]% of traffic
|
||||
- [Endpoint 2]: [Y]% of traffic
|
||||
- [Endpoint 3]: [Z]% of traffic
|
||||
|
||||
**Simulated user behaviour:**
|
||||
- Think time between requests: [X–Y] seconds (randomised)
|
||||
- Session duration: [N] minutes average
|
||||
- Authenticated vs anonymous ratio: [X]%/[Y]%
|
||||
- Geographic distribution: [Region 1 X]%, [Region 2 Y]%
|
||||
|
||||
---
|
||||
|
||||
## 4. Test Scenarios
|
||||
|
||||
### Scenario 1: Baseline (Steady-State)
|
||||
|
||||
**Purpose:** Confirm the service performs acceptably under normal production load.
|
||||
**Duration:** 10 minutes
|
||||
**Load profile:** Ramp to [N] RPS over 2 minutes, hold for 8 minutes.
|
||||
**Concurrency:** [N] virtual users
|
||||
|
||||
**Pass criteria:** All thresholds in the Baseline column of the targets table above.
|
||||
|
||||
---
|
||||
|
||||
### Scenario 2: Stress Test
|
||||
|
||||
**Purpose:** Find the breaking point — how much load can the service handle before SLOs are breached?
|
||||
**Duration:** 20–30 minutes
|
||||
**Load profile:** Ramp from [N] RPS (baseline) to [N × 5] RPS in 5-minute steps. Hold each step for 5 minutes. Stop at first SLO breach.
|
||||
**Concurrency:** Scales with RPS target
|
||||
|
||||
**What to record:**
|
||||
- RPS at which p99 latency first exceeds SLO
|
||||
- RPS at which error rate first exceeds SLO
|
||||
- Whether the service recovers when load drops back to baseline
|
||||
|
||||
---
|
||||
|
||||
### Scenario 3: Spike Test
|
||||
|
||||
**Purpose:** Simulate a sudden traffic surge (flash sale, viral event, bot attack).
|
||||
**Duration:** 15 minutes
|
||||
**Load profile:** Hold at [N] RPS (baseline) for 3 minutes, spike to [N × 10] RPS instantly, hold for 5 minutes, drop back to baseline for 7 minutes.
|
||||
|
||||
**What to record:**
|
||||
- Latency during spike and recovery
|
||||
- Whether the service sheds load gracefully (rate limiting, queue depth)
|
||||
- Time to recover to baseline latency after spike ends
|
||||
|
||||
---
|
||||
|
||||
### Scenario 4: Soak / Endurance Test
|
||||
|
||||
**Purpose:** Detect memory leaks, connection pool exhaustion, and slow degradation over time.
|
||||
**Duration:** 4–8 hours (run overnight)
|
||||
**Load profile:** Steady [N × 1.5] RPS (50% above baseline) for entire duration.
|
||||
|
||||
**What to watch:**
|
||||
- Memory usage trend over time (should not grow unboundedly)
|
||||
- Error rate trend (should be flat, not creeping up)
|
||||
- GC pause frequency (JVM/Go services)
|
||||
- Database connection pool utilisation
|
||||
- p99 latency trend (should not creep up over hours)
|
||||
|
||||
---
|
||||
|
||||
## 5. Test Environment Requirements
|
||||
|
||||
### Infrastructure
|
||||
|
||||
| Component | Requirement | Notes |
|
||||
|---|---|---|
|
||||
| Service under test | Isolated from production | [N] replicas, matching prod resource limits |
|
||||
| Database | Separate instance with production-scale data | Seed script in section 7 |
|
||||
| Cache (Redis/Memcached) | Empty at test start | Ensures cold-start conditions are tested |
|
||||
| Load generator | Separate from service under test | [N] vCPUs, [N] GB RAM minimum |
|
||||
| Network | Low-latency path to service | Do not run generator on same host |
|
||||
|
||||
### Data Seeding
|
||||
|
||||
Before every test run, ensure the environment has:
|
||||
```bash
|
||||
# Seed test users (needed for authenticated endpoint tests)
|
||||
[seed command or script path — e.g. python scripts/seed_load_test_users.py --count 10000]
|
||||
|
||||
# Seed test data for read endpoints
|
||||
[seed command — e.g. ./scripts/seed_products.sh --count 50000]
|
||||
|
||||
# Verify seed completed
|
||||
[verification command — e.g. psql $DB_URL -c "SELECT COUNT(*) FROM users WHERE load_test=true"]
|
||||
```
|
||||
|
||||
**Test data rules:**
|
||||
- Never use real production user data in load tests
|
||||
- Tag all test-generated records with `load_test=true` for easy cleanup
|
||||
- Run cleanup after each test: `[cleanup command]`
|
||||
|
||||
---
|
||||
|
||||
## 6. Tooling Setup
|
||||
|
||||
### k6 Script Skeleton
|
||||
|
||||
```javascript
|
||||
import http from 'k6/http';
|
||||
import { check, sleep } from 'k6';
|
||||
import { Rate, Trend } from 'k6/metrics';
|
||||
|
||||
// Custom metrics
|
||||
const errorRate = new Rate('error_rate');
|
||||
const endpointLatency = new Trend('endpoint_latency', true);
|
||||
|
||||
// Test configuration — override per scenario
|
||||
export const options = {
|
||||
scenarios: {
|
||||
baseline: {
|
||||
executor: 'ramping-vus',
|
||||
startVUs: 0,
|
||||
stages: [
|
||||
{ duration: '2m', target: [BASELINE_VUS] },
|
||||
{ duration: '8m', target: [BASELINE_VUS] },
|
||||
{ duration: '1m', target: 0 },
|
||||
],
|
||||
},
|
||||
},
|
||||
thresholds: {
|
||||
http_req_duration: [
|
||||
'p(95)<[Y_MS]',
|
||||
'p(99)<[Z_MS]',
|
||||
],
|
||||
error_rate: ['rate<0.01'],
|
||||
http_req_failed: ['rate<0.01'],
|
||||
},
|
||||
};
|
||||
|
||||
// Auth helper — get token once per VU
|
||||
export function setup() {
|
||||
const loginRes = http.post('[BASE_URL]/auth/login', JSON.stringify({
|
||||
username: `load_test_user_${Math.floor(Math.random() * 10000)}@example.com`,
|
||||
password: '[LOAD_TEST_PASSWORD]',
|
||||
}), { headers: { 'Content-Type': 'application/json' } });
|
||||
|
||||
check(loginRes, { 'login ok': (r) => r.status === 200 });
|
||||
return { token: loginRes.json('access_token') };
|
||||
}
|
||||
|
||||
export default function (data) {
|
||||
const headers = {
|
||||
Authorization: `Bearer ${data.token}`,
|
||||
'Content-Type': 'application/json',
|
||||
};
|
||||
|
||||
// Endpoint 1: [Description]
|
||||
const res1 = http.get('[BASE_URL]/[endpoint-1]', { headers });
|
||||
check(res1, {
|
||||
'[endpoint-1] status 200': (r) => r.status === 200,
|
||||
'[endpoint-1] latency < [X]ms': (r) => r.timings.duration < [X],
|
||||
});
|
||||
errorRate.add(res1.status >= 400);
|
||||
endpointLatency.add(res1.timings.duration, { endpoint: '[endpoint-1]' });
|
||||
|
||||
sleep(Math.random() * [THINK_TIME_MAX] + [THINK_TIME_MIN]);
|
||||
|
||||
// Endpoint 2: [Description]
|
||||
const res2 = http.post('[BASE_URL]/[endpoint-2]',
|
||||
JSON.stringify({ [key]: '[value]' }),
|
||||
{ headers }
|
||||
);
|
||||
check(res2, {
|
||||
'[endpoint-2] status 201': (r) => r.status === 201,
|
||||
});
|
||||
errorRate.add(res2.status >= 400);
|
||||
}
|
||||
```
|
||||
|
||||
### Locust Script Skeleton (alternative)
|
||||
|
||||
```python
|
||||
from locust import HttpUser, task, between
|
||||
import random
|
||||
|
||||
class [ServiceName]User(HttpUser):
|
||||
wait_time = between([THINK_TIME_MIN], [THINK_TIME_MAX])
|
||||
token = None
|
||||
|
||||
def on_start(self):
|
||||
"""Called once per simulated user — authenticate."""
|
||||
user_id = random.randint(1, 10000)
|
||||
response = self.client.post("/auth/login", json={
|
||||
"username": f"load_test_user_{user_id}@example.com",
|
||||
"password": "[LOAD_TEST_PASSWORD]",
|
||||
})
|
||||
self.token = response.json()["access_token"]
|
||||
self.headers = {"Authorization": f"Bearer {self.token}"}
|
||||
|
||||
@task([WEIGHT_1]) # Weight = relative frequency
|
||||
def [endpoint_1_task](self):
|
||||
"""[Endpoint 1 description]"""
|
||||
with self.client.get(
|
||||
"/[endpoint-1]",
|
||||
headers=self.headers,
|
||||
catch_response=True
|
||||
) as response:
|
||||
if response.elapsed.total_seconds() > [LATENCY_THRESHOLD]:
|
||||
response.failure(f"Too slow: {response.elapsed.total_seconds()}s")
|
||||
|
||||
@task([WEIGHT_2])
|
||||
def [endpoint_2_task](self):
|
||||
"""[Endpoint 2 description]"""
|
||||
self.client.post(
|
||||
"/[endpoint-2]",
|
||||
json={"[key]": "[value]"},
|
||||
headers=self.headers,
|
||||
)
|
||||
```
|
||||
|
||||
### Running Tests
|
||||
|
||||
```bash
|
||||
# k6 — run baseline scenario
|
||||
k6 run --env BASE_URL=https://[test-env-url] scripts/load_test.js
|
||||
|
||||
# k6 — run stress scenario with output to InfluxDB
|
||||
k6 run --out influxdb=http://[influxdb-host]:8086/k6 \
|
||||
--env SCENARIO=stress \
|
||||
scripts/load_test.js
|
||||
|
||||
# Locust — headless run
|
||||
locust -f locustfile.py \
|
||||
--headless \
|
||||
--users [N] \
|
||||
--spawn-rate [N] \
|
||||
--run-time 10m \
|
||||
--host https://[test-env-url] \
|
||||
--csv=results/[run-id]
|
||||
|
||||
# Locust — web UI (interactive)
|
||||
locust -f locustfile.py --host https://[test-env-url]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Metrics to Capture
|
||||
|
||||
Capture all of the following during every test run. Missing any of these makes result comparison unreliable.
|
||||
|
||||
| Metric | Source | Why it matters |
|
||||
|---|---|---|
|
||||
| p50, p95, p99, p999 latency per endpoint | Load tool | SLO validation |
|
||||
| Error rate (4xx, 5xx) per endpoint | Load tool | SLO validation |
|
||||
| Requests/sec (throughput) | Load tool | Capacity baseline |
|
||||
| CPU utilisation (%) | Infra monitoring | Saturation signal |
|
||||
| Memory utilisation (%) | Infra monitoring | Leak detection |
|
||||
| GC pause time / frequency | JVM/Go metrics | Latency spike root cause |
|
||||
| DB connection pool: active/idle/waiting | DB metrics | Pool exhaustion detection |
|
||||
| DB query latency (p99) | DB metrics | Downstream bottleneck |
|
||||
| Cache hit rate | Cache metrics | Miss storm detection |
|
||||
| Pod/instance count (if autoscaling) | Infra | Scaling behaviour |
|
||||
| Network in/out bytes | Infra | Bandwidth saturation |
|
||||
|
||||
---
|
||||
|
||||
## 8. Result Analysis Framework
|
||||
|
||||
After each test run, work through this analysis in order:
|
||||
|
||||
**Step 1 — Pass/fail check**
|
||||
Compare all captured metrics against the thresholds in Section 2. Record pass/fail per scenario.
|
||||
|
||||
**Step 2 — Latency distribution**
|
||||
Plot the full latency histogram, not just percentiles. A bimodal distribution (two humps) indicates two distinct code paths — investigate the slow hump.
|
||||
|
||||
**Step 3 — Error correlation**
|
||||
If errors occurred, correlate them with:
|
||||
- Time of occurrence (was it during ramp-up, steady state, or spike?)
|
||||
- Specific endpoint (is it one endpoint or all?)
|
||||
- Infrastructure events (CPU spike, OOM, DB connection exhaustion?)
|
||||
|
||||
**Step 4 — Saturation analysis**
|
||||
Graph CPU, memory, and connection pool over time. If any resource reached 80%+ of capacity, it is a candidate bottleneck — even if SLOs passed this run.
|
||||
|
||||
**Step 5 — Compare to baseline run**
|
||||
Every run should be compared to the previous run. A 10% regression in p99 latency warrants investigation even if it is still within SLO.
|
||||
|
||||
**Regression classification:**
|
||||
|
||||
| Change | Classification | Action |
|
||||
|---|---|---|
|
||||
| p99 within 5% of previous run | Green — no regression | No action |
|
||||
| p99 5–15% worse than previous | Yellow — watch | Investigate before next release |
|
||||
| p99 >15% worse than previous | Red — regression | Block release, file ticket |
|
||||
| Error rate increased vs previous | Red — regression | Block release |
|
||||
| SLO threshold breached | Critical | Block release, page on-call |
|
||||
|
||||
---
|
||||
|
||||
## 9. CI Integration
|
||||
|
||||
Add load tests as a gated step in the release pipeline. Run the baseline scenario on every release candidate; run all scenarios weekly.
|
||||
|
||||
```yaml
|
||||
# Example: GitHub Actions step (adapt for your CI platform)
|
||||
load-test:
|
||||
runs-on: ubuntu-latest
|
||||
needs: [deploy-staging]
|
||||
if: github.ref == 'refs/heads/main'
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
|
||||
- name: Install k6
|
||||
run: |
|
||||
curl -s https://dl.k6.io/key.gpg | sudo apt-key add -
|
||||
echo "deb https://dl.k6.io/deb stable main" | sudo tee /etc/apt/sources.list.d/k6.list
|
||||
sudo apt-get update && sudo apt-get install k6
|
||||
|
||||
- name: Seed test data
|
||||
run: [seed command]
|
||||
|
||||
- name: Run baseline load test
|
||||
run: |
|
||||
k6 run \
|
||||
--env BASE_URL=${{ secrets.LOAD_TEST_ENV_URL }} \
|
||||
--out json=results.json \
|
||||
scripts/load_test.js
|
||||
env:
|
||||
LOAD_TEST_ENV_URL: ${{ secrets.LOAD_TEST_ENV_URL }}
|
||||
|
||||
- name: Check thresholds
|
||||
run: |
|
||||
# k6 exits with non-zero if any threshold fails — this step fails the build
|
||||
echo "k6 threshold check complete"
|
||||
|
||||
- name: Upload results
|
||||
uses: actions/upload-artifact@v3
|
||||
if: always()
|
||||
with:
|
||||
name: load-test-results-${{ github.run_id }}
|
||||
path: results.json
|
||||
|
||||
- name: Cleanup test data
|
||||
if: always()
|
||||
run: [cleanup command]
|
||||
```
|
||||
|
||||
**CI gates summary:**
|
||||
- Baseline scenario runs on every release to staging
|
||||
- Full scenario suite (stress, spike, soak) runs weekly on a schedule
|
||||
- Any threshold failure blocks promotion to production
|
||||
- Results are archived for trend analysis
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] All key endpoints are covered by at least one test scenario — no production endpoint is untested
|
||||
- [ ] Thresholds are derived from actual SLO targets, not guesses
|
||||
- [ ] Test data seeding is scripted and reproducible — tests do not rely on pre-existing environment state
|
||||
- [ ] The load generator runs on separate infrastructure from the service under test
|
||||
- [ ] CI integration blocks promotion on threshold failure — not just records results
|
||||
- [ ] Soak test has been run at least once to establish a memory and connection pool baseline
|
||||
- [ ] Results comparison to previous run is part of the analysis — not just absolute pass/fail
|
||||
@@ -0,0 +1,484 @@
|
||||
---
|
||||
name: local-dev-setup
|
||||
description: "Write a local development environment setup guide for a service or project — covering prerequisites, repository setup, environment variables, local service dependencies, database seeding, running the service, running tests, common gotchas, IDE recommendations, and first-contribution checklist. Use when asked to write a dev setup guide, create onboarding documentation for engineers, document local environment setup, or write a getting-started guide for a codebase. Produces a complete setup guide that a new engineer can follow from zero to running tests in under 30 minutes, with a troubleshooting section for the most common setup failures."
|
||||
---
|
||||
|
||||
# Local Dev Setup Skill
|
||||
|
||||
Produce a complete local development environment setup guide for a service or project — walking a new engineer from zero (a clean laptop) to a working local environment with passing tests in under 30 minutes. A good setup guide reduces onboarding time, prevents the "it works on my machine" problem, and lets engineers make their first contribution with confidence. Write every step as a concrete command or action — not a description of what needs to happen.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask for these if not already provided:
|
||||
- **Service name** and what it does
|
||||
- **Tech stack** — language, framework, database, cache, message queue, and any external services
|
||||
- **Dependencies** — databases, caches, message queues, and external services (mocked or real)
|
||||
- **Test framework** — how tests are run and what the test suite covers
|
||||
- **CI/CD platform** — GitHub Actions, CircleCI, Jenkins, etc. (for context on what "passing CI" means locally)
|
||||
|
||||
## Output Format
|
||||
|
||||
---
|
||||
|
||||
# Local Development Setup: [Service Name]
|
||||
|
||||
**Tech stack:** [Language + version] | [Framework] | [Database] | [Cache]
|
||||
**Estimated setup time:** [20–30 minutes] on a clean machine
|
||||
**Last verified:** [Date] on [macOS Ventura 13.x / Ubuntu 22.04]
|
||||
**Questions?** Ask in [Slack: #[team-channel]] or ping [@tech-lead-handle]
|
||||
|
||||
> **First contribution?** Complete setup first (this doc), then read [CONTRIBUTING.md] for code standards and PR process.
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Install these tools before starting. The versions listed are the minimum required — newer patch versions are fine, newer major versions may have compatibility issues.
|
||||
|
||||
### Required Tools
|
||||
|
||||
| Tool | Required version | Install |
|
||||
|---|---|---|
|
||||
| [Git] | 2.x+ | Pre-installed on most systems; or `brew install git` |
|
||||
| [Language runtime — e.g. Go] | [1.22+] | [https://go.dev/dl/ or `brew install go`] |
|
||||
| [Docker] | 24.x+ | [https://docs.docker.com/get-docker/] |
|
||||
| [Docker Compose] | 2.x+ | Included with Docker Desktop; or `brew install docker-compose` |
|
||||
| [Make] | Any | Pre-installed on macOS/Linux |
|
||||
| [Tool — e.g. Node.js] | [20.x+] | [`brew install node` or https://nodejs.org] |
|
||||
| [Tool — e.g. psql client] | [15+] | `brew install postgresql@15` (client only) |
|
||||
|
||||
### Optional but Recommended
|
||||
|
||||
| Tool | Purpose | Install |
|
||||
|---|---|---|
|
||||
| [direnv] | Auto-load `.envrc` environment variables | `brew install direnv` + [setup instructions](https://direnv.net) |
|
||||
| [jq] | Pretty-print JSON in terminal | `brew install jq` |
|
||||
| [k9s] | Kubernetes cluster UI (if using K8s locally) | `brew install k9s` |
|
||||
| [mkcert] | Local HTTPS certificates | `brew install mkcert` |
|
||||
|
||||
### Required Accounts and Access
|
||||
|
||||
Before starting, make sure you have:
|
||||
- [ ] GitHub access to [org/repo] — request via [access request process / Slack: #it-help]
|
||||
- [ ] [AWS / GCP / Azure] account with [dev environment] access — request via [process]
|
||||
- [ ] [Internal tool — e.g. 1Password] for retrieving development secrets — request via [process]
|
||||
- [ ] [VPN access] if required to reach internal services — request via [process]
|
||||
|
||||
---
|
||||
|
||||
## 1. Repository Setup
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone git@github.com:[org]/[repo-name].git
|
||||
cd [repo-name]
|
||||
|
||||
# Install git hooks (required — enforces commit message format and runs pre-commit checks)
|
||||
make install-hooks
|
||||
# Or manually:
|
||||
# cp scripts/hooks/pre-commit .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit
|
||||
|
||||
# Verify your git setup
|
||||
git config user.name # should be your name
|
||||
git config user.email # should be your work email
|
||||
```
|
||||
|
||||
**If you see a permission denied error on clone:** Your SSH key is not added to GitHub. Follow [GitHub's SSH key guide](https://docs.github.com/en/authentication/connecting-to-github-with-ssh) or use HTTPS with a personal access token instead.
|
||||
|
||||
---
|
||||
|
||||
## 2. Environment Variables
|
||||
|
||||
The service requires environment variables for configuration. **Never commit actual secrets to the repository.**
|
||||
|
||||
### Step 1 — Copy the example file
|
||||
|
||||
```bash
|
||||
cp .env.example .env.local
|
||||
```
|
||||
|
||||
### Step 2 — Fill in the values
|
||||
|
||||
Open `.env.local` in your editor. Below is a description of every variable and where to get its value:
|
||||
|
||||
| Variable | Description | Where to get it | Example (not real) |
|
||||
|---|---|---|---|
|
||||
| `APP_ENV` | Environment name | Set to `development` | `development` |
|
||||
| `APP_PORT` | Port the service listens on | Set to `8080` for local | `8080` |
|
||||
| `DATABASE_URL` | PostgreSQL connection string | Use value from Docker Compose (Section 3) | `postgres://app:password@localhost:5432/[service]_dev` |
|
||||
| `REDIS_URL` | Redis connection string | Use value from Docker Compose | `redis://localhost:6379` |
|
||||
| `SECRET_KEY` | Application secret key | Generate with: `openssl rand -hex 32` | `[random 64-char hex]` |
|
||||
| `[EXTERNAL_SERVICE]_API_KEY` | API key for [External Service] | Retrieve from [1Password vault: "Dev API Keys"] or ask [name] | — |
|
||||
| `[EXTERNAL_SERVICE]_BASE_URL` | Base URL for [External Service] | Use sandbox URL: `https://sandbox.[external-service].com` | `https://sandbox.stripe.com` |
|
||||
| `LOG_LEVEL` | Logging verbosity | Set to `debug` for local development | `debug` |
|
||||
| `[FEATURE_FLAG_SDK_KEY]` | Feature flag platform SDK key | Retrieve from [LaunchDarkly/Split dev project] | — |
|
||||
|
||||
**Using direnv (recommended):** Rename `.env.local` to `.envrc`, add `dotenv` at the top, and run `direnv allow`. Variables will load automatically when you `cd` into the project.
|
||||
|
||||
---
|
||||
|
||||
## 3. Local Service Dependencies
|
||||
|
||||
All infrastructure dependencies run in Docker Compose. You do not need to install PostgreSQL, Redis, or Kafka locally.
|
||||
|
||||
```bash
|
||||
# Start all dependencies (PostgreSQL, Redis, and any other services)
|
||||
docker compose up -d
|
||||
|
||||
# Verify all containers are healthy
|
||||
docker compose ps
|
||||
# Expected output: all services show "healthy" status
|
||||
|
||||
# View logs if something is not healthy
|
||||
docker compose logs [service-name]
|
||||
```
|
||||
|
||||
### What Docker Compose Starts
|
||||
|
||||
| Service | Port | Purpose | Health check |
|
||||
|---|---|---|---|
|
||||
| PostgreSQL [version] | `5432` | Primary database | `pg_isready -U app` |
|
||||
| Redis [version] | `6379` | Cache and session store | `redis-cli ping` |
|
||||
| [Kafka + Zookeeper] | `9092` / `2181` | Message queue | `kafka-topics.sh --list` |
|
||||
| [Mock server — e.g. WireMock] | `8089` | Mocks for external APIs in tests | `curl localhost:8089/__admin` |
|
||||
| [LocalStack] | `4566` | AWS service emulation (S3, SQS, etc.) | `aws --endpoint-url=http://localhost:4566 s3 ls` |
|
||||
|
||||
**If a container exits immediately:** See Troubleshooting section — common causes are port conflicts and Docker memory limits.
|
||||
|
||||
### Stopping Dependencies
|
||||
|
||||
```bash
|
||||
# Stop containers (preserves data volumes)
|
||||
docker compose stop
|
||||
|
||||
# Stop and remove containers (clears data — use when you want a fresh start)
|
||||
docker compose down -v
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Install Dependencies and Build
|
||||
|
||||
```bash
|
||||
# Install language dependencies
|
||||
# Go:
|
||||
go mod download
|
||||
|
||||
# Node.js:
|
||||
npm install # or: yarn install / pnpm install
|
||||
|
||||
# Python:
|
||||
python -m venv .venv
|
||||
source .venv/bin/activate # On Windows: .venv\Scripts\activate
|
||||
pip install -r requirements-dev.txt
|
||||
|
||||
# Verify build compiles cleanly
|
||||
make build
|
||||
# Expected: no errors; binary or compiled output in [./bin/ or ./dist/]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Database Setup and Seeding
|
||||
|
||||
```bash
|
||||
# Run database migrations (creates tables and schema)
|
||||
make db-migrate
|
||||
# Or directly:
|
||||
# [Migration command — e.g. "go run ./cmd/migrate up" or "alembic upgrade head" or "npm run db:migrate"]
|
||||
|
||||
# Verify migrations applied
|
||||
# psql $DATABASE_URL -c "\dt" # should list all tables
|
||||
|
||||
# Seed the database with development data
|
||||
make db-seed
|
||||
# Or directly:
|
||||
# [Seed command — e.g. "go run ./cmd/seed" or "python scripts/seed.py" or "npm run db:seed"]
|
||||
|
||||
# Verify seed data is present
|
||||
# psql $DATABASE_URL -c "SELECT COUNT(*) FROM [primary-table]"
|
||||
# Expected: [N] rows
|
||||
```
|
||||
|
||||
**What the seed creates:**
|
||||
- [N] test user accounts (credentials in [scripts/seed/README.md or .env.example])
|
||||
- [N] sample [resources] for development and testing
|
||||
- Admin account: `[admin@example.com]` / password: see `.env.example` for dev password variable
|
||||
|
||||
**To reset to a clean state:**
|
||||
```bash
|
||||
docker compose down -v # wipe database volume
|
||||
docker compose up -d # start fresh
|
||||
make db-migrate
|
||||
make db-seed
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Running the Service
|
||||
|
||||
```bash
|
||||
# Run the service locally
|
||||
make run
|
||||
# Or directly:
|
||||
# [Run command — e.g. "go run ./cmd/server" or "python app.py" or "npm run dev"]
|
||||
|
||||
# Expected output:
|
||||
# [Example of healthy startup log lines — e.g.:]
|
||||
# {"level":"info","message":"Database connected","host":"localhost","port":5432}
|
||||
# {"level":"info","message":"Redis connected","host":"localhost","port":6379}
|
||||
# {"level":"info","message":"Server listening","port":8080}
|
||||
```
|
||||
|
||||
### Verify It's Working
|
||||
|
||||
```bash
|
||||
# Health check
|
||||
curl http://localhost:8080/health
|
||||
# Expected: {"status":"ok","version":"[git-sha]"}
|
||||
|
||||
# Test a key endpoint (authenticated)
|
||||
# First, get a dev token:
|
||||
curl -X POST http://localhost:8080/api/v1/auth/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"email":"[dev-user-from-seed]@example.com","password":"[dev-password-from-env]"}'
|
||||
# Copy the token from the response, then:
|
||||
|
||||
curl http://localhost:8080/api/v1/[resource] \
|
||||
-H "Authorization: Bearer [token-from-above]"
|
||||
# Expected: 200 with JSON response
|
||||
```
|
||||
|
||||
### Hot Reload (for Development)
|
||||
|
||||
```bash
|
||||
# Run with hot reload — service restarts automatically on file changes
|
||||
make run-dev
|
||||
# Or:
|
||||
# [Hot reload command — e.g. "air" for Go / "uvicorn --reload" for Python / "npm run dev" for Node]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Running Tests
|
||||
|
||||
```bash
|
||||
# Run the full test suite
|
||||
make test
|
||||
# Or:
|
||||
# [Test command — e.g. "go test ./..." or "pytest" or "npm test"]
|
||||
|
||||
# Run tests with coverage report
|
||||
make test-coverage
|
||||
# Coverage report: [./coverage.html or stdout]
|
||||
|
||||
# Run a specific test file or test case
|
||||
# Go: go test ./pkg/[package]/... -run TestFunctionName
|
||||
# Python: pytest tests/test_[module].py::TestClass::test_method -v
|
||||
# Node: npm test -- --testPathPattern=[filename]
|
||||
|
||||
# Run only unit tests (fast — no external dependencies)
|
||||
make test-unit
|
||||
|
||||
# Run only integration tests (requires Docker Compose dependencies running)
|
||||
make test-integration
|
||||
```
|
||||
|
||||
**Expected test results:**
|
||||
- Unit tests: [N] tests, all pass, [<30] seconds
|
||||
- Integration tests: [N] tests, all pass, [<2] minutes
|
||||
- Coverage: [≥80]% (enforced in CI — tests fail below this threshold)
|
||||
|
||||
**Before pushing a PR, always run:**
|
||||
```bash
|
||||
make lint # code linting — must pass
|
||||
make test # full test suite — must pass
|
||||
make build # verify compilation — must pass
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. IDE Setup
|
||||
|
||||
### VS Code (Recommended)
|
||||
|
||||
Install the recommended extensions (VS Code will prompt you automatically):
|
||||
|
||||
```json
|
||||
// .vscode/extensions.json — already in the repository
|
||||
{
|
||||
"recommendations": [
|
||||
"[language-extension — e.g. golang.go]",
|
||||
"dbaeumer.vscode-eslint",
|
||||
"esbenp.prettier-vscode",
|
||||
"ms-azuretools.vscode-docker",
|
||||
"eamodio.gitlens"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Workspace settings are in `.vscode/settings.json` — format on save is enabled, linter is configured automatically.
|
||||
|
||||
**[Language]-specific setup:**
|
||||
```
|
||||
[e.g. Go: The gopls language server is installed automatically by the Go extension.
|
||||
Run "Go: Install/Update Tools" from the command palette after installing the extension.]
|
||||
```
|
||||
|
||||
### JetBrains (IntelliJ / GoLand / PyCharm / WebStorm)
|
||||
|
||||
- Open the project root as the project directory
|
||||
- [Language SDK]: set to [version] — File → Project Structure → SDKs
|
||||
- Run configurations are checked into `.idea/runConfigurations/` — they appear automatically
|
||||
- Enable "Run formatters on save" in Settings → Tools → Actions on Save
|
||||
|
||||
---
|
||||
|
||||
## 9. Common Gotchas and Troubleshooting
|
||||
|
||||
### Docker container exits immediately on startup
|
||||
|
||||
**Symptom:** `docker compose ps` shows a container as `Exited (1)` seconds after starting.
|
||||
|
||||
```bash
|
||||
# Check the container logs for the error
|
||||
docker compose logs [container-name]
|
||||
|
||||
# Common causes:
|
||||
# 1. Port already in use — find and kill the conflicting process:
|
||||
lsof -ti tcp:[port] | xargs kill -9
|
||||
|
||||
# 2. Docker doesn't have enough memory — allocate at least 4GB in Docker Desktop:
|
||||
# Docker Desktop → Settings → Resources → Memory → 4GB
|
||||
|
||||
# 3. M1/M2 Mac architecture mismatch — add platform directive to docker-compose.yml:
|
||||
# platform: linux/amd64
|
||||
```
|
||||
|
||||
### Database connection refused
|
||||
|
||||
**Symptom:** Service fails to start with "connection refused" or "dial tcp localhost:5432: connect: connection refused"
|
||||
|
||||
```bash
|
||||
# Is PostgreSQL actually running?
|
||||
docker compose ps postgres
|
||||
# If not running: docker compose up -d postgres
|
||||
|
||||
# Is it on the right port?
|
||||
lsof -i :5432
|
||||
|
||||
# Can you connect manually?
|
||||
psql postgres://app:password@localhost:5432/[service]_dev -c "SELECT 1"
|
||||
|
||||
# If using a custom DATABASE_URL, verify it matches the docker-compose.yml settings exactly
|
||||
```
|
||||
|
||||
### Migrations fail with "relation already exists"
|
||||
|
||||
**Symptom:** `make db-migrate` errors with "ERROR: relation [table] already exists"
|
||||
|
||||
```bash
|
||||
# Check current migration state
|
||||
[migration status command — e.g. "go run ./cmd/migrate status" or "alembic current"]
|
||||
|
||||
# The database may be in a partial state — reset it:
|
||||
docker compose down -v
|
||||
docker compose up -d
|
||||
make db-migrate # should now succeed on a clean database
|
||||
```
|
||||
|
||||
### Tests fail with "connection refused" or dependency errors
|
||||
|
||||
**Symptom:** Integration tests fail because they cannot connect to PostgreSQL or Redis.
|
||||
|
||||
```bash
|
||||
# Integration tests need Docker Compose running
|
||||
docker compose up -d
|
||||
|
||||
# Verify all containers are healthy before running tests
|
||||
docker compose ps # all should show "healthy"
|
||||
|
||||
# If containers are running but tests still fail, check environment variables:
|
||||
make test-integration # should pick up .env.local automatically
|
||||
# If not: source .env.local && make test-integration
|
||||
```
|
||||
|
||||
### `make lint` fails on a fresh checkout
|
||||
|
||||
**Symptom:** Lint errors on files you have not modified.
|
||||
|
||||
```bash
|
||||
# Formatting issue — auto-fix with:
|
||||
# Go:
|
||||
gofmt -w .
|
||||
goimports -w .
|
||||
|
||||
# Python:
|
||||
black .
|
||||
isort .
|
||||
|
||||
# Node/TypeScript:
|
||||
npm run lint:fix
|
||||
# Or: npx eslint --fix . && npx prettier --write .
|
||||
|
||||
# Re-run lint to confirm
|
||||
make lint
|
||||
```
|
||||
|
||||
### Environment variables not loading
|
||||
|
||||
**Symptom:** Service starts but immediately fails with "missing required environment variable: [VAR]"
|
||||
|
||||
```bash
|
||||
# Verify .env.local exists and has all required variables
|
||||
cat .env.local | grep "^[A-Z]" | awk -F= '{print $1}'
|
||||
|
||||
# Compare against required variables in .env.example
|
||||
diff <(grep "^[A-Z_]*=" .env.example | cut -d= -f1 | sort) \
|
||||
<(grep "^[A-Z_]*=" .env.local | cut -d= -f1 | sort)
|
||||
|
||||
# Missing variables are shown in left column only (< prefix)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. First Contribution Checklist
|
||||
|
||||
Before opening your first pull request, verify:
|
||||
|
||||
**Setup complete:**
|
||||
- [ ] `make build` passes with no errors
|
||||
- [ ] `make test` passes — all tests green
|
||||
- [ ] `make lint` passes — no lint errors
|
||||
- [ ] Service starts and health check returns 200
|
||||
- [ ] You can authenticate and call at least one API endpoint
|
||||
|
||||
**Git and GitHub:**
|
||||
- [ ] You have read [CONTRIBUTING.md] — code standards, commit message format, PR process
|
||||
- [ ] Your git user.name and user.email are set correctly
|
||||
- [ ] Pre-commit hooks are installed (`ls .git/hooks/pre-commit` should exist)
|
||||
- [ ] You have branched from `main` (not committing directly to main)
|
||||
|
||||
**Development workflow:**
|
||||
- [ ] You know how to run a specific test: `[test command for single test]`
|
||||
- [ ] You know how to reset the database: `docker compose down -v && docker compose up -d && make db-migrate && make db-seed`
|
||||
- [ ] You have joined [Slack: #[team-channel]] and [#[service-consumers-channel] if applicable]
|
||||
- [ ] You have read the [architecture overview doc / README] — you understand what this service does
|
||||
|
||||
**First PR:**
|
||||
- [ ] Changes are small and focused — one logical change per PR
|
||||
- [ ] Tests are added or updated for your change
|
||||
- [ ] `make test && make lint && make build` all pass locally before requesting review
|
||||
- [ ] PR description explains what changed and why (use the [pr-description-writer skill] if needed)
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] A new engineer with no prior knowledge of the project can follow this guide from start to finish without asking anyone for help
|
||||
- [ ] Every command is tested on a clean environment — not written from memory and assumed to work
|
||||
- [ ] Environment variables table covers every variable in `.env.example` — no undocumented variables
|
||||
- [ ] The troubleshooting section covers the 5 most common real failures observed during onboarding — not theoretical issues
|
||||
- [ ] Docker Compose version and Docker Desktop memory requirements are stated explicitly
|
||||
- [ ] "Expected output" is shown for key commands so engineers know whether a step succeeded
|
||||
- [ ] Setup time estimate is honest — verified by timing a real onboarding session, not estimated
|
||||
@@ -0,0 +1,290 @@
|
||||
---
|
||||
name: microservices-decomposition
|
||||
description: "Design a microservices decomposition for a monolith or new system, defining service boundaries, ownership, communication patterns, and migration plan. Use when asked to decompose a monolith, define service boundaries, design a microservices architecture, or plan a strangler-fig migration. Produces a bounded context map, service inventory table, communication pattern decisions, data ownership matrix, migration roadmap, and risk register."
|
||||
---
|
||||
|
||||
# Microservices Decomposition
|
||||
|
||||
Produce a complete microservices decomposition design for a system — whether decomposing an existing monolith or designing service boundaries for a new system. Ground the decomposition in Domain-Driven Design (DDD) concepts: identify bounded contexts first, then derive service boundaries from them. Include communication pattern decisions (sync vs. async, event vs. RPC), data ownership rules, and a pragmatic migration plan if decomposing a monolith. Conway's Law is real — include an organizational alignment section. The deliverable should be specific enough that a team can begin implementation, not an abstract architectural diagram.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask for these if not already provided:
|
||||
- **System or domain description** — what the system does, its core domain, and the key business processes it supports
|
||||
- **Current architecture** — monolith (describe the tech stack and rough module structure), partial services (list existing services), or greenfield
|
||||
- **Team structure** — number of teams, team names if known, and approximate team sizes; this drives service ownership
|
||||
- **Performance and scalability requirements** — any specific SLAs, load characteristics, or scaling constraints per domain area
|
||||
- **Migration constraints** — what cannot be rewritten all at once, hard deadlines, zero-downtime requirements, budget constraints
|
||||
- **Integration points** — external systems, third-party APIs, or legacy systems that cannot be changed
|
||||
|
||||
If decomposing a monolith, also ask for: approximate codebase size, what is most painful to change today, and where the team experiences the most coupling-related friction.
|
||||
|
||||
## Output Format
|
||||
|
||||
---
|
||||
|
||||
# Microservices Decomposition: [System Name]
|
||||
|
||||
**Author:** [Name / Team]
|
||||
**Date:** [Date]
|
||||
**Architecture type:** [Monolith decomposition / New system design]
|
||||
**Current state:** [One sentence describing what exists today]
|
||||
**Target state:** [One sentence describing the desired end state]
|
||||
|
||||
---
|
||||
|
||||
## 1. Domain Analysis
|
||||
|
||||
### Core Domain
|
||||
|
||||
[One paragraph: what is the core domain of this system? What does the business fundamentally do? What gives it competitive differentiation? The core domain gets the most investment and the cleanest service boundaries.]
|
||||
|
||||
### Domain Map
|
||||
|
||||
List every significant subdomain before assigning service boundaries. Classify each subdomain:
|
||||
|
||||
| Subdomain | Type | Description | Current Location in Monolith |
|
||||
|-----------|------|-------------|------------------------------|
|
||||
| [Subdomain, e.g., Order Management] | Core | [What it does and why it matters] | [Module/package name or "new"] |
|
||||
| [Subdomain, e.g., Inventory] | Core | [Description] | [Location] |
|
||||
| [Subdomain, e.g., Notifications] | Supporting | [Description] | [Location] |
|
||||
| [Subdomain, e.g., Billing] | Supporting | [Description] | [Location] |
|
||||
| [Subdomain, e.g., Reporting] | Generic | [Description — candidates for off-the-shelf solutions] | [Location] |
|
||||
| [Subdomain, e.g., User Auth] | Generic | [Description] | [Location] |
|
||||
|
||||
**Subdomain types:** Core = competitive differentiation, build with care; Supporting = necessary but not differentiating, build pragmatically; Generic = commodity, buy or use open source.
|
||||
|
||||
---
|
||||
|
||||
## 2. Bounded Context Map (ASCII)
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ [System Name] │
|
||||
│ │
|
||||
│ ┌──────────────────┐ ┌──────────────────┐ │
|
||||
│ │ [Context A] │ │ [Context B] │ │
|
||||
│ │ │─ ─►│ │ │
|
||||
│ │ [key concepts] │ │ [key concepts] │ │
|
||||
│ └──────────────────┘ └──────────────────┘ │
|
||||
│ │ │ │
|
||||
│ │ event │ sync │
|
||||
│ ▼ ▼ │
|
||||
│ ┌──────────────────┐ ┌──────────────────┐ │
|
||||
│ │ [Context C] │ │ [Context D] │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ [key concepts] │ │ [key concepts] │ │
|
||||
│ └──────────────────┘ └──────────────────┘ │
|
||||
│ │ │
|
||||
│ ┌────────┘ │
|
||||
│ ▼ │
|
||||
│ ┌──────────────────┐ │
|
||||
│ │ [Context E] │ │
|
||||
│ │ [key concepts] │ │
|
||||
│ └──────────────────┘ │
|
||||
│ │
|
||||
│ External: [Third-party system] ──► [Context that owns it] │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
|
||||
Legend: ──► sync call - -► async event ═══ shared kernel
|
||||
```
|
||||
|
||||
Render this map using the actual bounded contexts derived from the domain analysis. Place contexts that communicate frequently closer together. Label relationship types on arrows.
|
||||
|
||||
### Context Relationships
|
||||
|
||||
| Upstream Context | Downstream Context | Relationship Type | Integration Pattern |
|
||||
|-----------------|-------------------|------------------|---------------------|
|
||||
| [Context A] | [Context B] | Customer-Supplier | REST API call |
|
||||
| [Context B] | [Context C] | Published Language | Domain events via message bus |
|
||||
| [Context X] | [Context Y] | Conformist | [Downstream conforms to upstream's model] |
|
||||
| [Context X] | [Context Y] | Anti-Corruption Layer | [ACL translates upstream model to local model] |
|
||||
|
||||
---
|
||||
|
||||
## 3. Proposed Service Inventory
|
||||
|
||||
| Service Name | Bounded Context | Core Responsibility | Team Owner | Tech Stack | Priority |
|
||||
|-------------|----------------|--------------------|-----------|-----------|---------|
|
||||
| [service-name] | [Context] | [One sentence: what this service owns and does] | [Team] | [Language/framework] | [P1/P2/P3] |
|
||||
| [service-name] | [Context] | [Responsibility] | [Team] | [Stack] | [Priority] |
|
||||
| [service-name] | [Context] | [Responsibility] | [Team] | [Stack] | [Priority] |
|
||||
| [service-name] | [Context] | [Responsibility] | [Team] | [Stack] | [Priority] |
|
||||
| [service-name] | [Context] | [Responsibility] | [Team] | [Stack] | [Priority] |
|
||||
|
||||
**Service count:** [N proposed services] for [M bounded contexts]. [Note if any context maps to multiple services and why — e.g., "the Orders context splits into order-intake and order-fulfillment because they have different scalability requirements."]
|
||||
|
||||
### Service Responsibility Rules (applied to every service above)
|
||||
|
||||
- Single bounded context ownership — a service does not straddle two bounded contexts
|
||||
- Owns its own data — no direct database access by other services
|
||||
- Independently deployable — no coordinated deploys required with other services
|
||||
- Has a named team owner — no shared ownership of a single service across teams
|
||||
- Exposes a defined API contract — not internal implementation
|
||||
|
||||
---
|
||||
|
||||
## 4. Inter-Service Communication Patterns
|
||||
|
||||
### Pattern Decision Matrix
|
||||
|
||||
| Communication Need | Recommended Pattern | Rationale |
|
||||
|-------------------|--------------------|-----------|
|
||||
| Query another service's current state | Synchronous REST / gRPC | Low latency required; caller needs immediate response |
|
||||
| Notify other services of a state change | Async domain event | Decouples services; multiple consumers; sender doesn't care when it's processed |
|
||||
| Long-running workflow spanning services | Async saga (choreography or orchestration) | No single service owns the full workflow; rollback needed if steps fail |
|
||||
| Read-heavy cross-service aggregation | CQRS read model / materialized view | Avoid chatty sync calls at read time; build purpose-fit read models |
|
||||
| Real-time push to clients | WebSocket gateway service | Centralizes connection management; services emit events, gateway pushes |
|
||||
|
||||
### Per-Service Communication Decisions
|
||||
|
||||
| Service | Calls (sync) | Publishes (events) | Subscribes to (events) |
|
||||
|---------|-------------|-------------------|----------------------|
|
||||
| [service-name] | [service-name (endpoint)] | [EventName] | [EventName] |
|
||||
| [service-name] | — | [EventName], [EventName] | [EventName] |
|
||||
| [service-name] | [service-name (endpoint)] | — | [EventName] |
|
||||
|
||||
### Event Catalog
|
||||
|
||||
| Event Name | Producer | Consumers | Payload (key fields) | Trigger |
|
||||
|-----------|---------|---------|---------------------|---------|
|
||||
| [OrderPlaced] | [order-service] | [inventory-service, notification-service] | `orderId, customerId, lineItems, totalAmount` | Customer submits order |
|
||||
| [InventoryReserved] | [inventory-service] | [order-service] | `orderId, reservationId, items` | Inventory successfully reserved |
|
||||
| [PaymentProcessed] | [payment-service] | [order-service, notification-service] | `orderId, paymentId, amount, status` | Payment confirmed |
|
||||
|
||||
---
|
||||
|
||||
## 5. Data Ownership Matrix
|
||||
|
||||
Each piece of data has exactly one owning service. Other services may cache or project a read model, but they do not write to the owner's database.
|
||||
|
||||
| Data Entity | Owner Service | Authoritative Store | Consumers | Access Pattern |
|
||||
|-------------|--------------|--------------------|-----------| ---------------|
|
||||
| [Order] | [order-service] | [PostgreSQL] | [fulfillment-service, reporting-service] | Event subscription + read API |
|
||||
| [Customer] | [customer-service] | [PostgreSQL] | [order-service, notification-service] | Sync API call |
|
||||
| [Product Catalog] | [catalog-service] | [PostgreSQL] | [order-service, inventory-service] | Sync API + cached local copy |
|
||||
| [Inventory Level] | [inventory-service] | [Redis + PostgreSQL] | [catalog-service (read only)] | Event subscription |
|
||||
| [Payment Record] | [payment-service] | [PostgreSQL] | [order-service] | Event subscription |
|
||||
|
||||
### Data Migration (if decomposing a monolith)
|
||||
|
||||
| Data Entity | Current Location | Target Service | Migration Approach | Data Volume | Risk |
|
||||
|-------------|-----------------|---------------|-------------------|-------------|------|
|
||||
| [Entity] | [monolith.orders table] | [order-service] | Dual-write then cut over | [X rows] | [High/Med/Low] |
|
||||
| [Entity] | [monolith.users table] | [customer-service] | Extract and sync via CDC | [X rows] | [High/Med/Low] |
|
||||
|
||||
---
|
||||
|
||||
## 6. API Contract Definitions
|
||||
|
||||
Define the surface area for each service. Full OpenAPI specs are written separately; this section establishes the contract boundaries.
|
||||
|
||||
### [service-name] API
|
||||
|
||||
**Base path:** `/api/v1/[resource]`
|
||||
**Owner team:** [Team]
|
||||
**SLA:** [p99 latency target, availability target]
|
||||
|
||||
| Endpoint | Method | Description | Auth Required | Rate Limit |
|
||||
|----------|--------|-------------|--------------|------------|
|
||||
| `/[resources]` | GET | List [resources] with pagination | Yes | [X req/min] |
|
||||
| `/[resources]/{id}` | GET | Get single [resource] by ID | Yes | [X req/min] |
|
||||
| `/[resources]` | POST | Create new [resource] | Yes | [X req/min] |
|
||||
| `/[resources]/{id}` | PUT | Update [resource] | Yes | [X req/min] |
|
||||
| `/[resources]/{id}` | DELETE | Soft-delete [resource] | Yes — elevated | [X req/min] |
|
||||
|
||||
[Repeat for each service.]
|
||||
|
||||
---
|
||||
|
||||
## 7. Strangler Fig Migration Plan (for monolith decomposition)
|
||||
|
||||
Use the strangler fig pattern: extract services incrementally, route traffic through a facade, and retire monolith modules one at a time.
|
||||
|
||||
### Migration Phases
|
||||
|
||||
```
|
||||
Phase 1: Foundation (Weeks 1–[N])
|
||||
- Deploy service infrastructure (CI/CD, observability, service mesh)
|
||||
- Extract lowest-risk, highest-value service first
|
||||
- Monolith continues to serve all traffic
|
||||
|
||||
Phase 2: First Extractions (Weeks [N]–[M])
|
||||
- Extract P1 services
|
||||
- API gateway routes selected traffic to new services
|
||||
- Monolith handles remaining traffic via facade pattern
|
||||
- Both paths write to shared DB during transition (dual-write)
|
||||
|
||||
Phase 3: Core Domain Services (Weeks [M]–[P])
|
||||
- Extract P1 core domain services
|
||||
- Data migration for extracted services
|
||||
- Remove dual-write paths for completed migrations
|
||||
|
||||
Phase 4: Monolith Retirement (Weeks [P]–[Q])
|
||||
- Extract remaining services
|
||||
- Monolith serves no production traffic
|
||||
- Decommission monolith infrastructure
|
||||
```
|
||||
|
||||
### Phase-by-Phase Roadmap
|
||||
|
||||
| Phase | Service to Extract | Migration Approach | Team | Duration | Dependencies | Success Criteria |
|
||||
|-------|------------------|--------------------|------|----------|-------------|-----------------|
|
||||
| 1 | [service-name] | [Strangler facade / Branch by abstraction / Event interception] | [Team] | [X weeks] | [Infra ready, CI/CD pipeline] | [Traffic fully on new service, zero errors for 2 weeks] |
|
||||
| 2 | [service-name] | [Approach] | [Team] | [X weeks] | [Phase 1 complete] | [Success metric] |
|
||||
| 3 | [service-name] | [Approach] | [Team] | [X weeks] | [Phase 2 complete] | [Success metric] |
|
||||
|
||||
### Rollback Plan
|
||||
|
||||
For each migration phase, define the rollback trigger and mechanism:
|
||||
- **Rollback trigger:** Error rate on new service > [X%] sustained for [Y minutes], or p99 latency > [threshold]
|
||||
- **Rollback mechanism:** API gateway feature flag reverts all traffic to monolith path in < 5 minutes
|
||||
- **Data rollback:** Dual-write maintained for [X weeks] after cutover to allow replay if needed
|
||||
|
||||
---
|
||||
|
||||
## 8. Organizational Alignment (Conway's Law)
|
||||
|
||||
Conway's Law: the architecture of a system mirrors the communication structure of the organization that builds it. Design service ownership to match team boundaries — or change the team boundaries.
|
||||
|
||||
| Service | Proposed Owner Team | Current Team Assignment | Change Required |
|
||||
|---------|--------------------|-----------------------|-----------------|
|
||||
| [service-name] | [Team A] | [Same / Different] | [No change / Transfer to Team A / New team needed] |
|
||||
| [service-name] | [Team B] | [Team A currently] | [Transfer ownership] |
|
||||
|
||||
**Misalignments identified:**
|
||||
- [Misalignment 1: e.g., "The notification service spans two teams today. Assign it entirely to Team B which already owns the messaging domain."]
|
||||
- [Misalignment 2: e.g., "The reporting service is owned by Data Eng but consumers are Product teams — establish a clear API contract and SLA."]
|
||||
|
||||
**Team topology recommendation:** [Describe the recommended team structure — stream-aligned teams, platform team, enabling team — and how it maps to the proposed services.]
|
||||
|
||||
---
|
||||
|
||||
## 9. Risk Register
|
||||
|
||||
| Risk | Likelihood | Impact | Mitigation | Owner |
|
||||
|------|-----------|--------|-----------|-------|
|
||||
| Data consistency across services during migration | High | High | Dual-write with reconciliation job; event sourcing for critical domains | [Name] |
|
||||
| Distributed transaction complexity (sagas) | Medium | High | Start with choreography; add orchestration only when choreography becomes unmanageable | [Name] |
|
||||
| Service mesh operational overhead | Medium | Medium | Start without a mesh; add after 5+ services deployed | [Name] |
|
||||
| Network latency replacing in-process calls | Medium | Medium | Cache aggressively; design read models to avoid chatty sync calls | [Name] |
|
||||
| Conway's Law friction during transition | High | Medium | Align team structure before starting extraction, not after | [Name] |
|
||||
| Over-decomposition (nanoservices) | Medium | High | Enforce minimum service size rule: a service must justify its own team/deployment overhead | [Name] |
|
||||
| Observability gaps during migration | High | High | Deploy distributed tracing before first extraction; establish correlation IDs | [Name] |
|
||||
| [Context-specific risk] | [Level] | [Level] | [Mitigation] | [Owner] |
|
||||
|
||||
---
|
||||
|
||||
*Questions about this design: [Slack channel or contact]*
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Bounded context map is an ASCII diagram with labeled relationships — not a prose description of the contexts
|
||||
- [ ] Every service in the inventory table has a named team owner and a clear single-sentence responsibility statement
|
||||
- [ ] Data ownership matrix assigns every key entity to exactly one owning service — no shared ownership
|
||||
- [ ] Communication pattern decisions explain WHY sync vs. async was chosen for each interaction type
|
||||
- [ ] If decomposing a monolith, the strangler fig migration plan has phases with durations, dependencies, and success criteria
|
||||
- [ ] Risk register addresses at minimum: data consistency, distributed transactions, and Conway's Law alignment
|
||||
- [ ] Organizational alignment section maps services to teams and identifies misalignments that need to be resolved
|
||||
@@ -0,0 +1,436 @@
|
||||
---
|
||||
name: monitoring-setup-guide
|
||||
description: "Write a monitoring setup guide for a service — defining what to measure, how to alert on it, and how to build the observability stack covering the four golden signals, business metrics, log strategy, distributed tracing, alerting rules, dashboard layout, and observability debt. Use when asked to set up monitoring for a service, define alerting strategy, write an observability plan, create a dashboard specification, or document logging standards for a team. Produces a metric definitions table, alert rules specification, dashboard layout wireframe, log schema, tracing setup checklist, and monitoring gap analysis."
|
||||
---
|
||||
|
||||
# Monitoring Setup Guide Skill
|
||||
|
||||
Produce a complete monitoring setup guide for a service — defining exactly what to measure, how to structure logs, how to configure alerts with actionable thresholds, and how to build dashboards that answer real operational questions. A good monitoring guide eliminates "we don't know what's happening in production" as a root cause category, and gives on-call engineers a single source of truth for what healthy looks like.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask for these if not already provided:
|
||||
- **Service name and description** — what the service does and its role in the system
|
||||
- **Tech stack** — language, framework, and infrastructure (e.g. Go/gRPC on Kubernetes, Python/FastAPI on ECS)
|
||||
- **Current monitoring tooling** — Datadog, Prometheus + Grafana, CloudWatch, New Relic, Honeycomb, or none yet
|
||||
- **Key user journeys** — the 2–4 most important things a user or consumer does with the service (these drive what to alert on)
|
||||
- **Existing alerts** — paste any existing alert configurations or describe what's currently monitored
|
||||
|
||||
## Output Format
|
||||
|
||||
---
|
||||
|
||||
# Monitoring Setup Guide: [Service Name]
|
||||
|
||||
**Team:** [Team name] | **Tech lead:** [Name]
|
||||
**Stack:** [Language/Framework] on [Infrastructure]
|
||||
**Monitoring platform:** [Datadog / Prometheus+Grafana / CloudWatch / etc.]
|
||||
**Date:** [Date] | **Review cycle:** Quarterly
|
||||
|
||||
---
|
||||
|
||||
## 1. Monitoring Philosophy
|
||||
|
||||
Good monitoring answers three questions:
|
||||
1. **Is the service healthy right now?** (alerting)
|
||||
2. **Was it healthy in the past, and is it trending worse?** (dashboards + SLO tracking)
|
||||
3. **Why did something fail?** (logs + traces)
|
||||
|
||||
This guide defines the answers for [Service Name]. Every alert must be actionable — if an on-call engineer cannot take a specific action in response to the alert, the alert should not exist.
|
||||
|
||||
**Key user journeys monitored:**
|
||||
- Journey 1: [e.g. "User submits a payment — POST /charges, receives confirmation"]
|
||||
- Journey 2: [e.g. "User views transaction history — GET /transactions"]
|
||||
- Journey 3: [e.g. "Subscription renewal job runs — background worker processes billing events"]
|
||||
|
||||
---
|
||||
|
||||
## 2. The Four Golden Signals
|
||||
|
||||
Apply the four golden signals specifically to [Service Name]:
|
||||
|
||||
### Latency
|
||||
|
||||
Latency measures how long requests take to complete. Track it separately for successful and failed requests — slow failures hide behind fast errors if you only measure aggregate latency.
|
||||
|
||||
| Metric | Description | Source | Dimensions |
|
||||
|---|---|---|---|
|
||||
| `[service].request.duration_ms` | End-to-end request latency | Application instrumentation | `endpoint`, `method`, `status_code` |
|
||||
| `[service].db.query_duration_ms` | Database query latency | ORM / query instrumentation | `query_name`, `table` |
|
||||
| `[service].external.request_duration_ms` | Outbound call latency to dependencies | HTTP client instrumentation | `target_service`, `endpoint` |
|
||||
| `[service].queue.processing_duration_ms` | Time to process one message (if applicable) | Consumer instrumentation | `queue_name`, `message_type` |
|
||||
|
||||
**Latency SLO targets:**
|
||||
|
||||
| Endpoint / operation | p50 target | p95 target | p99 target |
|
||||
|---|---|---|---|
|
||||
| `GET /api/v1/[resource]` | < [50] ms | < [200] ms | < [500] ms |
|
||||
| `POST /api/v1/[resource]` | < [100] ms | < [400] ms | < [1000] ms |
|
||||
| `GET /health` | < [10] ms | < [20] ms | < [50] ms |
|
||||
| [Background job name] | < [5] sec | < [15] sec | < [60] sec |
|
||||
|
||||
### Traffic
|
||||
|
||||
Traffic measures demand on the system. Use it to detect unexpected spikes, traffic drops (which can indicate upstream failures), and to capacity-plan.
|
||||
|
||||
| Metric | Description | Source |
|
||||
|---|---|---|
|
||||
| `[service].request.count` | Requests per second | Application / load balancer |
|
||||
| `[service].request.count_by_endpoint` | RPS broken down by endpoint | Application |
|
||||
| `[service].queue.messages_consumed_per_second` | Consumer throughput | Queue consumer |
|
||||
| `[service].queue.depth` | Messages waiting in queue | Queue metrics |
|
||||
|
||||
**Traffic baselines (update after observing production for 2+ weeks):**
|
||||
|
||||
| Time period | Expected RPS | Low-traffic floor | Spike ceiling |
|
||||
|---|---|---|---|
|
||||
| Peak (weekday business hours) | [N] RPS | [N × 0.5] RPS | [N × 5] RPS |
|
||||
| Off-peak (nights/weekends) | [N × 0.2] RPS | [N × 0.05] RPS | [N] RPS |
|
||||
|
||||
### Errors
|
||||
|
||||
Errors measure the fraction of requests that fail. Distinguish between client errors (4xx — caller is doing something wrong) and server errors (5xx — the service is broken).
|
||||
|
||||
| Metric | Description | Alert on? |
|
||||
|---|---|---|
|
||||
| `[service].request.error_rate` | 5xx errors / total requests | Yes — see alert rules |
|
||||
| `[service].request.client_error_rate` | 4xx errors / total requests | Threshold alert — sudden spike may indicate API misuse |
|
||||
| `[service].dependency.error_rate` | Errors calling downstream dependencies | Yes — upstream health signal |
|
||||
| `[service].queue.dlq_depth` | Messages in dead-letter queue | Yes — indicates processing failures |
|
||||
|
||||
### Saturation
|
||||
|
||||
Saturation measures how "full" the service is — how close to maximum capacity are the constrained resources.
|
||||
|
||||
| Resource | Metric | Alert threshold | Source |
|
||||
|---|---|---|---|
|
||||
| CPU | `[service].cpu.utilisation_pct` | >80% sustained 5 min | Container / VM metrics |
|
||||
| Memory | `[service].memory.utilisation_pct` | >85% sustained 5 min | Container / VM metrics |
|
||||
| DB connections | `[service].db.connection_pool.utilisation_pct` | >75% | Application / DB metrics |
|
||||
| Thread pool / goroutines | `[service].runtime.goroutine_count` / `thread_count` | >N (establish baseline) | Runtime metrics |
|
||||
| Disk (if applicable) | `[service].disk.utilisation_pct` | >75% | Infrastructure |
|
||||
| Queue depth (if applicable) | `[service].queue.depth` | >[backlog threshold] | Queue metrics |
|
||||
|
||||
---
|
||||
|
||||
## 3. Business Metrics
|
||||
|
||||
Beyond the golden signals, track metrics that measure whether the service is delivering business value. These matter for SLO reporting and product dashboards.
|
||||
|
||||
| Metric | Description | Source | Alert? |
|
||||
|---|---|---|---|
|
||||
| `[service].[primary_action].success_rate` | [e.g. "Payment success rate"] | Application | Yes — if drops >5% vs 1h average |
|
||||
| `[service].[primary_action].count` | [e.g. "Payments processed per minute"] | Application | Yes — sudden drop (traffic anomaly) |
|
||||
| `[service].[resource].created_per_hour` | [e.g. "New accounts created"] | Application / DB | No — informational |
|
||||
| `[service].cache.hit_rate` | Fraction of requests served from cache | Cache instrumentation | Yes — if drops below [60]% |
|
||||
| `[service].job.[name].success_rate` | [Background job success rate] | Job framework | Yes — if drops below [99]% |
|
||||
|
||||
---
|
||||
|
||||
## 4. Log Strategy
|
||||
|
||||
### Structured Logging Schema
|
||||
|
||||
All logs must be structured JSON. Do not emit unstructured text logs in production. Every log line must include the mandatory fields.
|
||||
|
||||
**Mandatory fields (every log line):**
|
||||
|
||||
```json
|
||||
{
|
||||
"timestamp": "2024-01-15T10:23:45.123Z",
|
||||
"level": "info",
|
||||
"service": "[service-name]",
|
||||
"version": "[git-sha-short]",
|
||||
"trace_id": "[uuid-from-request-context]",
|
||||
"span_id": "[span-uuid]",
|
||||
"request_id": "[uuid-per-request]",
|
||||
"message": "[human readable description]"
|
||||
}
|
||||
```
|
||||
|
||||
**Request log (emit for every HTTP request):**
|
||||
|
||||
```json
|
||||
{
|
||||
"timestamp": "...",
|
||||
"level": "info",
|
||||
"service": "[service-name]",
|
||||
"event": "http_request",
|
||||
"method": "POST",
|
||||
"path": "/api/v1/[resource]",
|
||||
"status_code": 201,
|
||||
"duration_ms": 45,
|
||||
"user_id": "[uuid — DO NOT log PII directly]",
|
||||
"request_id": "[uuid]",
|
||||
"trace_id": "[uuid]"
|
||||
}
|
||||
```
|
||||
|
||||
**Error log (emit for every error with context):**
|
||||
|
||||
```json
|
||||
{
|
||||
"timestamp": "...",
|
||||
"level": "error",
|
||||
"service": "[service-name]",
|
||||
"event": "error",
|
||||
"error_code": "[application-error-code]",
|
||||
"error_message": "[description — no sensitive data]",
|
||||
"stack_trace": "[stack trace]",
|
||||
"request_id": "[uuid]",
|
||||
"trace_id": "[uuid]",
|
||||
"context": {
|
||||
"[key]": "[relevant context without PII]"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Log Levels — When to Use Each
|
||||
|
||||
| Level | Use when | Example |
|
||||
|---|---|---|
|
||||
| `error` | Something failed that requires attention — this should page on-call eventually | Database query failed, external API returned 5xx, required config missing |
|
||||
| `warn` | Something unexpected happened but service is still functioning | Retry succeeded after failure, cache miss on expected hit, rate limit approaching |
|
||||
| `info` | Significant business events and request lifecycle | Request received, payment processed, user authenticated, job started/completed |
|
||||
| `debug` | Detailed diagnostic information — off in production by default | Query parameters, intermediate computation results, cache key lookups |
|
||||
|
||||
### What NOT to Log
|
||||
|
||||
**Never log:**
|
||||
- Passwords, tokens, API keys, or secrets (even hashed)
|
||||
- Full credit card numbers or PAN data
|
||||
- Social security numbers or government IDs
|
||||
- Full names + dates of birth + contact info in the same log line (PII aggregation)
|
||||
- Request/response bodies in full (use field-level extraction instead)
|
||||
- Health check requests (too noisy — exclude `GET /health` from access logs)
|
||||
|
||||
---
|
||||
|
||||
## 5. Distributed Tracing Setup
|
||||
|
||||
Distributed tracing is mandatory for any service that calls other services. It enables root-cause analysis across service boundaries.
|
||||
|
||||
### Instrumentation Checklist
|
||||
|
||||
```
|
||||
[ ] Tracing library installed:
|
||||
- Go: go.opentelemetry.io/otel
|
||||
- Python: opentelemetry-sdk, opentelemetry-instrumentation
|
||||
- Node: @opentelemetry/sdk-node
|
||||
- Java: opentelemetry-java-instrumentation
|
||||
|
||||
[ ] Tracer initialized at service startup with service name and version
|
||||
|
||||
[ ] Trace context propagated via W3C Trace Context headers:
|
||||
traceparent: 00-[trace-id]-[span-id]-01
|
||||
tracestate: [optional vendor-specific]
|
||||
|
||||
[ ] Automatic instrumentation enabled for:
|
||||
[ ] Inbound HTTP/gRPC requests (creates root span)
|
||||
[ ] Outbound HTTP/gRPC calls (creates child spans)
|
||||
[ ] Database queries (creates child spans with sanitized query)
|
||||
[ ] Cache operations (Redis, Memcached)
|
||||
[ ] Message queue produce/consume
|
||||
|
||||
[ ] Custom spans added for:
|
||||
[ ] Key business operations ([e.g. payment processing, user lookup])
|
||||
[ ] Background jobs (each job execution = root span)
|
||||
[ ] Third-party API calls with custom attributes
|
||||
|
||||
[ ] Span attributes to capture on all spans:
|
||||
- user.id (if authenticated — no PII)
|
||||
- deployment.environment (production/staging)
|
||||
- service.version (git SHA)
|
||||
- [service-specific key attributes]
|
||||
|
||||
[ ] Trace exporter configured to: [Datadog / Jaeger / Tempo / OTLP endpoint]
|
||||
|
||||
[ ] Sampling rate configured:
|
||||
- Production: [1–10]% of requests (adjust based on volume and cost)
|
||||
- Always sample: errors, slow requests (>p99 threshold), and 100% of [critical endpoint]
|
||||
```
|
||||
|
||||
### Trace Instrumentation Examples
|
||||
|
||||
```python
|
||||
# Python — OpenTelemetry example
|
||||
from opentelemetry import trace
|
||||
|
||||
tracer = trace.get_tracer("[service-name]")
|
||||
|
||||
def process_payment(payment_data):
|
||||
with tracer.start_as_current_span("process_payment") as span:
|
||||
span.set_attribute("payment.amount_cents", payment_data["amount"])
|
||||
span.set_attribute("payment.currency", payment_data["currency"])
|
||||
# Never: span.set_attribute("payment.card_number", ...)
|
||||
try:
|
||||
result = _do_process(payment_data)
|
||||
span.set_status(trace.StatusCode.OK)
|
||||
return result
|
||||
except PaymentError as e:
|
||||
span.set_status(trace.StatusCode.ERROR, str(e))
|
||||
span.record_exception(e)
|
||||
raise
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Alert Rules Specification
|
||||
|
||||
Every alert must have: a name, a condition, a threshold, a severity, and a clear on-call action. Alerts without a clear action should not exist.
|
||||
|
||||
### Alert Definitions
|
||||
|
||||
| Alert name | Condition | Threshold | Severity | On-call action |
|
||||
|---|---|---|---|---|
|
||||
| `[Service]HighErrorRate` | 5xx error rate, 5-min rolling window | >1% for 2 consecutive windows | P1 | Check recent deploys; inspect error logs; see runbook [link] |
|
||||
| `[Service]CriticalErrorRate` | 5xx error rate, 2-min rolling window | >5% | P1 — immediate | Same as above — page immediately, do not wait |
|
||||
| `[Service]HighP99Latency` | p99 latency on key endpoints | >2× SLO target for 3 min | P2 | Check DB latency, cache hit rate, and upstream dependencies |
|
||||
| `[Service]LatencySLOBreach` | p99 latency | >SLO target for 5 consecutive minutes | P1 | SLO burn — page on-call, escalate if not resolved in 20 min |
|
||||
| `[Service]HighCPU` | CPU utilisation | >80% sustained for 5 min | P2 | Check for traffic spike; scale up if needed; check for runaway processes |
|
||||
| `[Service]HighMemory` | Memory utilisation | >85% sustained for 5 min | P2 | Check for memory leak (especially after deploys); restart pod if OOM imminent |
|
||||
| `[Service]DBConnectionPoolHigh` | DB connection pool utilisation | >75% | P2 | Check for long-running queries; consider scaling service or increasing pool size |
|
||||
| `[Service]DLQDepthHigh` | Dead-letter queue depth | >10 messages | P2 | Inspect DLQ messages for error pattern; fix bug and replay if safe |
|
||||
| `[Service]TrafficDropAnomaly` | RPS, compared to same hour yesterday | >50% drop sustained 5 min | P1 | Upstream may be down; check caller health; check load balancer |
|
||||
| `[Service]PrimaryActionSuccessRateDrop` | [Business metric success rate] | <[95]% over 10 min | P1 | [Service-specific action — e.g. "Check payment provider status"] |
|
||||
| `[Service]DownstreamDependencyErrors` | Error rate calling [dependency] | >5% over 5 min | P2 | Check [dependency] status page; enable fallback if available |
|
||||
|
||||
### Alert Configuration Examples
|
||||
|
||||
```yaml
|
||||
# Prometheus / Grafana alerting rules (adapt for your platform)
|
||||
groups:
|
||||
- name: [service-name]-alerts
|
||||
rules:
|
||||
|
||||
- alert: [Service]HighErrorRate
|
||||
expr: |
|
||||
(
|
||||
sum(rate([service]_http_requests_total{status=~"5.."}[5m]))
|
||||
/
|
||||
sum(rate([service]_http_requests_total[5m]))
|
||||
) > 0.01
|
||||
for: 2m
|
||||
labels:
|
||||
severity: critical
|
||||
team: [team-name]
|
||||
annotations:
|
||||
summary: "High error rate on [Service Name]"
|
||||
description: "Error rate is {{ $value | humanizePercentage }} (threshold: 1%)"
|
||||
runbook_url: "[runbook link]"
|
||||
|
||||
- alert: [Service]HighP99Latency
|
||||
expr: |
|
||||
histogram_quantile(0.99,
|
||||
sum(rate([service]_http_request_duration_seconds_bucket[5m])) by (le, endpoint)
|
||||
) > [0.5]
|
||||
for: 3m
|
||||
labels:
|
||||
severity: warning
|
||||
team: [team-name]
|
||||
annotations:
|
||||
summary: "p99 latency elevated on [Service Name]"
|
||||
description: "p99 latency on {{ $labels.endpoint }} is {{ $value | humanizeDuration }}"
|
||||
runbook_url: "[runbook link]"
|
||||
```
|
||||
|
||||
```python
|
||||
# Datadog monitor configuration (Python SDK or Terraform)
|
||||
import datadog
|
||||
|
||||
datadog.initialize(api_key="[key]", app_key="[key]")
|
||||
|
||||
datadog.api.Monitor.create(
|
||||
type="metric alert",
|
||||
query=f"sum(last_5m):sum:{{service}}.http.errors{{service:[service-name]}} / sum:{{service}}.http.requests{{service:[service-name]}} > 0.01",
|
||||
name="[Service] High Error Rate",
|
||||
message="Error rate exceeded 1%. @pagerduty-[service-oncall]\n\nRunbook: [link]",
|
||||
tags=["service:[service-name]", "team:[team-name]"],
|
||||
options={
|
||||
"thresholds": {"critical": 0.01, "warning": 0.005},
|
||||
"notify_no_data": False,
|
||||
"evaluation_delay": 60,
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Dashboard Layout Specification
|
||||
|
||||
The primary service dashboard must answer "is the service healthy right now?" at a glance. Use this layout:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────┐
|
||||
│ [SERVICE NAME] — Service Health Dashboard [Time range ▼] │
|
||||
├───────────────┬───────────────┬───────────────┬─────────────────────┤
|
||||
│ Error rate │ p99 Latency │ RPS (current)│ SLO budget remaining│
|
||||
│ [BIG NUMBER] │ [BIG NUMBER] │ [BIG NUMBER] │ [BIG NUMBER / days] │
|
||||
│ vs SLO: 0.1% │ vs SLO: 500ms│ vs avg: [N] │ [Error budget gauge]│
|
||||
├───────────────┴───────────────┴───────────────┴─────────────────────┤
|
||||
│ Error rate over time (24h) │
|
||||
│ [Time series: 5xx rate line, SLO threshold line] │
|
||||
├─────────────────────────────────┬───────────────────────────────────┤
|
||||
│ Latency percentiles over time │ Request throughput over time │
|
||||
│ [Lines: p50, p95, p99, p999] │ [Bars: RPS by endpoint] │
|
||||
│ [SLO threshold horizontal line]│ │
|
||||
├─────────────────────────────────┴───────────────────────────────────┤
|
||||
│ Latency heatmap (all requests — shows distribution shape) │
|
||||
├─────────────────────────────────┬───────────────────────────────────┤
|
||||
│ CPU utilisation over time │ Memory utilisation over time │
|
||||
│ [All instances/pods — lines] │ [All instances/pods — lines] │
|
||||
│ [Alert threshold: 80%] │ [Alert threshold: 85%] │
|
||||
├─────────────────────────────────┴───────────────────────────────────┤
|
||||
│ DB: connection pool utilisation│ DB: query latency (p99 per query)│
|
||||
├─────────────────────────────────┴───────────────────────────────────┤
|
||||
│ [Business metric 1 over time] │ [Business metric 2 over time] │
|
||||
│ e.g. Payment success rate │ e.g. Orders created/min │
|
||||
└─────────────────────────────────┴───────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Second dashboard — Dependency Health:**
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────┐
|
||||
│ [SERVICE NAME] — Dependency Health │
|
||||
├─────────────────────────────────────────────────────────────────────┤
|
||||
│ For each dependency: error rate | latency | current status │
|
||||
│ [Database] [N]% errors | [N]ms p99 | ● Healthy / ⚠ Degraded │
|
||||
│ [Redis] [N]% errors | [N]ms p99 | ● Healthy │
|
||||
│ [External API][N]% errors | [N]ms p99 | ● Healthy │
|
||||
├─────────────────────────────────────────────────────────────────────┤
|
||||
│ Outbound call latency over time (one line per dependency) │
|
||||
├─────────────────────────────────────────────────────────────────────┤
|
||||
│ Circuit breaker / fallback state (if implemented) │
|
||||
└─────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Observability Debt Analysis
|
||||
|
||||
Honest assessment of what is missing today and what the priority to add it is:
|
||||
|
||||
| Gap | Impact | Priority | Effort | Owner | Target date |
|
||||
|---|---|---|---|---|---|
|
||||
| [e.g. No distributed tracing — can't see cross-service latency] | High — blind to dependency issues | P1 | [2 days] | [Name] | [Date] |
|
||||
| [e.g. No business metric alerts — only infra alerts] | High — silent business failures | P1 | [1 day] | [Name] | [Date] |
|
||||
| [e.g. Logs are unstructured text — not searchable] | Medium — slow incident investigation | P2 | [3 days] | [Name] | [Date] |
|
||||
| [e.g. No dead-letter queue monitoring] | Medium — failed messages go unnoticed | P2 | [4 hours] | [Name] | [Date] |
|
||||
| [e.g. Alert thresholds not calibrated to production baseline] | Medium — alert fatigue or missed alerts | P2 | [1 day] | [Name] | [Date] |
|
||||
| [e.g. No latency heatmap — outliers invisible in averages] | Low — harder to spot tail latency issues | P3 | [2 hours] | [Name] | [Date] |
|
||||
|
||||
**Total observability debt: [N] items | Estimated effort: [N days]**
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Every alert has a named on-call action — no alert says "investigate" without specifying what to investigate first
|
||||
- [ ] Alert thresholds are calibrated against production baselines, not set to default values from a template
|
||||
- [ ] Structured logging is implemented — no unstructured text log lines in production
|
||||
- [ ] PII is explicitly excluded from logs — a named engineer has verified this
|
||||
- [ ] Distributed tracing is propagating trace IDs across all service boundaries (verify with a test request)
|
||||
- [ ] The primary dashboard answers "is the service healthy?" in under 10 seconds — no hunting for the right panel
|
||||
- [ ] Business metrics are tracked alongside infrastructure metrics — not just four golden signals
|
||||
- [ ] Observability debt items have owners and dates — not just "would be nice to have"
|
||||
@@ -0,0 +1,364 @@
|
||||
---
|
||||
name: oncall-runbook
|
||||
description: "Write an on-call runbook for a service — covering alert definitions, escalation paths, common incident responses, and on-call handoff procedures. Use when asked to write an on-call guide, create alert runbooks, document escalation procedures, or prepare an on-call handoff document. Produces a structured on-call runbook with per-alert response procedures, escalation matrix, diagnostic commands, and handoff template."
|
||||
---
|
||||
|
||||
# On-Call Runbook Skill
|
||||
|
||||
Produce a complete on-call runbook for a service — giving the on-call engineer everything they need to respond confidently to alerts at 3am, without having to ask anyone for help.
|
||||
|
||||
A good on-call runbook reduces mean time to resolution (MTTR) by eliminating the "what do I do first?" problem. It is written for the on-call engineer who has just been paged and needs to act, not for someone calmly reading documentation.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask for these if not already provided:
|
||||
- **Service name** and what it does
|
||||
- **Team** and tech lead name
|
||||
- **Alert list** — names of alerts that currently page on-call
|
||||
- **Monitoring setup** — Datadog / Grafana / CloudWatch / PagerDuty / etc.
|
||||
- **Common failure modes** — what breaks most often, and what fixes it
|
||||
- **Escalation contacts** — who to call when on-call can't resolve it
|
||||
- **Deployment setup** — can on-call roll back? How?
|
||||
- **Service dependencies** — what does this service depend on, and what depends on it?
|
||||
|
||||
## Output Format
|
||||
|
||||
---
|
||||
|
||||
# On-Call Runbook: [Service Name]
|
||||
|
||||
**Team:** [Team name] | **Tech lead:** [Name]
|
||||
**PagerDuty service:** [Link] | **Escalation policy:** [Policy name]
|
||||
**Last updated:** [Date] | **Next review:** [Date + 90 days]
|
||||
|
||||
> **First time on-call for this service?** Read the [developer onboarding doc] first — it covers the architecture and how things work. This runbook assumes you understand the service.
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
**Dashboard:** [Link — the first thing to open when paged]
|
||||
**Logs:** [Link — where to find logs]
|
||||
**Runbook index:** Jump to the alert that paged you → [Alert list below]
|
||||
**Can't resolve in 30 min?** Escalate to: [Name] via [Slack / PagerDuty]
|
||||
|
||||
**Rollback command (memorise this):**
|
||||
```bash
|
||||
[rollback command — e.g. kubectl rollout undo deployment/[service-name]]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Escalation Matrix
|
||||
|
||||
| Situation | Escalate to | How | After how long |
|
||||
|---|---|---|---|
|
||||
| Can't diagnose the alert | [Tech lead name] | Slack DM / Phone | 30 minutes |
|
||||
| Alert requires infra change | [Platform team] | `#platform` Slack | Immediately |
|
||||
| Customer-facing impact | [CSM / Support lead] | `#incidents` Slack | Immediately (P1) |
|
||||
| Database issue | [DBA or data team] | Slack / PagerDuty | Immediately |
|
||||
| [Specific dependency] down | [[Dependency] on-call] | PagerDuty / Slack | Immediately |
|
||||
| Extended outage (>1 hour) | [Engineering manager] | Phone | 1 hour |
|
||||
|
||||
**Contacts:**
|
||||
|
||||
| Name | Role | Slack | Phone |
|
||||
|---|---|---|---|
|
||||
| [Name] | Tech lead | @[handle] | [Number] |
|
||||
| [Name] | Engineering manager | @[handle] | [Number] |
|
||||
| [Name] | Platform / infra | @[handle] | [Number] |
|
||||
| [Platform team] | Infra on-call | `#platform` | PagerDuty |
|
||||
|
||||
---
|
||||
|
||||
## Service Architecture (Quick View)
|
||||
|
||||
```
|
||||
[Upstream callers]
|
||||
│
|
||||
▼
|
||||
[This Service]
|
||||
│
|
||||
├──→ [Primary Database]
|
||||
├──→ [Cache — e.g. Redis]
|
||||
└──→ [Downstream Service / Queue]
|
||||
```
|
||||
|
||||
**If this service is down, these are affected:** [List downstream consumers]
|
||||
**If these are down, this service is affected:** [List upstream dependencies]
|
||||
|
||||
---
|
||||
|
||||
## Alert Runbooks
|
||||
|
||||
### ALERT: [Alert Name 1 — e.g. HighErrorRate]
|
||||
|
||||
**What it means:** [Plain English — e.g. "More than 5% of API requests are returning 5xx errors in the last 5 minutes"]
|
||||
**Severity:** P1 / P2 / P3
|
||||
**SLO impact:** Yes / No — [If yes: this alert means the error budget is burning at [X]× rate]
|
||||
|
||||
**Step 1 — Acknowledge and assess**
|
||||
```bash
|
||||
# Check current error rate
|
||||
[query or dashboard link]
|
||||
|
||||
# Check which endpoints are erroring
|
||||
[query or command]
|
||||
```
|
||||
|
||||
**Step 2 — Check recent changes**
|
||||
```bash
|
||||
# Any deploys in the last hour?
|
||||
[command or link to deployment log]
|
||||
|
||||
# Recent config changes?
|
||||
[where to check]
|
||||
```
|
||||
|
||||
**Step 3 — Check dependencies**
|
||||
```bash
|
||||
# Is the database healthy?
|
||||
[health check command or link]
|
||||
|
||||
# Is [downstream service] healthy?
|
||||
[health check command or link]
|
||||
```
|
||||
|
||||
**Step 4 — Diagnose**
|
||||
|
||||
| If you see | It means | Do this |
|
||||
|---|---|---|
|
||||
| [Error pattern 1] | [Cause] | [Action] |
|
||||
| [Error pattern 2] | [Cause] | [Action] |
|
||||
| [Error pattern 3] | [Cause] | [Action] |
|
||||
| No clear pattern | Unknown cause | Escalate to [name] |
|
||||
|
||||
**Step 5 — Fix or mitigate**
|
||||
```bash
|
||||
# If caused by bad deploy — roll back:
|
||||
[rollback command]
|
||||
|
||||
# If caused by [specific issue]:
|
||||
[fix command]
|
||||
|
||||
# If caused by upstream dependency:
|
||||
[mitigation — e.g. enable circuit breaker, reduce traffic, etc.]
|
||||
```
|
||||
|
||||
**After resolving:**
|
||||
- [ ] Confirm error rate has returned to baseline
|
||||
- [ ] Check no downstream services were affected
|
||||
- [ ] If P1: open a post-incident review — see [incident-postmortem skill]
|
||||
- [ ] Update `#incidents` with resolution summary
|
||||
|
||||
---
|
||||
|
||||
### ALERT: [Alert Name 2 — e.g. HighLatency]
|
||||
|
||||
**What it means:** [e.g. "P99 response time has exceeded 1s for more than 3 consecutive minutes"]
|
||||
**Severity:** P1 / P2 / P3
|
||||
**SLO impact:** Yes — latency SLO breach
|
||||
|
||||
**Step 1 — Assess scope**
|
||||
```bash
|
||||
# Check which endpoints are slow
|
||||
[query or dashboard — broken down by endpoint]
|
||||
|
||||
# Check if latency is across all regions or localised
|
||||
[query or command]
|
||||
```
|
||||
|
||||
**Step 2 — Common causes and fixes**
|
||||
|
||||
| Cause | Signal | Fix |
|
||||
|---|---|---|
|
||||
| Database slow queries | DB latency spike on dashboard | [Check slow query log: `command`] |
|
||||
| Cache miss storm | Cache hit rate drops on dashboard | [command or action] |
|
||||
| Memory pressure / GC | High memory on service dashboard | [command or action — e.g. restart, scale up] |
|
||||
| Upstream service slow | Trace shows time in external call | Escalate to [service] on-call |
|
||||
| Traffic spike | Request rate spike on dashboard | [Scale up: `command`] |
|
||||
|
||||
**Step 3 — Escalate if unresolved in 20 minutes**
|
||||
Page [Tech lead] via PagerDuty / Slack.
|
||||
|
||||
---
|
||||
|
||||
### ALERT: [Alert Name 3 — e.g. DatabaseConnectionPoolExhausted]
|
||||
|
||||
**What it means:** [e.g. "The service has used all available database connections — new requests will fail"]
|
||||
**Severity:** P1
|
||||
**SLO impact:** Yes — will cause errors immediately
|
||||
|
||||
**Immediate mitigation:**
|
||||
```bash
|
||||
# Restart the service to flush stale connections
|
||||
[restart command]
|
||||
|
||||
# Check current connection count
|
||||
[DB connection query]
|
||||
```
|
||||
|
||||
**Diagnose root cause after stabilising:**
|
||||
```bash
|
||||
# Check for long-running queries holding connections
|
||||
[query]
|
||||
|
||||
# Check if a recent deploy changed connection pool config
|
||||
[where to check]
|
||||
```
|
||||
|
||||
**Resolution:** [e.g. "Increase pool size in config / kill long-running queries / scale the service"]
|
||||
|
||||
---
|
||||
|
||||
### ALERT: [Alert Name 4 — e.g. QueueBacklogHigh / ConsumerLag]
|
||||
|
||||
**What it means:** [e.g. "The message queue backlog exceeds 10,000 messages — consumers are not keeping up"]
|
||||
**Severity:** P2
|
||||
**SLO impact:** Depends — if queue backs up, downstream systems will receive delayed data
|
||||
|
||||
**Step 1 — Check consumer health**
|
||||
```bash
|
||||
# Are consumers running?
|
||||
[command]
|
||||
|
||||
# Consumer error rate?
|
||||
[dashboard or query]
|
||||
```
|
||||
|
||||
**Step 2 — Check message contents**
|
||||
```bash
|
||||
# Are there poison messages causing retries?
|
||||
[command to inspect dead-letter queue or failed messages]
|
||||
```
|
||||
|
||||
**Step 3 — Options**
|
||||
|
||||
| If | Then |
|
||||
|---|---|
|
||||
| Consumers are down | Restart consumers: `[command]` |
|
||||
| Poison message in queue | Move to DLQ: `[command]` |
|
||||
| Consumers healthy but slow | Scale consumers: `[command]` |
|
||||
| Upstream producing too fast | Escalate to [upstream service] owner |
|
||||
|
||||
---
|
||||
|
||||
### ALERT: [Add additional alerts following the same pattern]
|
||||
|
||||
---
|
||||
|
||||
## Diagnostic Cheat Sheet
|
||||
|
||||
Common commands for quick diagnosis. Paste and run without modification.
|
||||
|
||||
```bash
|
||||
# Service health
|
||||
[health check command]
|
||||
|
||||
# Recent logs (last 100 lines)
|
||||
[log command]
|
||||
|
||||
# Error logs only
|
||||
[error log filter command]
|
||||
|
||||
# Current pod / instance status
|
||||
[kubectl get pods / aws ecs describe-tasks / etc.]
|
||||
|
||||
# Restart the service
|
||||
[restart command]
|
||||
|
||||
# Roll back to previous version
|
||||
[rollback command]
|
||||
|
||||
# Database connection count
|
||||
[DB query]
|
||||
|
||||
# Cache hit rate
|
||||
[cache stats command]
|
||||
|
||||
# Current request rate
|
||||
[metrics query]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Useful Dashboard Links
|
||||
|
||||
| Dashboard | URL | Use it to |
|
||||
|---|---|---|
|
||||
| Service overview | [Link] | First stop — error rate, latency, request rate |
|
||||
| Database | [Link] | Connection count, slow queries, replication lag |
|
||||
| Infrastructure | [Link] | CPU, memory, disk |
|
||||
| Queue / consumers | [Link] | Backlog depth, consumer throughput |
|
||||
| Upstream dependencies | [Link] | Dependency health at a glance |
|
||||
|
||||
---
|
||||
|
||||
## Incident Communication
|
||||
|
||||
When you declare an incident:
|
||||
|
||||
**Post to `#incidents` immediately:**
|
||||
```
|
||||
🔴 INCIDENT — [Service Name]
|
||||
Status: Investigating
|
||||
Impact: [Who is affected and how]
|
||||
Paged: [Your name]
|
||||
Next update: [Time — max 30 min from now]
|
||||
```
|
||||
|
||||
**Update every 30 minutes while active:**
|
||||
```
|
||||
🔴 UPDATE — [Service Name] — [Time]
|
||||
Status: [Investigating / Identified / Mitigating / Resolved]
|
||||
Latest: [One sentence on what you found or did]
|
||||
Next update: [Time]
|
||||
```
|
||||
|
||||
**On resolution:**
|
||||
```
|
||||
✅ RESOLVED — [Service Name] — [Time]
|
||||
Duration: [X minutes]
|
||||
Impact: [Summary of who was affected]
|
||||
Cause: [One sentence]
|
||||
Follow-up: [PIR required? Yes/No — link when created]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## On-Call Handoff
|
||||
|
||||
Use this template at the end of every on-call shift:
|
||||
|
||||
```
|
||||
--- ON-CALL HANDOFF: [Service Name] ---
|
||||
Date: [Date]
|
||||
Outgoing: [Your name]
|
||||
Incoming: [Next on-call name]
|
||||
|
||||
INCIDENTS THIS SHIFT:
|
||||
- [Incident summary — date, duration, cause, resolution, follow-up required]
|
||||
|
||||
OPEN ISSUES TO WATCH:
|
||||
- [Anything not fully resolved / trending in the wrong direction]
|
||||
|
||||
CHANGES SINCE LAST HANDOFF:
|
||||
- [Deploys, config changes, infra changes that affect on-call awareness]
|
||||
|
||||
RUNBOOK GAPS FOUND:
|
||||
- [Anything you had to figure out that isn't documented — please add it]
|
||||
|
||||
ANYTHING ELSE:
|
||||
- [Notes for incoming on-call]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Every alert that pages on-call has a runbook entry — no alert is missing
|
||||
- [ ] Rollback command is accurate and tested recently
|
||||
- [ ] Escalation contacts have current phone numbers and Slack handles
|
||||
- [ ] Diagnostic commands work — they have been run by at least one person recently
|
||||
- [ ] Handoff template is used at every shift change — not just during incidents
|
||||
- [ ] "Things I had to figure out that weren't documented" are added to this runbook after every incident
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user