diff --git a/plugins/pm-engineering/skills/changelog-generator/SKILL.md b/plugins/pm-engineering/skills/changelog-generator/SKILL.md index d2c6c03..e23762d 100644 --- a/plugins/pm-engineering/skills/changelog-generator/SKILL.md +++ b/plugins/pm-engineering/skills/changelog-generator/SKILL.md @@ -15,6 +15,8 @@ Ask for these if not provided: - **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 @@ -52,6 +54,10 @@ Follow [Keep a Changelog](https://keepachangelog.com) format: --- +--- + +> **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". @@ -72,7 +78,8 @@ Follow [Keep a Changelog](https://keepachangelog.com) format: - [ ] Related commits are grouped into single entries (not listed individually) - [ ] Version and date header is correct - [ ] Empty sections are omitted -- [ ] Tone is imperative mood throughout +- [ ] 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] diff --git a/plugins/pm-engineering/skills/code-review-checklist/SKILL.md b/plugins/pm-engineering/skills/code-review-checklist/SKILL.md index cb4e9da..4683150 100644 --- a/plugins/pm-engineering/skills/code-review-checklist/SKILL.md +++ b/plugins/pm-engineering/skills/code-review-checklist/SKILL.md @@ -14,6 +14,7 @@ Ask the user for these if not provided: - **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 @@ -22,9 +23,10 @@ Ask the user for these if not provided: # 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:** [Minutes] +**Estimated review time:** [e.g. 20–30 min — use 5 min per 50 lines of diff as a rough guide] ### 2. Correctness Checks @@ -102,7 +104,8 @@ Based on the change type and language, flag 2-3 things reviewers typically miss - [ ] Checklist is tailored to the stated language (not generic) - [ ] Change-type-specific section is included - [ ] Risk-appropriate depth matches stated risk level -- [ ] Decision framework is explicit +- [ ] 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]" diff --git a/plugins/pm-engineering/skills/debugging-log-analyser/SKILL.md b/plugins/pm-engineering/skills/debugging-log-analyser/SKILL.md index 21ff6a2..a438416 100644 --- a/plugins/pm-engineering/skills/debugging-log-analyser/SKILL.md +++ b/plugins/pm-engineering/skills/debugging-log-analyser/SKILL.md @@ -12,7 +12,8 @@ Parses raw error logs, stack traces, and crash reports into a structured diagnos 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 the user was doing when the error occurred) +- **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) @@ -22,6 +23,7 @@ Ask for these if not provided: # 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] @@ -73,7 +75,8 @@ One or two concrete things that would prevent this class of error recurring: - [ ] 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 -- [ ] Language-specific idioms are used correctly +- [ ] 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 diff --git a/plugins/pm-engineering/skills/incident-postmortem/SKILL.md b/plugins/pm-engineering/skills/incident-postmortem/SKILL.md index 2a4a153..6396a5f 100644 --- a/plugins/pm-engineering/skills/incident-postmortem/SKILL.md +++ b/plugins/pm-engineering/skills/incident-postmortem/SKILL.md @@ -20,6 +20,8 @@ Ask the user for these if not provided: - **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 diff --git a/plugins/pm-engineering/skills/pr-description-writer/SKILL.md b/plugins/pm-engineering/skills/pr-description-writer/SKILL.md index 89f5e3c..70796b5 100644 --- a/plugins/pm-engineering/skills/pr-description-writer/SKILL.md +++ b/plugins/pm-engineering/skills/pr-description-writer/SKILL.md @@ -15,6 +15,8 @@ Ask for these if not provided: - **How to test it** (any specific steps a reviewer needs to verify it works) - **Risk level** (low / medium / high — affects how much reviewer guidance to include) - **PR type** (feature / bug fix / refactor / dependency upgrade / config change / hotfix) +- **Target branch** (e.g. main / develop / release/2.4 — affects risk framing and reviewer guidance) +- **Linked issue or ticket** (e.g. JIRA-1234, GitHub #567 — or "none") ## Output Format @@ -43,7 +45,7 @@ Bullet list of specific changes — one bullet per logical change, not per file: ### Screenshots / Demo [If UI change: include before/after screenshots or a screen recording] [If API change: include example request/response] -[If no visual change: this section can be omitted] +[If no visual change and no API contract change: omit this section entirely — do not leave it as a placeholder] ### How to Test Step-by-step instructions a reviewer can follow: diff --git a/plugins/pm-engineering/skills/runbook-writer/SKILL.md b/plugins/pm-engineering/skills/runbook-writer/SKILL.md index 83a52f2..fdb77bc 100644 --- a/plugins/pm-engineering/skills/runbook-writer/SKILL.md +++ b/plugins/pm-engineering/skills/runbook-writer/SKILL.md @@ -15,6 +15,8 @@ Ask for these if not provided: - **System/service name and what it does** (brief description) - **Audience** (new on-call engineers / experienced SREs / DevOps team) - **Tech stack** (where relevant — e.g. Kubernetes, AWS RDS, Node.js) +- **Monitoring tools** (e.g. Grafana, Datadog, CloudWatch, Splunk — used to name specific dashboards and alert links in the steps) +- **Key environment details** (e.g. Kubernetes cluster name, AWS account/region, relevant namespaces or resource names — paste what's relevant for exact commands) ## Output Format @@ -22,7 +24,7 @@ Ask for these if not provided: **Runbook:** [Runbook Title] **Service:** [Service Name] **Type:** [Deployment / Incident Response / Maintenance / DR] -**Last Updated:** [Date] +**Last Updated:** [Insert today's date in YYYY-MM-DD format] **Owner:** [Team or person] **Severity:** [P1 / P2 / P3 — if incident-type] @@ -133,7 +135,8 @@ After completing the runbook: - [ ] Expected output is specified for each step so engineer knows if it worked - [ ] Failure path is explicit for each step (not "if it fails, investigate") - [ ] Rollback procedure is complete and independently testable -- [ ] Escalation paths name specific contacts, not just team names +- [ ] Escalation table has no cells containing only "[Team name]" — every row must either have a real contact or be explicitly flagged as [FILL IN: on-call rotation link] +- [ ] Rollback section contains at least one concrete command (not left as "[rollback command]" placeholder) - [ ] Runbook can be followed by someone who has never touched this system ## Usage Examples diff --git a/plugins/pm-engineering/skills/test-strategy-doc/SKILL.md b/plugins/pm-engineering/skills/test-strategy-doc/SKILL.md index d01f9b1..a39d188 100644 --- a/plugins/pm-engineering/skills/test-strategy-doc/SKILL.md +++ b/plugins/pm-engineering/skills/test-strategy-doc/SKILL.md @@ -11,7 +11,9 @@ Produces a complete test strategy from a feature spec, PRD, or system descriptio Ask for these if not provided: - **Feature or system being tested** (paste a spec, PRD, or describe it in plain English) -- **Tech stack** (language, framework, testing tools already in use if known) +- **Tech stack** (language and framework — e.g. TypeScript + React, Python + FastAPI) +- **Existing test coverage** (e.g. "we have unit tests but no E2E tests", "we use Jest + Playwright already", or "starting from scratch") +- **Deployment cadence** (e.g. continuous deployment / weekly releases / quarterly — affects what must be automated vs. manual) - **Risk level** (low / medium / high / critical — affects depth and coverage requirements) - **Timeline** (when does this need to ship — affects prioritisation) - **Team context** (who is doing the testing — developers / dedicated QA / both) @@ -66,7 +68,7 @@ Identify the highest-risk areas first — these drive depth and coverage: - **Tools:** [e.g. Playwright, Cypress, Selenium] - **Focus areas:** [The 3–5 most critical user flows] -**Performance Tests** *(include only if risk is medium+)* +**Performance Tests** *(include if any row in the Risk Assessment table has performance as a risk factor, regardless of overall risk level)* - **What:** Load, stress, or latency testing - **Targets:** [Specific numbers — e.g. 200 req/sec at p95 < 200ms] - **Tools:** [e.g. k6, Locust, JMeter] @@ -115,7 +117,8 @@ Testing is complete when: ## Quality Checks - [ ] Risk table is populated and drives test priority (not filled in generically) -- [ ] P0 test cases cover the highest-risk paths specifically +- [ ] Every "P0 — exhaustive" row in the Risk Assessment table has at least one corresponding P0 test case +- [ ] "Out of scope" section names at least one explicit exclusion (not left blank) - [ ] Each test type names a concrete tool (not "some testing framework") - [ ] Definition of Done is measurable (not "tests are done when QA is happy") diff --git a/skills/changelog-generator/SKILL.md b/skills/changelog-generator/SKILL.md index d2c6c03..e23762d 100644 --- a/skills/changelog-generator/SKILL.md +++ b/skills/changelog-generator/SKILL.md @@ -15,6 +15,8 @@ Ask for these if not provided: - **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 @@ -52,6 +54,10 @@ Follow [Keep a Changelog](https://keepachangelog.com) format: --- +--- + +> **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". @@ -72,7 +78,8 @@ Follow [Keep a Changelog](https://keepachangelog.com) format: - [ ] Related commits are grouped into single entries (not listed individually) - [ ] Version and date header is correct - [ ] Empty sections are omitted -- [ ] Tone is imperative mood throughout +- [ ] 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] diff --git a/skills/code-review-checklist/SKILL.md b/skills/code-review-checklist/SKILL.md index cb4e9da..4683150 100644 --- a/skills/code-review-checklist/SKILL.md +++ b/skills/code-review-checklist/SKILL.md @@ -14,6 +14,7 @@ Ask the user for these if not provided: - **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 @@ -22,9 +23,10 @@ Ask the user for these if not provided: # 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:** [Minutes] +**Estimated review time:** [e.g. 20–30 min — use 5 min per 50 lines of diff as a rough guide] ### 2. Correctness Checks @@ -102,7 +104,8 @@ Based on the change type and language, flag 2-3 things reviewers typically miss - [ ] Checklist is tailored to the stated language (not generic) - [ ] Change-type-specific section is included - [ ] Risk-appropriate depth matches stated risk level -- [ ] Decision framework is explicit +- [ ] 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]" diff --git a/skills/debugging-log-analyser/SKILL.md b/skills/debugging-log-analyser/SKILL.md index 21ff6a2..a438416 100644 --- a/skills/debugging-log-analyser/SKILL.md +++ b/skills/debugging-log-analyser/SKILL.md @@ -12,7 +12,8 @@ Parses raw error logs, stack traces, and crash reports into a structured diagnos 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 the user was doing when the error occurred) +- **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) @@ -22,6 +23,7 @@ Ask for these if not provided: # 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] @@ -73,7 +75,8 @@ One or two concrete things that would prevent this class of error recurring: - [ ] 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 -- [ ] Language-specific idioms are used correctly +- [ ] 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 diff --git a/skills/incident-postmortem/SKILL.md b/skills/incident-postmortem/SKILL.md index 2a4a153..6396a5f 100644 --- a/skills/incident-postmortem/SKILL.md +++ b/skills/incident-postmortem/SKILL.md @@ -20,6 +20,8 @@ Ask the user for these if not provided: - **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 diff --git a/skills/pr-description-writer/SKILL.md b/skills/pr-description-writer/SKILL.md index 89f5e3c..70796b5 100644 --- a/skills/pr-description-writer/SKILL.md +++ b/skills/pr-description-writer/SKILL.md @@ -15,6 +15,8 @@ Ask for these if not provided: - **How to test it** (any specific steps a reviewer needs to verify it works) - **Risk level** (low / medium / high — affects how much reviewer guidance to include) - **PR type** (feature / bug fix / refactor / dependency upgrade / config change / hotfix) +- **Target branch** (e.g. main / develop / release/2.4 — affects risk framing and reviewer guidance) +- **Linked issue or ticket** (e.g. JIRA-1234, GitHub #567 — or "none") ## Output Format @@ -43,7 +45,7 @@ Bullet list of specific changes — one bullet per logical change, not per file: ### Screenshots / Demo [If UI change: include before/after screenshots or a screen recording] [If API change: include example request/response] -[If no visual change: this section can be omitted] +[If no visual change and no API contract change: omit this section entirely — do not leave it as a placeholder] ### How to Test Step-by-step instructions a reviewer can follow: diff --git a/skills/runbook-writer/SKILL.md b/skills/runbook-writer/SKILL.md index 83a52f2..fdb77bc 100644 --- a/skills/runbook-writer/SKILL.md +++ b/skills/runbook-writer/SKILL.md @@ -15,6 +15,8 @@ Ask for these if not provided: - **System/service name and what it does** (brief description) - **Audience** (new on-call engineers / experienced SREs / DevOps team) - **Tech stack** (where relevant — e.g. Kubernetes, AWS RDS, Node.js) +- **Monitoring tools** (e.g. Grafana, Datadog, CloudWatch, Splunk — used to name specific dashboards and alert links in the steps) +- **Key environment details** (e.g. Kubernetes cluster name, AWS account/region, relevant namespaces or resource names — paste what's relevant for exact commands) ## Output Format @@ -22,7 +24,7 @@ Ask for these if not provided: **Runbook:** [Runbook Title] **Service:** [Service Name] **Type:** [Deployment / Incident Response / Maintenance / DR] -**Last Updated:** [Date] +**Last Updated:** [Insert today's date in YYYY-MM-DD format] **Owner:** [Team or person] **Severity:** [P1 / P2 / P3 — if incident-type] @@ -133,7 +135,8 @@ After completing the runbook: - [ ] Expected output is specified for each step so engineer knows if it worked - [ ] Failure path is explicit for each step (not "if it fails, investigate") - [ ] Rollback procedure is complete and independently testable -- [ ] Escalation paths name specific contacts, not just team names +- [ ] Escalation table has no cells containing only "[Team name]" — every row must either have a real contact or be explicitly flagged as [FILL IN: on-call rotation link] +- [ ] Rollback section contains at least one concrete command (not left as "[rollback command]" placeholder) - [ ] Runbook can be followed by someone who has never touched this system ## Usage Examples diff --git a/skills/test-strategy-doc/SKILL.md b/skills/test-strategy-doc/SKILL.md index d01f9b1..a39d188 100644 --- a/skills/test-strategy-doc/SKILL.md +++ b/skills/test-strategy-doc/SKILL.md @@ -11,7 +11,9 @@ Produces a complete test strategy from a feature spec, PRD, or system descriptio Ask for these if not provided: - **Feature or system being tested** (paste a spec, PRD, or describe it in plain English) -- **Tech stack** (language, framework, testing tools already in use if known) +- **Tech stack** (language and framework — e.g. TypeScript + React, Python + FastAPI) +- **Existing test coverage** (e.g. "we have unit tests but no E2E tests", "we use Jest + Playwright already", or "starting from scratch") +- **Deployment cadence** (e.g. continuous deployment / weekly releases / quarterly — affects what must be automated vs. manual) - **Risk level** (low / medium / high / critical — affects depth and coverage requirements) - **Timeline** (when does this need to ship — affects prioritisation) - **Team context** (who is doing the testing — developers / dedicated QA / both) @@ -66,7 +68,7 @@ Identify the highest-risk areas first — these drive depth and coverage: - **Tools:** [e.g. Playwright, Cypress, Selenium] - **Focus areas:** [The 3–5 most critical user flows] -**Performance Tests** *(include only if risk is medium+)* +**Performance Tests** *(include if any row in the Risk Assessment table has performance as a risk factor, regardless of overall risk level)* - **What:** Load, stress, or latency testing - **Targets:** [Specific numbers — e.g. 200 req/sec at p95 < 200ms] - **Tools:** [e.g. k6, Locust, JMeter] @@ -115,7 +117,8 @@ Testing is complete when: ## Quality Checks - [ ] Risk table is populated and drives test priority (not filled in generically) -- [ ] P0 test cases cover the highest-risk paths specifically +- [ ] Every "P0 — exhaustive" row in the Risk Assessment table has at least one corresponding P0 test case +- [ ] "Out of scope" section names at least one explicit exclusion (not left blank) - [ ] Each test type names a concrete tool (not "some testing framework") - [ ] Definition of Done is measurable (not "tests are done when QA is happy")