From e366a77cf0b948bd5732e3a47915678d02d47296 Mon Sep 17 00:00:00 2001 From: mohitagw15856 Date: Wed, 20 May 2026 07:36:10 +0000 Subject: [PATCH 1/4] Quality-improve 10 v7.0.0-era engineering skills MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Applies three consistent fixes across the v7.0.0 batch: - Rename `## Output Structure` → `## Output Format` for consistency - Wrap output template in `---` document separators (code-review-checklist, debugging-log-analyser needed full structural upgrade; remaining 8 already had the wrapper) - Remove `## Example Trigger Phrases` section from all 10 skills Skills updated: code-review-checklist, debugging-log-analyser, changelog-generator, pr-description-writer, system-design-interview, test-strategy-doc, runbook-writer, incident-postmortem, api-docs-writer, architecture-decision-record Both `skills/` and `plugins/pm-engineering/skills/` copies synced. https://claude.ai/code/session_01C3HwChrccJd145vJ6Z7ajF --- .../skills/api-docs-writer/SKILL.md | 9 +-------- .../architecture-decision-record/SKILL.md | 9 +-------- .../skills/changelog-generator/SKILL.md | 11 ++-------- .../skills/code-review-checklist/SKILL.md | 18 ++++++++--------- .../skills/debugging-log-analyser/SKILL.md | 20 +++++++++---------- .../skills/incident-postmortem/SKILL.md | 9 +-------- .../skills/pr-description-writer/SKILL.md | 11 ++-------- .../skills/runbook-writer/SKILL.md | 11 ++-------- .../skills/system-design-interview/SKILL.md | 11 ++-------- .../skills/test-strategy-doc/SKILL.md | 11 ++-------- skills/api-docs-writer/SKILL.md | 9 +-------- skills/architecture-decision-record/SKILL.md | 9 +-------- skills/changelog-generator/SKILL.md | 11 ++-------- skills/code-review-checklist/SKILL.md | 18 ++++++++--------- skills/debugging-log-analyser/SKILL.md | 20 +++++++++---------- skills/incident-postmortem/SKILL.md | 9 +-------- skills/pr-description-writer/SKILL.md | 11 ++-------- skills/runbook-writer/SKILL.md | 11 ++-------- skills/system-design-interview/SKILL.md | 11 ++-------- skills/test-strategy-doc/SKILL.md | 11 ++-------- 20 files changed, 60 insertions(+), 180 deletions(-) diff --git a/plugins/pm-engineering/skills/api-docs-writer/SKILL.md b/plugins/pm-engineering/skills/api-docs-writer/SKILL.md index 29b4a69..e6d9977 100644 --- a/plugins/pm-engineering/skills/api-docs-writer/SKILL.md +++ b/plugins/pm-engineering/skills/api-docs-writer/SKILL.md @@ -16,7 +16,7 @@ Ask the user for these if not provided: - **Audience** (internal developers / external partners / public) - **Output format** (Markdown / OpenAPI YAML / Plain prose) -## Output Structure +## Output Format For each endpoint, produce the following: @@ -137,10 +137,3 @@ data = response.json() - [ ] Auth method is clearly stated at the top - [ ] Enum values are listed where applicable - [ ] Pagination documented if the endpoint is a list endpoint - -## Example Trigger Phrases - -- "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" diff --git a/plugins/pm-engineering/skills/architecture-decision-record/SKILL.md b/plugins/pm-engineering/skills/architecture-decision-record/SKILL.md index 0948d6a..a61c362 100644 --- a/plugins/pm-engineering/skills/architecture-decision-record/SKILL.md +++ b/plugins/pm-engineering/skills/architecture-decision-record/SKILL.md @@ -18,7 +18,7 @@ Ask the user for these if not provided: - **Status** (Proposed / Accepted / Deprecated / Superseded) - **Author and date** -## Output Structure +## Output Format --- @@ -108,10 +108,3 @@ For each option, produce: - [ ] Decision is stated in plain language in the Decision section - [ ] Risks section identifies what would invalidate this decision - [ ] Written for someone with no prior context on this decision - -## Example Trigger Phrases - -- "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]" diff --git a/plugins/pm-engineering/skills/changelog-generator/SKILL.md b/plugins/pm-engineering/skills/changelog-generator/SKILL.md index 64c8dd1..5716403 100644 --- a/plugins/pm-engineering/skills/changelog-generator/SKILL.md +++ b/plugins/pm-engineering/skills/changelog-generator/SKILL.md @@ -1,6 +1,6 @@ --- 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. Optimised for Opus 4.7 and newer models." +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 @@ -16,7 +16,7 @@ Ask for these if not provided: - **Audience** (developers using an API / end users of a product / internal team — affects language) - **Any breaking changes** (flag these explicitly if known) -## Output Structure +## Output Format Follow [Keep a Changelog](https://keepachangelog.com) format: @@ -73,10 +73,3 @@ Follow [Keep a Changelog](https://keepachangelog.com) format: - [ ] Version and date header is correct - [ ] Empty sections are omitted - [ ] Tone is imperative mood throughout - -## Example Trigger Phrases -- "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] diff --git a/plugins/pm-engineering/skills/code-review-checklist/SKILL.md b/plugins/pm-engineering/skills/code-review-checklist/SKILL.md index 38b87fa..29edd69 100644 --- a/plugins/pm-engineering/skills/code-review-checklist/SKILL.md +++ b/plugins/pm-engineering/skills/code-review-checklist/SKILL.md @@ -1,6 +1,6 @@ --- 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. Optimised for Opus 4.7 and newer models." +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 @@ -16,10 +16,12 @@ Ask the user for these if not provided: - **PR description** (paste the description or link to the PR) - **Author context** (new starter / experienced / external contributor) -## Output Structure +## Output Format + +--- + +# Code Review: [PR Title or Reference] -### 1. Review Summary -**PR:** [Title or reference] **Scope assessment:** [Small / Medium / Large / Too large — should be split] **Recommended review depth:** [Skim / Standard / Deep dive] **Estimated review time:** [Minutes] @@ -94,14 +96,10 @@ Language-specific correctness checks — choose based on the language stated: ### 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 is explicit - -## Example Trigger Phrases -- "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]" \ No newline at end of file diff --git a/plugins/pm-engineering/skills/debugging-log-analyser/SKILL.md b/plugins/pm-engineering/skills/debugging-log-analyser/SKILL.md index b1c9347..ffeb2b3 100644 --- a/plugins/pm-engineering/skills/debugging-log-analyser/SKILL.md +++ b/plugins/pm-engineering/skills/debugging-log-analyser/SKILL.md @@ -1,6 +1,6 @@ --- 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. Optimised for Opus 4.7 and newer models." +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 @@ -16,10 +16,13 @@ Ask for these if not provided: - **Environment** (local dev / staging / production) - **What they've already tried** (if anything) -## Output Structure +## Output Format -### 1. Error Classification -**Error type:** [Runtime exception / Build error / Config error / Network error / Memory/resource error / Unknown] +--- + +# Debugging Report: [Service/App Name] + +**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] @@ -64,16 +67,11 @@ One or two concrete things that would prevent this class of error recurring: - 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 - [ ] Language-specific idioms are used correctly - [ ] Prevention is proactive (not just "add error handling") - -## Example Trigger Phrases -- "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?" diff --git a/plugins/pm-engineering/skills/incident-postmortem/SKILL.md b/plugins/pm-engineering/skills/incident-postmortem/SKILL.md index 744397f..af1e3ff 100644 --- a/plugins/pm-engineering/skills/incident-postmortem/SKILL.md +++ b/plugins/pm-engineering/skills/incident-postmortem/SKILL.md @@ -21,7 +21,7 @@ Ask the user for these if not provided: - **Initial thoughts on root cause** - **Action items already identified** (optional) -## Output Structure +## Output Format --- @@ -135,10 +135,3 @@ Rules for action items: - [ ] Every action item has an owner and due date - [ ] "What went well" section is genuine, not token - [ ] Executive summary is readable by non-technical leadership - -## Example Trigger Phrases - -- "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]" diff --git a/plugins/pm-engineering/skills/pr-description-writer/SKILL.md b/plugins/pm-engineering/skills/pr-description-writer/SKILL.md index 5dca74c..f488f07 100644 --- a/plugins/pm-engineering/skills/pr-description-writer/SKILL.md +++ b/plugins/pm-engineering/skills/pr-description-writer/SKILL.md @@ -1,6 +1,6 @@ --- name: pr-description-writer -description: "Write a clear, structured pull request description from a git diff, branch summary, or commit list. Use when asked to write a PR description, draft a pull request, or document code changes. Produces a description with summary, motivation, changes made, testing steps, and reviewer guidance. Optimised for Opus 4.7 and newer models." +description: "Write a clear, structured pull request description from a git diff, branch summary, or commit list. Use when asked to write a PR description, draft a pull request, or document code changes. Produces a description with summary, motivation, changes made, testing steps, and reviewer guidance." --- # PR Description Writer Skill @@ -16,7 +16,7 @@ Ask for these if not provided: - **Risk level** (low / medium / high — affects how much reviewer guidance to include) - **PR type** (feature / bug fix / refactor / dependency upgrade / config change / hotfix) -## Output Structure +## Output Format ### Title A clear, imperative-mood title under 72 characters: @@ -78,10 +78,3 @@ Flag anything that warrants extra attention: - [ ] Changes list describes logical changes (not file-by-file changes) - [ ] Testing steps are reproducible by someone unfamiliar with the code - [ ] Risk-appropriate reviewer guidance is included - -## Example Trigger Phrases -- "Write a PR description for these changes" + [paste diff or description] -- "Draft a pull request for [feature]" -- "I need a PR description — here's what I changed" -- "Summarise these commits into a PR description" -- "Write the PR body for this branch" diff --git a/plugins/pm-engineering/skills/runbook-writer/SKILL.md b/plugins/pm-engineering/skills/runbook-writer/SKILL.md index b75922d..4571add 100644 --- a/plugins/pm-engineering/skills/runbook-writer/SKILL.md +++ b/plugins/pm-engineering/skills/runbook-writer/SKILL.md @@ -1,6 +1,6 @@ --- name: runbook-writer -description: "Write an operational runbook for a service, incident type, or deployment procedure. Use when asked to write a runbook, create an ops guide, document an operational procedure, or prepare an incident response playbook. Produces a runbook with overview, prerequisites, step-by-step procedures, rollback steps, troubleshooting table, and escalation paths. Optimised for Opus 4.7 and newer models." +description: "Write an operational runbook for a service, incident type, or deployment procedure. Use when asked to write a runbook, create an ops guide, document an operational procedure, or prepare an incident response playbook. Produces a runbook with overview, prerequisites, step-by-step procedures, rollback steps, troubleshooting table, and escalation paths." --- # Runbook Writer Skill @@ -16,7 +16,7 @@ Ask for these if not provided: - **Audience** (new on-call engineers / experienced SREs / DevOps team) - **Tech stack** (where relevant — e.g. Kubernetes, AWS RDS, Node.js) -## Output Structure +## Output Format --- **Runbook:** [Runbook Title] @@ -135,10 +135,3 @@ After completing the runbook: - [ ] Rollback procedure is complete and independently testable - [ ] Escalation paths name specific contacts, not just team names - [ ] Runbook can be followed by someone who has never touched this system - -## Example Trigger Phrases -- "Write a runbook for [service] deployment" -- "Create an incident response runbook for [alert type]" -- "I need a runbook for [procedure]" -- "Document the operational procedure for [X]" -- "Write an ops playbook for [scenario]" diff --git a/plugins/pm-engineering/skills/system-design-interview/SKILL.md b/plugins/pm-engineering/skills/system-design-interview/SKILL.md index e3a10e8..496cedb 100644 --- a/plugins/pm-engineering/skills/system-design-interview/SKILL.md +++ b/plugins/pm-engineering/skills/system-design-interview/SKILL.md @@ -1,6 +1,6 @@ --- name: system-design-interview -description: "Structure a complete system design answer for interview questions or real architecture sessions. Use when asked to design a system, answer a system design interview question, or architect a solution at scale. Produces a structured answer covering requirements, capacity estimates, high-level design, component deep-dives, trade-offs, and follow-up considerations. Optimised for Opus 4.7 and newer models." +description: "Structure a complete system design answer for interview questions or real architecture sessions. Use when asked to design a system, answer a system design interview question, or architect a solution at scale. Produces a structured answer covering requirements, capacity estimates, high-level design, component deep-dives, trade-offs, and follow-up considerations." --- # System Design Interview Skill @@ -15,7 +15,7 @@ Ask for these if not provided: - **Scale target** (rough numbers: DAU, requests/sec, data volume — or "assume typical web scale") - **Constraints or priorities** (e.g. prioritise availability over consistency, minimise cost, low-latency reads) -## Output Structure +## Output Format ### 1. Clarifying Questions Before designing, list 4–6 questions that would change the design. Examples: @@ -126,10 +126,3 @@ Things to tackle in production but out of scope for this design session: - [ ] At least 2 component deep-dives with technology choices justified - [ ] Trade-offs section is honest (not just benefits of chosen approach) - [ ] Data flow is described end-to-end for the critical path - -## Example Trigger Phrases -- "Help me answer a system design interview: [question]" -- "Design [system] for a system design interview" -- "How would I architect [system] at scale?" -- "I have a system design interview — the question is [X]" -- "Design a [URL shortener / chat system / notification service / feed]" diff --git a/plugins/pm-engineering/skills/test-strategy-doc/SKILL.md b/plugins/pm-engineering/skills/test-strategy-doc/SKILL.md index 68dc7ec..bcfd3dc 100644 --- a/plugins/pm-engineering/skills/test-strategy-doc/SKILL.md +++ b/plugins/pm-engineering/skills/test-strategy-doc/SKILL.md @@ -1,6 +1,6 @@ --- name: test-strategy-doc -description: "Write a test strategy document from a feature spec, PRD, or system description. Use when asked to create a test plan, write a test strategy, define QA approach, or plan testing for a feature or release. Produces a complete test strategy with scope, risk assessment, test types, coverage targets, and a prioritised test case outline. Optimised for Opus 4.7 and newer models." +description: "Write a test strategy document from a feature spec, PRD, or system description. Use when asked to create a test plan, write a test strategy, define QA approach, or plan testing for a feature or release. Produces a complete test strategy with scope, risk assessment, test types, coverage targets, and a prioritised test case outline." --- # Test Strategy Document Skill @@ -16,7 +16,7 @@ Ask for these if not provided: - **Timeline** (when does this need to ship — affects prioritisation) - **Team context** (who is doing the testing — developers / dedicated QA / both) -## Output Structure +## Output Format ### 1. Test Scope @@ -118,10 +118,3 @@ Testing is complete when: - [ ] P0 test cases cover the highest-risk paths specifically - [ ] Each test type names a concrete tool (not "some testing framework") - [ ] Definition of Done is measurable (not "tests are done when QA is happy") - -## Example Trigger Phrases -- "Write a test strategy for [feature]" + [paste spec or PRD] -- "Create a test plan for [system]" -- "How should we test [feature]?" -- "I need a QA plan for this sprint" -- "What tests do we need for [X]?" diff --git a/skills/api-docs-writer/SKILL.md b/skills/api-docs-writer/SKILL.md index 29b4a69..e6d9977 100644 --- a/skills/api-docs-writer/SKILL.md +++ b/skills/api-docs-writer/SKILL.md @@ -16,7 +16,7 @@ Ask the user for these if not provided: - **Audience** (internal developers / external partners / public) - **Output format** (Markdown / OpenAPI YAML / Plain prose) -## Output Structure +## Output Format For each endpoint, produce the following: @@ -137,10 +137,3 @@ data = response.json() - [ ] Auth method is clearly stated at the top - [ ] Enum values are listed where applicable - [ ] Pagination documented if the endpoint is a list endpoint - -## Example Trigger Phrases - -- "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" diff --git a/skills/architecture-decision-record/SKILL.md b/skills/architecture-decision-record/SKILL.md index 0948d6a..a61c362 100644 --- a/skills/architecture-decision-record/SKILL.md +++ b/skills/architecture-decision-record/SKILL.md @@ -18,7 +18,7 @@ Ask the user for these if not provided: - **Status** (Proposed / Accepted / Deprecated / Superseded) - **Author and date** -## Output Structure +## Output Format --- @@ -108,10 +108,3 @@ For each option, produce: - [ ] Decision is stated in plain language in the Decision section - [ ] Risks section identifies what would invalidate this decision - [ ] Written for someone with no prior context on this decision - -## Example Trigger Phrases - -- "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]" diff --git a/skills/changelog-generator/SKILL.md b/skills/changelog-generator/SKILL.md index 64c8dd1..5716403 100644 --- a/skills/changelog-generator/SKILL.md +++ b/skills/changelog-generator/SKILL.md @@ -1,6 +1,6 @@ --- 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. Optimised for Opus 4.7 and newer models." +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 @@ -16,7 +16,7 @@ Ask for these if not provided: - **Audience** (developers using an API / end users of a product / internal team — affects language) - **Any breaking changes** (flag these explicitly if known) -## Output Structure +## Output Format Follow [Keep a Changelog](https://keepachangelog.com) format: @@ -73,10 +73,3 @@ Follow [Keep a Changelog](https://keepachangelog.com) format: - [ ] Version and date header is correct - [ ] Empty sections are omitted - [ ] Tone is imperative mood throughout - -## Example Trigger Phrases -- "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] diff --git a/skills/code-review-checklist/SKILL.md b/skills/code-review-checklist/SKILL.md index 38b87fa..29edd69 100644 --- a/skills/code-review-checklist/SKILL.md +++ b/skills/code-review-checklist/SKILL.md @@ -1,6 +1,6 @@ --- 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. Optimised for Opus 4.7 and newer models." +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 @@ -16,10 +16,12 @@ Ask the user for these if not provided: - **PR description** (paste the description or link to the PR) - **Author context** (new starter / experienced / external contributor) -## Output Structure +## Output Format + +--- + +# Code Review: [PR Title or Reference] -### 1. Review Summary -**PR:** [Title or reference] **Scope assessment:** [Small / Medium / Large / Too large — should be split] **Recommended review depth:** [Skim / Standard / Deep dive] **Estimated review time:** [Minutes] @@ -94,14 +96,10 @@ Language-specific correctness checks — choose based on the language stated: ### 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 is explicit - -## Example Trigger Phrases -- "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]" \ No newline at end of file diff --git a/skills/debugging-log-analyser/SKILL.md b/skills/debugging-log-analyser/SKILL.md index b1c9347..ffeb2b3 100644 --- a/skills/debugging-log-analyser/SKILL.md +++ b/skills/debugging-log-analyser/SKILL.md @@ -1,6 +1,6 @@ --- 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. Optimised for Opus 4.7 and newer models." +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 @@ -16,10 +16,13 @@ Ask for these if not provided: - **Environment** (local dev / staging / production) - **What they've already tried** (if anything) -## Output Structure +## Output Format -### 1. Error Classification -**Error type:** [Runtime exception / Build error / Config error / Network error / Memory/resource error / Unknown] +--- + +# Debugging Report: [Service/App Name] + +**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] @@ -64,16 +67,11 @@ One or two concrete things that would prevent this class of error recurring: - 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 - [ ] Language-specific idioms are used correctly - [ ] Prevention is proactive (not just "add error handling") - -## Example Trigger Phrases -- "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?" diff --git a/skills/incident-postmortem/SKILL.md b/skills/incident-postmortem/SKILL.md index 744397f..af1e3ff 100644 --- a/skills/incident-postmortem/SKILL.md +++ b/skills/incident-postmortem/SKILL.md @@ -21,7 +21,7 @@ Ask the user for these if not provided: - **Initial thoughts on root cause** - **Action items already identified** (optional) -## Output Structure +## Output Format --- @@ -135,10 +135,3 @@ Rules for action items: - [ ] Every action item has an owner and due date - [ ] "What went well" section is genuine, not token - [ ] Executive summary is readable by non-technical leadership - -## Example Trigger Phrases - -- "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]" diff --git a/skills/pr-description-writer/SKILL.md b/skills/pr-description-writer/SKILL.md index 5dca74c..f488f07 100644 --- a/skills/pr-description-writer/SKILL.md +++ b/skills/pr-description-writer/SKILL.md @@ -1,6 +1,6 @@ --- name: pr-description-writer -description: "Write a clear, structured pull request description from a git diff, branch summary, or commit list. Use when asked to write a PR description, draft a pull request, or document code changes. Produces a description with summary, motivation, changes made, testing steps, and reviewer guidance. Optimised for Opus 4.7 and newer models." +description: "Write a clear, structured pull request description from a git diff, branch summary, or commit list. Use when asked to write a PR description, draft a pull request, or document code changes. Produces a description with summary, motivation, changes made, testing steps, and reviewer guidance." --- # PR Description Writer Skill @@ -16,7 +16,7 @@ Ask for these if not provided: - **Risk level** (low / medium / high — affects how much reviewer guidance to include) - **PR type** (feature / bug fix / refactor / dependency upgrade / config change / hotfix) -## Output Structure +## Output Format ### Title A clear, imperative-mood title under 72 characters: @@ -78,10 +78,3 @@ Flag anything that warrants extra attention: - [ ] Changes list describes logical changes (not file-by-file changes) - [ ] Testing steps are reproducible by someone unfamiliar with the code - [ ] Risk-appropriate reviewer guidance is included - -## Example Trigger Phrases -- "Write a PR description for these changes" + [paste diff or description] -- "Draft a pull request for [feature]" -- "I need a PR description — here's what I changed" -- "Summarise these commits into a PR description" -- "Write the PR body for this branch" diff --git a/skills/runbook-writer/SKILL.md b/skills/runbook-writer/SKILL.md index b75922d..4571add 100644 --- a/skills/runbook-writer/SKILL.md +++ b/skills/runbook-writer/SKILL.md @@ -1,6 +1,6 @@ --- name: runbook-writer -description: "Write an operational runbook for a service, incident type, or deployment procedure. Use when asked to write a runbook, create an ops guide, document an operational procedure, or prepare an incident response playbook. Produces a runbook with overview, prerequisites, step-by-step procedures, rollback steps, troubleshooting table, and escalation paths. Optimised for Opus 4.7 and newer models." +description: "Write an operational runbook for a service, incident type, or deployment procedure. Use when asked to write a runbook, create an ops guide, document an operational procedure, or prepare an incident response playbook. Produces a runbook with overview, prerequisites, step-by-step procedures, rollback steps, troubleshooting table, and escalation paths." --- # Runbook Writer Skill @@ -16,7 +16,7 @@ Ask for these if not provided: - **Audience** (new on-call engineers / experienced SREs / DevOps team) - **Tech stack** (where relevant — e.g. Kubernetes, AWS RDS, Node.js) -## Output Structure +## Output Format --- **Runbook:** [Runbook Title] @@ -135,10 +135,3 @@ After completing the runbook: - [ ] Rollback procedure is complete and independently testable - [ ] Escalation paths name specific contacts, not just team names - [ ] Runbook can be followed by someone who has never touched this system - -## Example Trigger Phrases -- "Write a runbook for [service] deployment" -- "Create an incident response runbook for [alert type]" -- "I need a runbook for [procedure]" -- "Document the operational procedure for [X]" -- "Write an ops playbook for [scenario]" diff --git a/skills/system-design-interview/SKILL.md b/skills/system-design-interview/SKILL.md index e3a10e8..496cedb 100644 --- a/skills/system-design-interview/SKILL.md +++ b/skills/system-design-interview/SKILL.md @@ -1,6 +1,6 @@ --- name: system-design-interview -description: "Structure a complete system design answer for interview questions or real architecture sessions. Use when asked to design a system, answer a system design interview question, or architect a solution at scale. Produces a structured answer covering requirements, capacity estimates, high-level design, component deep-dives, trade-offs, and follow-up considerations. Optimised for Opus 4.7 and newer models." +description: "Structure a complete system design answer for interview questions or real architecture sessions. Use when asked to design a system, answer a system design interview question, or architect a solution at scale. Produces a structured answer covering requirements, capacity estimates, high-level design, component deep-dives, trade-offs, and follow-up considerations." --- # System Design Interview Skill @@ -15,7 +15,7 @@ Ask for these if not provided: - **Scale target** (rough numbers: DAU, requests/sec, data volume — or "assume typical web scale") - **Constraints or priorities** (e.g. prioritise availability over consistency, minimise cost, low-latency reads) -## Output Structure +## Output Format ### 1. Clarifying Questions Before designing, list 4–6 questions that would change the design. Examples: @@ -126,10 +126,3 @@ Things to tackle in production but out of scope for this design session: - [ ] At least 2 component deep-dives with technology choices justified - [ ] Trade-offs section is honest (not just benefits of chosen approach) - [ ] Data flow is described end-to-end for the critical path - -## Example Trigger Phrases -- "Help me answer a system design interview: [question]" -- "Design [system] for a system design interview" -- "How would I architect [system] at scale?" -- "I have a system design interview — the question is [X]" -- "Design a [URL shortener / chat system / notification service / feed]" diff --git a/skills/test-strategy-doc/SKILL.md b/skills/test-strategy-doc/SKILL.md index 68dc7ec..bcfd3dc 100644 --- a/skills/test-strategy-doc/SKILL.md +++ b/skills/test-strategy-doc/SKILL.md @@ -1,6 +1,6 @@ --- name: test-strategy-doc -description: "Write a test strategy document from a feature spec, PRD, or system description. Use when asked to create a test plan, write a test strategy, define QA approach, or plan testing for a feature or release. Produces a complete test strategy with scope, risk assessment, test types, coverage targets, and a prioritised test case outline. Optimised for Opus 4.7 and newer models." +description: "Write a test strategy document from a feature spec, PRD, or system description. Use when asked to create a test plan, write a test strategy, define QA approach, or plan testing for a feature or release. Produces a complete test strategy with scope, risk assessment, test types, coverage targets, and a prioritised test case outline." --- # Test Strategy Document Skill @@ -16,7 +16,7 @@ Ask for these if not provided: - **Timeline** (when does this need to ship — affects prioritisation) - **Team context** (who is doing the testing — developers / dedicated QA / both) -## Output Structure +## Output Format ### 1. Test Scope @@ -118,10 +118,3 @@ Testing is complete when: - [ ] P0 test cases cover the highest-risk paths specifically - [ ] Each test type names a concrete tool (not "some testing framework") - [ ] Definition of Done is measurable (not "tests are done when QA is happy") - -## Example Trigger Phrases -- "Write a test strategy for [feature]" + [paste spec or PRD] -- "Create a test plan for [system]" -- "How should we test [feature]?" -- "I need a QA plan for this sprint" -- "What tests do we need for [X]?" From 929fa3ad7f7e088d4e6fa57a78fbc25477d8982c Mon Sep 17 00:00:00 2001 From: mohitagw15856 Date: Wed, 20 May 2026 07:57:08 +0000 Subject: [PATCH 2/4] Restore trigger phrases as ## Usage Examples across 10 engineering skills MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Renamed ## Example Trigger Phrases → ## Usage Examples to make the section clearly human-facing documentation rather than a system instruction. Restores content that was removed in the previous quality pass. Skills updated (both skills/ and plugins/pm-engineering/skills/): code-review-checklist, debugging-log-analyser, changelog-generator, pr-description-writer, system-design-interview, test-strategy-doc, runbook-writer, incident-postmortem, api-docs-writer, architecture-decision-record https://claude.ai/code/session_01C3HwChrccJd145vJ6Z7ajF --- plugins/pm-engineering/skills/api-docs-writer/SKILL.md | 6 ++++++ .../skills/architecture-decision-record/SKILL.md | 6 ++++++ plugins/pm-engineering/skills/changelog-generator/SKILL.md | 7 +++++++ .../pm-engineering/skills/code-review-checklist/SKILL.md | 6 ++++++ .../pm-engineering/skills/debugging-log-analyser/SKILL.md | 7 +++++++ plugins/pm-engineering/skills/incident-postmortem/SKILL.md | 6 ++++++ .../pm-engineering/skills/pr-description-writer/SKILL.md | 7 +++++++ plugins/pm-engineering/skills/runbook-writer/SKILL.md | 7 +++++++ .../pm-engineering/skills/system-design-interview/SKILL.md | 7 +++++++ plugins/pm-engineering/skills/test-strategy-doc/SKILL.md | 7 +++++++ skills/api-docs-writer/SKILL.md | 6 ++++++ skills/architecture-decision-record/SKILL.md | 6 ++++++ skills/changelog-generator/SKILL.md | 7 +++++++ skills/code-review-checklist/SKILL.md | 6 ++++++ skills/debugging-log-analyser/SKILL.md | 7 +++++++ skills/incident-postmortem/SKILL.md | 6 ++++++ skills/pr-description-writer/SKILL.md | 7 +++++++ skills/runbook-writer/SKILL.md | 7 +++++++ skills/system-design-interview/SKILL.md | 7 +++++++ skills/test-strategy-doc/SKILL.md | 7 +++++++ 20 files changed, 132 insertions(+) diff --git a/plugins/pm-engineering/skills/api-docs-writer/SKILL.md b/plugins/pm-engineering/skills/api-docs-writer/SKILL.md index e6d9977..8953450 100644 --- a/plugins/pm-engineering/skills/api-docs-writer/SKILL.md +++ b/plugins/pm-engineering/skills/api-docs-writer/SKILL.md @@ -137,3 +137,9 @@ data = response.json() - [ ] 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" diff --git a/plugins/pm-engineering/skills/architecture-decision-record/SKILL.md b/plugins/pm-engineering/skills/architecture-decision-record/SKILL.md index a61c362..e0e3d71 100644 --- a/plugins/pm-engineering/skills/architecture-decision-record/SKILL.md +++ b/plugins/pm-engineering/skills/architecture-decision-record/SKILL.md @@ -108,3 +108,9 @@ For each option, produce: - [ ] Decision is stated in plain language in the Decision section - [ ] Risks section identifies what would invalidate this decision - [ ] Written for someone with no prior context on this decision + +## 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]" diff --git a/plugins/pm-engineering/skills/changelog-generator/SKILL.md b/plugins/pm-engineering/skills/changelog-generator/SKILL.md index 5716403..d2c6c03 100644 --- a/plugins/pm-engineering/skills/changelog-generator/SKILL.md +++ b/plugins/pm-engineering/skills/changelog-generator/SKILL.md @@ -73,3 +73,10 @@ Follow [Keep a Changelog](https://keepachangelog.com) format: - [ ] Version and date header is correct - [ ] Empty sections are omitted - [ ] Tone is imperative mood throughout + +## 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] diff --git a/plugins/pm-engineering/skills/code-review-checklist/SKILL.md b/plugins/pm-engineering/skills/code-review-checklist/SKILL.md index 29edd69..cb4e9da 100644 --- a/plugins/pm-engineering/skills/code-review-checklist/SKILL.md +++ b/plugins/pm-engineering/skills/code-review-checklist/SKILL.md @@ -103,3 +103,9 @@ Based on the change type and language, flag 2-3 things reviewers typically miss - [ ] Change-type-specific section is included - [ ] Risk-appropriate depth matches stated risk level - [ ] Decision framework is explicit + +## 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]" diff --git a/plugins/pm-engineering/skills/debugging-log-analyser/SKILL.md b/plugins/pm-engineering/skills/debugging-log-analyser/SKILL.md index ffeb2b3..21ff6a2 100644 --- a/plugins/pm-engineering/skills/debugging-log-analyser/SKILL.md +++ b/plugins/pm-engineering/skills/debugging-log-analyser/SKILL.md @@ -75,3 +75,10 @@ One or two concrete things that would prevent this class of error recurring: - [ ] Next steps are actionable commands, not vague advice - [ ] Language-specific idioms are used correctly - [ ] 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?" diff --git a/plugins/pm-engineering/skills/incident-postmortem/SKILL.md b/plugins/pm-engineering/skills/incident-postmortem/SKILL.md index af1e3ff..2a4a153 100644 --- a/plugins/pm-engineering/skills/incident-postmortem/SKILL.md +++ b/plugins/pm-engineering/skills/incident-postmortem/SKILL.md @@ -135,3 +135,9 @@ Rules for action items: - [ ] Every action item has an owner and due date - [ ] "What went well" section is genuine, not token - [ ] 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]" diff --git a/plugins/pm-engineering/skills/pr-description-writer/SKILL.md b/plugins/pm-engineering/skills/pr-description-writer/SKILL.md index f488f07..89f5e3c 100644 --- a/plugins/pm-engineering/skills/pr-description-writer/SKILL.md +++ b/plugins/pm-engineering/skills/pr-description-writer/SKILL.md @@ -78,3 +78,10 @@ Flag anything that warrants extra attention: - [ ] Changes list describes logical changes (not file-by-file changes) - [ ] Testing steps are reproducible by someone unfamiliar with the code - [ ] Risk-appropriate reviewer guidance is included + +## Usage Examples +- "Write a PR description for these changes" + [paste diff or description] +- "Draft a pull request for [feature]" +- "I need a PR description — here's what I changed" +- "Summarise these commits into a PR description" +- "Write the PR body for this branch" diff --git a/plugins/pm-engineering/skills/runbook-writer/SKILL.md b/plugins/pm-engineering/skills/runbook-writer/SKILL.md index 4571add..83a52f2 100644 --- a/plugins/pm-engineering/skills/runbook-writer/SKILL.md +++ b/plugins/pm-engineering/skills/runbook-writer/SKILL.md @@ -135,3 +135,10 @@ After completing the runbook: - [ ] Rollback procedure is complete and independently testable - [ ] Escalation paths name specific contacts, not just team names - [ ] Runbook can be followed by someone who has never touched this system + +## Usage Examples +- "Write a runbook for [service] deployment" +- "Create an incident response runbook for [alert type]" +- "I need a runbook for [procedure]" +- "Document the operational procedure for [X]" +- "Write an ops playbook for [scenario]" diff --git a/plugins/pm-engineering/skills/system-design-interview/SKILL.md b/plugins/pm-engineering/skills/system-design-interview/SKILL.md index 496cedb..e2c74e9 100644 --- a/plugins/pm-engineering/skills/system-design-interview/SKILL.md +++ b/plugins/pm-engineering/skills/system-design-interview/SKILL.md @@ -126,3 +126,10 @@ Things to tackle in production but out of scope for this design session: - [ ] At least 2 component deep-dives with technology choices justified - [ ] Trade-offs section is honest (not just benefits of chosen approach) - [ ] Data flow is described end-to-end for the critical path + +## Usage Examples +- "Help me answer a system design interview: [question]" +- "Design [system] for a system design interview" +- "How would I architect [system] at scale?" +- "I have a system design interview — the question is [X]" +- "Design a [URL shortener / chat system / notification service / feed]" diff --git a/plugins/pm-engineering/skills/test-strategy-doc/SKILL.md b/plugins/pm-engineering/skills/test-strategy-doc/SKILL.md index bcfd3dc..d01f9b1 100644 --- a/plugins/pm-engineering/skills/test-strategy-doc/SKILL.md +++ b/plugins/pm-engineering/skills/test-strategy-doc/SKILL.md @@ -118,3 +118,10 @@ Testing is complete when: - [ ] P0 test cases cover the highest-risk paths specifically - [ ] Each test type names a concrete tool (not "some testing framework") - [ ] Definition of Done is measurable (not "tests are done when QA is happy") + +## Usage Examples +- "Write a test strategy for [feature]" + [paste spec or PRD] +- "Create a test plan for [system]" +- "How should we test [feature]?" +- "I need a QA plan for this sprint" +- "What tests do we need for [X]?" diff --git a/skills/api-docs-writer/SKILL.md b/skills/api-docs-writer/SKILL.md index e6d9977..8953450 100644 --- a/skills/api-docs-writer/SKILL.md +++ b/skills/api-docs-writer/SKILL.md @@ -137,3 +137,9 @@ data = response.json() - [ ] 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" diff --git a/skills/architecture-decision-record/SKILL.md b/skills/architecture-decision-record/SKILL.md index a61c362..e0e3d71 100644 --- a/skills/architecture-decision-record/SKILL.md +++ b/skills/architecture-decision-record/SKILL.md @@ -108,3 +108,9 @@ For each option, produce: - [ ] Decision is stated in plain language in the Decision section - [ ] Risks section identifies what would invalidate this decision - [ ] Written for someone with no prior context on this decision + +## 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]" diff --git a/skills/changelog-generator/SKILL.md b/skills/changelog-generator/SKILL.md index 5716403..d2c6c03 100644 --- a/skills/changelog-generator/SKILL.md +++ b/skills/changelog-generator/SKILL.md @@ -73,3 +73,10 @@ Follow [Keep a Changelog](https://keepachangelog.com) format: - [ ] Version and date header is correct - [ ] Empty sections are omitted - [ ] Tone is imperative mood throughout + +## 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] diff --git a/skills/code-review-checklist/SKILL.md b/skills/code-review-checklist/SKILL.md index 29edd69..cb4e9da 100644 --- a/skills/code-review-checklist/SKILL.md +++ b/skills/code-review-checklist/SKILL.md @@ -103,3 +103,9 @@ Based on the change type and language, flag 2-3 things reviewers typically miss - [ ] Change-type-specific section is included - [ ] Risk-appropriate depth matches stated risk level - [ ] Decision framework is explicit + +## 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]" diff --git a/skills/debugging-log-analyser/SKILL.md b/skills/debugging-log-analyser/SKILL.md index ffeb2b3..21ff6a2 100644 --- a/skills/debugging-log-analyser/SKILL.md +++ b/skills/debugging-log-analyser/SKILL.md @@ -75,3 +75,10 @@ One or two concrete things that would prevent this class of error recurring: - [ ] Next steps are actionable commands, not vague advice - [ ] Language-specific idioms are used correctly - [ ] 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?" diff --git a/skills/incident-postmortem/SKILL.md b/skills/incident-postmortem/SKILL.md index af1e3ff..2a4a153 100644 --- a/skills/incident-postmortem/SKILL.md +++ b/skills/incident-postmortem/SKILL.md @@ -135,3 +135,9 @@ Rules for action items: - [ ] Every action item has an owner and due date - [ ] "What went well" section is genuine, not token - [ ] 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]" diff --git a/skills/pr-description-writer/SKILL.md b/skills/pr-description-writer/SKILL.md index f488f07..89f5e3c 100644 --- a/skills/pr-description-writer/SKILL.md +++ b/skills/pr-description-writer/SKILL.md @@ -78,3 +78,10 @@ Flag anything that warrants extra attention: - [ ] Changes list describes logical changes (not file-by-file changes) - [ ] Testing steps are reproducible by someone unfamiliar with the code - [ ] Risk-appropriate reviewer guidance is included + +## Usage Examples +- "Write a PR description for these changes" + [paste diff or description] +- "Draft a pull request for [feature]" +- "I need a PR description — here's what I changed" +- "Summarise these commits into a PR description" +- "Write the PR body for this branch" diff --git a/skills/runbook-writer/SKILL.md b/skills/runbook-writer/SKILL.md index 4571add..83a52f2 100644 --- a/skills/runbook-writer/SKILL.md +++ b/skills/runbook-writer/SKILL.md @@ -135,3 +135,10 @@ After completing the runbook: - [ ] Rollback procedure is complete and independently testable - [ ] Escalation paths name specific contacts, not just team names - [ ] Runbook can be followed by someone who has never touched this system + +## Usage Examples +- "Write a runbook for [service] deployment" +- "Create an incident response runbook for [alert type]" +- "I need a runbook for [procedure]" +- "Document the operational procedure for [X]" +- "Write an ops playbook for [scenario]" diff --git a/skills/system-design-interview/SKILL.md b/skills/system-design-interview/SKILL.md index 496cedb..e2c74e9 100644 --- a/skills/system-design-interview/SKILL.md +++ b/skills/system-design-interview/SKILL.md @@ -126,3 +126,10 @@ Things to tackle in production but out of scope for this design session: - [ ] At least 2 component deep-dives with technology choices justified - [ ] Trade-offs section is honest (not just benefits of chosen approach) - [ ] Data flow is described end-to-end for the critical path + +## Usage Examples +- "Help me answer a system design interview: [question]" +- "Design [system] for a system design interview" +- "How would I architect [system] at scale?" +- "I have a system design interview — the question is [X]" +- "Design a [URL shortener / chat system / notification service / feed]" diff --git a/skills/test-strategy-doc/SKILL.md b/skills/test-strategy-doc/SKILL.md index bcfd3dc..d01f9b1 100644 --- a/skills/test-strategy-doc/SKILL.md +++ b/skills/test-strategy-doc/SKILL.md @@ -118,3 +118,10 @@ Testing is complete when: - [ ] P0 test cases cover the highest-risk paths specifically - [ ] Each test type names a concrete tool (not "some testing framework") - [ ] Definition of Done is measurable (not "tests are done when QA is happy") + +## Usage Examples +- "Write a test strategy for [feature]" + [paste spec or PRD] +- "Create a test plan for [system]" +- "How should we test [feature]?" +- "I need a QA plan for this sprint" +- "What tests do we need for [X]?" From 49137bd1b686820c560b18def34070f7f9730012 Mon Sep 17 00:00:00 2001 From: mohitagw15856 Date: Wed, 20 May 2026 08:00:55 +0000 Subject: [PATCH 3/4] Content quality improvements to 7 engineering skills (partial batch) Applies reviewer-feedback-driven improvements across 7 skills: - code-review-checklist: add Section 1 header, optional diff input, precise review time estimate, stronger quality checks - debugging-log-analyser: improve Context input, add Frequency input, add Section 1 Error Classification header, stronger quality checks - changelog-generator: add Previous Version Behaviour + Scope inputs, clarify Formatting Rules are skill-internal, stronger quality checks - pr-description-writer: add Target Branch + Linked Issue inputs, fix Screenshots omission instruction, stronger quality checks - test-strategy-doc: split Existing Coverage from Tech Stack, add Deployment Cadence input, fix Performance Tests conditional, stronger quality checks - runbook-writer: add Monitoring Tools + Key Environment Details inputs, fix Last Updated placeholder, stronger quality checks - incident-postmortem: add Responders + Customer Communications inputs Both skills/ and plugins/pm-engineering/skills/ copies updated. https://claude.ai/code/session_01C3HwChrccJd145vJ6Z7ajF --- .../pm-engineering/skills/changelog-generator/SKILL.md | 9 ++++++++- .../pm-engineering/skills/code-review-checklist/SKILL.md | 7 +++++-- .../skills/debugging-log-analyser/SKILL.md | 7 +++++-- .../pm-engineering/skills/incident-postmortem/SKILL.md | 2 ++ .../pm-engineering/skills/pr-description-writer/SKILL.md | 4 +++- plugins/pm-engineering/skills/runbook-writer/SKILL.md | 7 +++++-- plugins/pm-engineering/skills/test-strategy-doc/SKILL.md | 9 ++++++--- skills/changelog-generator/SKILL.md | 9 ++++++++- skills/code-review-checklist/SKILL.md | 7 +++++-- skills/debugging-log-analyser/SKILL.md | 7 +++++-- skills/incident-postmortem/SKILL.md | 2 ++ skills/pr-description-writer/SKILL.md | 4 +++- skills/runbook-writer/SKILL.md | 7 +++++-- skills/test-strategy-doc/SKILL.md | 9 ++++++--- 14 files changed, 68 insertions(+), 22 deletions(-) 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") From 01c10eb625640f12b8de44eefb8b8d65c1a7dd15 Mon Sep 17 00:00:00 2001 From: mohitagw15856 Date: Wed, 20 May 2026 08:02:16 +0000 Subject: [PATCH 4/4] Content quality improvements to remaining 5 engineering skills Completes the quality pass across all 10 skills: - incident-postmortem: fix opening paragraph (blameless framing emphasis), add root cause circular check + action item specificity quality checks - pr-description-writer: add title format quality check, fix risk-appropriate reviewer guidance quality check - system-design-interview: rewrite architecture diagram instruction (system-specific not generic template), fix capacity estimates to show arithmetic, add trade-offs non-empty check - api-docs-writer: add API Version + Rate Limits inputs, clarify output format options, add error codes completeness check, fix code examples check - architecture-decision-record: add ADR Number + Team Context inputs, fix Implementation Notes + Review Date guidance, fix quality checks for context specificity and rejected option reasoning Both skills/ and plugins/pm-engineering/skills/ copies updated. https://claude.ai/code/session_01C3HwChrccJd145vJ6Z7ajF --- .../pm-engineering/skills/api-docs-writer/SKILL.md | 7 +++++-- .../skills/architecture-decision-record/SKILL.md | 9 ++++++--- .../skills/incident-postmortem/SKILL.md | 4 +++- .../skills/pr-description-writer/SKILL.md | 3 ++- .../skills/system-design-interview/SKILL.md | 12 +++++------- skills/api-docs-writer/SKILL.md | 7 +++++-- skills/architecture-decision-record/SKILL.md | 9 ++++++--- skills/incident-postmortem/SKILL.md | 4 +++- skills/pr-description-writer/SKILL.md | 3 ++- skills/system-design-interview/SKILL.md | 12 +++++------- 10 files changed, 42 insertions(+), 28 deletions(-) diff --git a/plugins/pm-engineering/skills/api-docs-writer/SKILL.md b/plugins/pm-engineering/skills/api-docs-writer/SKILL.md index 8953450..8cdb932 100644 --- a/plugins/pm-engineering/skills/api-docs-writer/SKILL.md +++ b/plugins/pm-engineering/skills/api-docs-writer/SKILL.md @@ -13,8 +13,10 @@ 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 / OpenAPI YAML / Plain prose) +- **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 @@ -133,7 +135,8 @@ data = response.json() - [ ] Every parameter is documented (type, required/optional, description) - [ ] Response fields are fully documented with types - [ ] All relevant error codes are listed with resolution guidance -- [ ] Code examples are copy-paste runnable (no pseudocode) +- [ ] 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 diff --git a/plugins/pm-engineering/skills/architecture-decision-record/SKILL.md b/plugins/pm-engineering/skills/architecture-decision-record/SKILL.md index e0e3d71..25f4dbd 100644 --- a/plugins/pm-engineering/skills/architecture-decision-record/SKILL.md +++ b/plugins/pm-engineering/skills/architecture-decision-record/SKILL.md @@ -10,6 +10,7 @@ This skill produces a complete Architecture Decision Record (ADR) following the ## 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) @@ -17,6 +18,7 @@ Ask the user for these if not provided: - **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 @@ -89,13 +91,13 @@ For each option, produce: ## Implementation Notes -[Optional but valuable: any specific patterns, gotchas, or guidance for the team implementing based on this decision. Link to relevant tickets, RFCs, or design docs if applicable.] +[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 -[Optional: "This decision should be reviewed if [condition] — e.g. team grows beyond 20 engineers, or traffic exceeds 10M requests/day."] +[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".] --- @@ -107,7 +109,8 @@ For each option, produce: - [ ] 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 -- [ ] Written for someone with no prior context on 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]" diff --git a/plugins/pm-engineering/skills/incident-postmortem/SKILL.md b/plugins/pm-engineering/skills/incident-postmortem/SKILL.md index 6396a5f..1b060a6 100644 --- a/plugins/pm-engineering/skills/incident-postmortem/SKILL.md +++ b/plugins/pm-engineering/skills/incident-postmortem/SKILL.md @@ -5,7 +5,7 @@ description: "Write a structured incident postmortem or post-incident review. Us # Incident Postmortem Skill -This skill produces a complete, blameless incident postmortem document following industry-standard format. Output is ready to share with engineering teams, leadership, and affected stakeholders. +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 @@ -133,9 +133,11 @@ Rules for action items: - [ ] 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 diff --git a/plugins/pm-engineering/skills/pr-description-writer/SKILL.md b/plugins/pm-engineering/skills/pr-description-writer/SKILL.md index 70796b5..19ee525 100644 --- a/plugins/pm-engineering/skills/pr-description-writer/SKILL.md +++ b/plugins/pm-engineering/skills/pr-description-writer/SKILL.md @@ -78,8 +78,9 @@ Flag anything that warrants extra attention: - [ ] Title is imperative mood and under 72 characters - [ ] Summary explains what AND why (not just what) - [ ] Changes list describes logical changes (not file-by-file changes) +- [ ] Title starts with a valid type prefix (feat / fix / refactor / chore / deps / config / hotfix) and is under 72 characters - [ ] Testing steps are reproducible by someone unfamiliar with the code -- [ ] Risk-appropriate reviewer guidance is included +- [ ] For high-risk PRs, Reviewer Notes flags at least one specific area of concern or deliberate trade-off; for low-risk PRs, Reviewer Notes is either omitted or kept to one line ## Usage Examples - "Write a PR description for these changes" + [paste diff or description] diff --git a/plugins/pm-engineering/skills/system-design-interview/SKILL.md b/plugins/pm-engineering/skills/system-design-interview/SKILL.md index e2c74e9..5c83362 100644 --- a/plugins/pm-engineering/skills/system-design-interview/SKILL.md +++ b/plugins/pm-engineering/skills/system-design-interview/SKILL.md @@ -14,6 +14,8 @@ Ask for these if not provided: - **Scope** (interview prep / real architecture decision / practice run) - **Scale target** (rough numbers: DAU, requests/sec, data volume — or "assume typical web scale") - **Constraints or priorities** (e.g. prioritise availability over consistency, minimise cost, low-latency reads) +- **Time available** (interview context only: 30 / 45 / 60 minutes — skip for real architecture sessions) +- **Emphasis** (optional — any area to go deeper on, e.g. "focus on the DB design" or "spend more time on scaling") ## Output Format @@ -62,12 +64,7 @@ Then proceed with stated assumptions if answering an interview question. ### 5. High-Level Architecture -``` -[Client] → [CDN/Edge] → [Load Balancer] → [API Servers] → [Cache] → [DB] - → [Message Queue] → [Workers] -``` - -Describe each layer in 1–2 sentences explaining its role and technology choice. +Draw an ASCII diagram specific to this system. Do not default to the client→CDN→LB→API→Cache→DB template unless it genuinely applies. Label each component with the specific technology chosen (e.g. "Kafka" not "Message Queue", "PostgreSQL" not "DB"). Describe each component in 1–2 sentences explaining its role and why that technology was chosen. ### 6. Component Deep-Dive @@ -122,7 +119,8 @@ Things to tackle in production but out of scope for this design session: ## Quality Checks - [ ] Clarifying questions are design-changing (not generic filler) -- [ ] Capacity estimates use real numbers (not just "it scales") +- [ ] Capacity estimates show the arithmetic: DAU → requests/day → requests/sec → storage per record → total storage, so the numbers can be sanity-checked +- [ ] Every row in the Trade-offs table has a non-empty Trade-off column (no rows where the trade-off is blank or says "none") - [ ] At least 2 component deep-dives with technology choices justified - [ ] Trade-offs section is honest (not just benefits of chosen approach) - [ ] Data flow is described end-to-end for the critical path diff --git a/skills/api-docs-writer/SKILL.md b/skills/api-docs-writer/SKILL.md index 8953450..8cdb932 100644 --- a/skills/api-docs-writer/SKILL.md +++ b/skills/api-docs-writer/SKILL.md @@ -13,8 +13,10 @@ 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 / OpenAPI YAML / Plain prose) +- **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 @@ -133,7 +135,8 @@ data = response.json() - [ ] Every parameter is documented (type, required/optional, description) - [ ] Response fields are fully documented with types - [ ] All relevant error codes are listed with resolution guidance -- [ ] Code examples are copy-paste runnable (no pseudocode) +- [ ] 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 diff --git a/skills/architecture-decision-record/SKILL.md b/skills/architecture-decision-record/SKILL.md index e0e3d71..25f4dbd 100644 --- a/skills/architecture-decision-record/SKILL.md +++ b/skills/architecture-decision-record/SKILL.md @@ -10,6 +10,7 @@ This skill produces a complete Architecture Decision Record (ADR) following the ## 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) @@ -17,6 +18,7 @@ Ask the user for these if not provided: - **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 @@ -89,13 +91,13 @@ For each option, produce: ## Implementation Notes -[Optional but valuable: any specific patterns, gotchas, or guidance for the team implementing based on this decision. Link to relevant tickets, RFCs, or design docs if applicable.] +[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 -[Optional: "This decision should be reviewed if [condition] — e.g. team grows beyond 20 engineers, or traffic exceeds 10M requests/day."] +[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".] --- @@ -107,7 +109,8 @@ For each option, produce: - [ ] 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 -- [ ] Written for someone with no prior context on 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]" diff --git a/skills/incident-postmortem/SKILL.md b/skills/incident-postmortem/SKILL.md index 6396a5f..1b060a6 100644 --- a/skills/incident-postmortem/SKILL.md +++ b/skills/incident-postmortem/SKILL.md @@ -5,7 +5,7 @@ description: "Write a structured incident postmortem or post-incident review. Us # Incident Postmortem Skill -This skill produces a complete, blameless incident postmortem document following industry-standard format. Output is ready to share with engineering teams, leadership, and affected stakeholders. +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 @@ -133,9 +133,11 @@ Rules for action items: - [ ] 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 diff --git a/skills/pr-description-writer/SKILL.md b/skills/pr-description-writer/SKILL.md index 70796b5..19ee525 100644 --- a/skills/pr-description-writer/SKILL.md +++ b/skills/pr-description-writer/SKILL.md @@ -78,8 +78,9 @@ Flag anything that warrants extra attention: - [ ] Title is imperative mood and under 72 characters - [ ] Summary explains what AND why (not just what) - [ ] Changes list describes logical changes (not file-by-file changes) +- [ ] Title starts with a valid type prefix (feat / fix / refactor / chore / deps / config / hotfix) and is under 72 characters - [ ] Testing steps are reproducible by someone unfamiliar with the code -- [ ] Risk-appropriate reviewer guidance is included +- [ ] For high-risk PRs, Reviewer Notes flags at least one specific area of concern or deliberate trade-off; for low-risk PRs, Reviewer Notes is either omitted or kept to one line ## Usage Examples - "Write a PR description for these changes" + [paste diff or description] diff --git a/skills/system-design-interview/SKILL.md b/skills/system-design-interview/SKILL.md index e2c74e9..5c83362 100644 --- a/skills/system-design-interview/SKILL.md +++ b/skills/system-design-interview/SKILL.md @@ -14,6 +14,8 @@ Ask for these if not provided: - **Scope** (interview prep / real architecture decision / practice run) - **Scale target** (rough numbers: DAU, requests/sec, data volume — or "assume typical web scale") - **Constraints or priorities** (e.g. prioritise availability over consistency, minimise cost, low-latency reads) +- **Time available** (interview context only: 30 / 45 / 60 minutes — skip for real architecture sessions) +- **Emphasis** (optional — any area to go deeper on, e.g. "focus on the DB design" or "spend more time on scaling") ## Output Format @@ -62,12 +64,7 @@ Then proceed with stated assumptions if answering an interview question. ### 5. High-Level Architecture -``` -[Client] → [CDN/Edge] → [Load Balancer] → [API Servers] → [Cache] → [DB] - → [Message Queue] → [Workers] -``` - -Describe each layer in 1–2 sentences explaining its role and technology choice. +Draw an ASCII diagram specific to this system. Do not default to the client→CDN→LB→API→Cache→DB template unless it genuinely applies. Label each component with the specific technology chosen (e.g. "Kafka" not "Message Queue", "PostgreSQL" not "DB"). Describe each component in 1–2 sentences explaining its role and why that technology was chosen. ### 6. Component Deep-Dive @@ -122,7 +119,8 @@ Things to tackle in production but out of scope for this design session: ## Quality Checks - [ ] Clarifying questions are design-changing (not generic filler) -- [ ] Capacity estimates use real numbers (not just "it scales") +- [ ] Capacity estimates show the arithmetic: DAU → requests/day → requests/sec → storage per record → total storage, so the numbers can be sanity-checked +- [ ] Every row in the Trade-offs table has a non-empty Trade-off column (no rows where the trade-off is blank or says "none") - [ ] At least 2 component deep-dives with technology choices justified - [ ] Trade-offs section is honest (not just benefits of chosen approach) - [ ] Data flow is described end-to-end for the critical path