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
This commit is contained in:
mohitagw15856
Claude
@@ -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
|
||||
|
||||
@@ -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]"
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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]
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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]"
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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]
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user