fix(plugins): sync all 171 plugin SKILL.md files with fixed skills/ versions
Propagates Anti-Patterns sections, description rewrites, Required Inputs additions, and Quality Checks format fixes from skills/ to matching plugin SKILL.md copies. https://claude.ai/code/session_01MuGKn3a3Gbqoe8uM5Lmuqt
This commit is contained in:
Mohit
@@ -141,6 +141,14 @@ data = response.json()
|
||||
- [ ] Enum values are listed where applicable
|
||||
- [ ] Pagination documented if the endpoint is a list endpoint
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- [ ] Do not document only the happy path — every endpoint must have error codes for at least 400, 401/403, 404, 429, and 500
|
||||
- [ ] Do not use placeholder values like "YOUR_ENDPOINT" or "INSERT_TOKEN" in code examples — use realistic-looking placeholders anchored to the actual base URL
|
||||
- [ ] Do not skip enum values for fields with a fixed set of accepted values — undocumented enums cause integration bugs
|
||||
- [ ] Do not omit pagination documentation on list endpoints — developers who miss this will build integrations that silently miss data
|
||||
- [ ] Do not describe what a field "is" without describing what it "does" — "the ID" is not documentation; "the unique identifier used to retrieve or update this resource" is
|
||||
|
||||
## Usage Examples
|
||||
- "Document this API endpoint: [paste spec or description]"
|
||||
- "Turn this Postman collection into developer docs"
|
||||
|
||||
@@ -301,6 +301,14 @@ builders and response parsers.
|
||||
- [ ] Do not set a sunset date without confirming it is achievable for the largest consumer — a sunset that forces consumers to miss a legal deadline will be ignored or escalated
|
||||
- [ ] Do not maintain more than two simultaneous stable/deprecated versions — each additional supported version multiplies maintenance burden and consumer confusion
|
||||
- [ ] Do not use "monitor traffic" as the sole mechanism for knowing when all consumers have migrated — track named consumers against migration completion explicitly
|
||||
- [ ] Do not skip the migration guide — consumers will delay migration indefinitely without a step-by-step guide that estimates effort
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Versioning scheme recommendation includes explicit rationale tied to the API type and consumer type provided — not a generic recommendation
|
||||
- [ ] Breaking-change table covers at minimum: field removal, field rename, type change, making optional field required, endpoint removal, enum expansion, and default value change
|
||||
- [ ] Deprecation timeline durations are filled in with concrete values, not left as abstract placeholders
|
||||
- [ ] All three communication artifacts are present: initial deprecation notice, 30-day warning, and migration guide template
|
||||
- [ ] Sunset response headers (`Deprecation`, `Sunset`, `Link`) use correct RFC date format and real URL structure
|
||||
- [ ] SDK versioning alignment table is present and ties SDK major versions explicitly to API major versions
|
||||
- [ ] Maximum simultaneous supported versions is stated with a concrete number
|
||||
|
||||
@@ -112,6 +112,14 @@ For each option, produce:
|
||||
- [ ] 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")
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- [ ] Do not write an ADR after the decision has already been fully implemented and the team has moved on — ADRs written retrospectively often omit the real reasons and alternatives
|
||||
- [ ] Do not list only the chosen option — rejected options with honest reasons are the most valuable part of an ADR for future readers
|
||||
- [ ] Do not write consequences that are all positive — every architectural decision involves trade-offs; an ADR with no negative consequences was not scrutinised honestly
|
||||
- [ ] Do not leave the status as "Proposed" indefinitely — an ADR that no one has approved is not guiding anyone's decisions
|
||||
- [ ] Do not write context that assumes the reader already knows what problem was being solved — the context section exists precisely for readers who lack that background
|
||||
|
||||
## Usage Examples
|
||||
- "Write an ADR for using [technology]"
|
||||
- "Document our decision to [architectural choice]"
|
||||
|
||||
@@ -346,6 +346,14 @@ Define the thresholds that require explicit action — not retrospective fixes a
|
||||
|
||||
---
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- [ ] Do not set capacity trigger thresholds without knowing the baseline — a "CPU > 70%" alert is meaningless if you don't know what normal looks like
|
||||
- [ ] Do not plan only for average traffic — capacity plans that don't model peak load will result in incidents during the events that matter most
|
||||
- [ ] Do not conflate vertical and horizontal scaling — adding more app servers without addressing database connection limits will not resolve the constraint
|
||||
- [ ] Do not present growth projections as certainties — all forecasts have uncertainty; state the confidence level and provide a conservative and optimistic scenario
|
||||
- [ ] Do not defer action items without a named owner and a specific date — a roadmap with no owners is a wish list
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Every resource has a quantified current utilisation and a projected months-to-ceiling — no hand-waving
|
||||
|
||||
@@ -81,6 +81,14 @@ Follow [Keep a Changelog](https://keepachangelog.com) format:
|
||||
- [ ] 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")
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- [ ] Do not include implementation details in changelog entries — users need to know what changed for them, not how the code was refactored internally
|
||||
- [ ] Do not list every micro-commit as a separate entry — related commits should be grouped into one user-facing change
|
||||
- [ ] Do not omit the migration path for breaking changes — a breaking change entry without a specific migration action forces users to read the source code
|
||||
- [ ] Do not include empty sections — a "### Fixed" section with no entries signals the template was filled in carelessly
|
||||
- [ ] Do not write breaking changes in the same casual tone as minor additions — breaking changes must be visually prominent and call out migration requirements explicitly
|
||||
|
||||
## Usage Examples
|
||||
- "Write a changelog for version [X]" + [paste commits]
|
||||
- "Generate release notes from these commits"
|
||||
|
||||
@@ -292,6 +292,14 @@ Ask for these if not already provided:
|
||||
|
||||
---
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- [ ] Do not describe a rollback procedure that has never been tested — a theoretical rollback is not a rollback plan; test it in staging before production
|
||||
- [ ] Do not allow deploys on Fridays or before holidays without an explicit on-call engineer who will monitor through the weekend
|
||||
- [ ] Do not commit secrets to source control even in non-production branches — secret scanning in the pipeline catches this, but prevention is the standard
|
||||
- [ ] Do not skip post-deploy monitoring after a production deploy — the deploying engineer must watch error rates and latency for the specified observation window
|
||||
- [ ] Do not suppress a security scan finding without a linked ticket and a named owner — suppressions without accountability accumulate into unmanaged risk
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Every stage has a clear owner when it fails
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: claude-superpowers
|
||||
description: "Force Claude Code to work like a senior developer: plan before coding, work in isolation, write tests first, and review its own output twice before presenting it. Use when asked to enable superpowers mode, activate the superpowers framework, or turn on superpowers for this session. Installs a 4-stage framework — Plan, Isolate, Test First, Double Review — that prevents Claude from sprinting into broken code."
|
||||
description: "Activate a 4-stage coding discipline framework that forces Claude to plan before coding, isolate changes on a branch, write tests first, and self-review output twice before presenting it. Use when starting a complex coding task, when past Claude sessions produced broken first drafts, or when you want to prevent rework cycles. Produces a confirmed written plan, isolated feature branch, test-first implementation, and a double-reviewed output with a correctness and code-quality checklist."
|
||||
---
|
||||
|
||||
# Claude Superpowers Skill
|
||||
@@ -269,6 +269,14 @@ Tell the user: "Add this to your CLAUDE.md and Superpowers will be active perman
|
||||
|
||||
---
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- [ ] Do not proceed to Stage 2 without explicit user confirmation of the plan — coding before confirmation defeats the entire purpose of the planning stage
|
||||
- [ ] Do not write tests after the implementation and call it "test-first" — tests must be written and confirmed failing before the implementation starts
|
||||
- [ ] Do not skip the Double Review when time is tight — the review is most valuable precisely when speed is the priority, because that is when errors are most likely
|
||||
- [ ] Do not expand scope during Stage 2 without surfacing it — silent scope expansion produces code the user did not approve and may not want
|
||||
- [ ] Do not mark both reviews as clean without actually performing them — a rubber-stamp review produces false confidence and defeats the framework
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Enable superpowers mode"
|
||||
|
||||
@@ -107,6 +107,14 @@ Based on the change type and language, flag 2-3 things reviewers typically miss
|
||||
- [ ] 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")
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- [ ] Do not generate a generic checklist that ignores the stated language — a Python checklist and a Go checklist have fundamentally different correctness concerns
|
||||
- [ ] Do not treat "looks fine" as a valid review outcome — the checklist exists to surface specific concerns, not validate a superficial read
|
||||
- [ ] Do not scope a "high risk" review the same as a "low risk" review — depth must scale with the stated risk level
|
||||
- [ ] Do not flag every stylistic preference as a blocking issue — distinguish between blocking correctness issues and non-blocking comments
|
||||
- [ ] Do not skip the "common pitfalls" section for the stated language and change-type combination — this is where the most valuable knowledge lives
|
||||
|
||||
## Usage Examples
|
||||
- "Generate a code review checklist for [PR description]"
|
||||
- "What should I check in this pull request?"
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: context-mode
|
||||
description: "Activate output filtering, session logging, and auto-resume to keep Claude Code sessions running for hours without context bloat or memory loss. Use when asked to enable context mode, turn on long session mode, or activate session persistence. Installs a session log at project root, filters verbose command output before it enters context, and auto-resumes after Claude resets."
|
||||
description: "Activate output filtering, session logging, and auto-resume to keep Claude Code sessions productive across resets. Use when starting a long or complex coding session, when previous sessions lost context mid-task, or when you need Claude to resume exactly where it left off after a reset. Installs a session.log at project root, filters verbose command output to preserve context, and automatically resumes in-progress tasks after any Claude reset."
|
||||
---
|
||||
|
||||
# Context Mode Skill
|
||||
|
||||
@@ -452,3 +452,11 @@ Follow this checklist on the day of migration. Mark each step as done before pro
|
||||
- [ ] Lock types are identified for every DDL statement — no "should be fine" assumptions
|
||||
- [ ] The deployment runbook names who runs each step, not just what to run
|
||||
- [ ] Phase 4 (contract) is explicitly gated on the rollback window passing — not run on the same day as Phase 3
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- [ ] Do not combine the expand and contract phases into a single deployment — they must be separated by a deployment cycle
|
||||
- [ ] Do not run DDL changes without first testing on a production-sized data clone
|
||||
- [ ] Do not skip the NOT VALID + VALIDATE pattern for constraint additions on large tables — it causes full table locks
|
||||
- [ ] Do not define a rollback as "restore from backup" — each phase must have an explicit, fast rollback procedure
|
||||
- [ ] Do not omit dual-write logic during the transition period — removing the old column before all writers are updated causes data loss
|
||||
|
||||
@@ -354,3 +354,11 @@ If this schema is being introduced to an existing system, note the migration app
|
||||
- [ ] JSONB columns are justified — not used as a substitute for proper schema design on queryable fields
|
||||
- [ ] Normalization decisions are documented with reasoning, not just stated
|
||||
- [ ] Migration notes address existing data if this is a schema change, not a greenfield schema
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- [ ] Do not use JSONB columns as a substitute for proper relational schema design on fields that will be queried
|
||||
- [ ] Do not add indexes speculatively — every index must be justified by a specific access pattern
|
||||
- [ ] Do not omit timezone-awareness — use TIMESTAMPTZ, never plain TIMESTAMP
|
||||
- [ ] Do not design without documenting normalization decisions — future maintainers need the reasoning, not just the structure
|
||||
- [ ] Do not skip the access patterns section — schema without query patterns cannot be evaluated for correctness
|
||||
|
||||
@@ -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."
|
||||
description: "Parse error logs, stack traces, and crash reports into a structured root cause diagnosis. Use when an application is throwing exceptions, crashing, or producing unexpected errors and you need to understand why and what to fix. Produces a structured diagnosis with error classification, stack trace walkthrough, probable root cause with confidence level, affected code path, a concrete code-level fix suggestion, and ordered next debugging steps."
|
||||
---
|
||||
|
||||
# Debugging Log Analyser Skill
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: dependency-audit
|
||||
description: "Conduct a dependency audit for a project — checking for security vulnerabilities, license compliance issues, outdated packages, and transitive dependency risk. Use when asked to audit dependencies, review package security, check license compliance, assess dependency health, or produce a vulnerability report. Produces a vulnerability findings table, license compliance matrix, update priority matrix, dependency health score, and 30-day remediation plan."
|
||||
description: "Audits project dependencies for security vulnerabilities, license compliance issues, outdated packages, and transitive dependency risk. Use when asked to audit dependencies, review package security, check license compliance, assess dependency health, or produce a vulnerability report. Produces a vulnerability findings table, license compliance matrix, update priority matrix, dependency health score, and 30-day remediation plan."
|
||||
---
|
||||
|
||||
# Dependency Audit Skill
|
||||
@@ -330,3 +330,11 @@ go-licenses check ./... --allowed_licenses=MIT,Apache-2.0,BSD-2-Clause,BSD-3-Cla
|
||||
- [ ] CI pipeline change is included — the audit findings should be the last time these are caught manually
|
||||
- [ ] The dependency health score is calculated from actual findings, not estimated
|
||||
- [ ] Remediation plan actions are specific commands or steps, not "upgrade package X" without version targets
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- [ ] Do not report only direct dependencies — transitive dependency vulnerabilities are often more dangerous and are the most commonly missed
|
||||
- [ ] Do not present raw audit tool output without interpretation — a table of 200 CVEs with no prioritisation is worse than no audit at all
|
||||
- [ ] Do not assign all Critical CVEs as "fix immediately" without checking whether an exploitable path exists in your usage context
|
||||
- [ ] Do not make license compliance decisions without legal input — flagging a GPL dependency without a recommendation is incomplete work
|
||||
- [ ] Do not complete the audit without including a CI/CD pipeline step — a one-time audit that leaves the door open for new vulnerabilities is not a remediation
|
||||
|
||||
@@ -330,3 +330,11 @@ curl http://localhost:[PORT]/health
|
||||
- [ ] On-call section has real links, not placeholders
|
||||
- [ ] Contacts are current — team members with real Slack handles
|
||||
- [ ] Troubleshooting covers the top 3 actual questions new joiners ask
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- [ ] Do not document the ideal setup — document the actual setup; real oddities and gotchas are what new engineers need most
|
||||
- [ ] Do not leave placeholder contacts like "ask your manager" — name specific people for each domain or the doc becomes useless when the new joiner has an urgent question
|
||||
- [ ] Do not write the onboarding doc without reviewing it with a recent joiner — the author is blind to what they take for granted
|
||||
- [ ] Do not include every piece of architectural detail — an onboarding doc that covers everything teaches nothing; link to deeper docs instead
|
||||
- [ ] Do not skip the "things that might surprise you" section — undocumented non-obvious patterns are the number one cause of wasted engineering time in the first week
|
||||
|
||||
@@ -558,3 +558,11 @@ Run this checklist quarterly and before any major infrastructure change:
|
||||
- [ ] Contact list contains current phone numbers, not just Slack handles (Slack may be down during a DR event)
|
||||
- [ ] Security breach runbook (3.5) explicitly names the security team contact and does not attempt self-remediation
|
||||
- [ ] All thresholds (RTO/RPO) are visible in the monitoring dashboard so actual vs. target is measurable in real time
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- [ ] Do not write runbook commands without testing them — an untested command in a runbook is actively dangerous during a real disaster when cognitive load is highest
|
||||
- [ ] Do not set RTO/RPO targets without business sign-off — technical teams often set aspirational targets that do not reflect actual business cost tolerance for downtime
|
||||
- [ ] Do not include only the "happy path" of each failover scenario — runbooks must explicitly cover what to do when the recovery step itself fails
|
||||
- [ ] Do not list Slack handles as the only escalation contact — Slack may be unavailable during a region-wide failure; phone numbers are mandatory
|
||||
- [ ] Do not schedule DR game days without pre-committing to fix the gaps found — a game day that produces action items no one owns is theater, not preparedness
|
||||
|
||||
@@ -336,3 +336,11 @@ Brief every interviewer on these before they conduct their first interview for t
|
||||
- [ ] Scorecard uses observable behavior fields ("What did the candidate do or say") — not impression fields
|
||||
- [ ] Must-hire competencies are explicitly named for the role and level
|
||||
- [ ] Debrief agenda enforces written scorecard submission before verbal discussion to prevent anchoring
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- [ ] Do not use a single behavioral anchor description per competency — you must define what Strong Hire AND No Hire look like separately, or interviewers cannot calibrate
|
||||
- [ ] Do not allow "culture fit" as a standalone assessment dimension — it masks similarity bias; all judgments must use observable behavioral evidence
|
||||
- [ ] Do not let interviewers share scorecard feedback before the debrief — verbal pre-debrief discussion anchors everyone to the first opinion expressed
|
||||
- [ ] Do not set the same must-hire competency list for all engineering roles — a senior backend engineer and a frontend engineer have different non-negotiable competencies
|
||||
- [ ] Do not skip the calibration bias notes section — interviewers who have never been briefed on halo effect, recency bias, and credential bias will reproduce them in every loop
|
||||
|
||||
@@ -162,3 +162,11 @@ If no decisions are pending: *No decisions pending.*
|
||||
- [ ] Escalations that need leadership attention are called out explicitly in the Risks section — not just buried in a table row
|
||||
- [ ] The entire report is readable in under 2 minutes — if it is longer than one printed page, trim it
|
||||
- [ ] Report period (week number and date range) is clearly stated in the header
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- [ ] Do not fabricate metrics — if data is not available, mark the field as `[data needed]` rather than estimating; stakeholders making decisions on invented numbers is actively harmful
|
||||
- [ ] Do not write next week's priorities as activities ("work on X") — they must be outcomes ("ship X", "complete Y migration") so stakeholders can evaluate whether the team delivered
|
||||
- [ ] Do not bury escalations inside a risk table row — anything needing leadership attention must be called out explicitly in the Escalations section
|
||||
- [ ] Do not list blocked items without naming a specific owner and a concrete unblocking action — "waiting on X" is not a blocker entry, it is a placeholder
|
||||
- [ ] Do not write a report that exceeds two printed pages — length signals the author has not done the editorial work of deciding what matters to stakeholders
|
||||
|
||||
@@ -367,3 +367,11 @@ All flag changes in production must be traceable. Ensure the following are confi
|
||||
- [ ] Stale flag detection runs automatically and results are reviewed weekly
|
||||
- [ ] Code review checklist includes: "Does this PR introduce a flag? If yes, is the creation checklist complete?"
|
||||
- [ ] At least one person other than the flag owner knows how to disable any given flag in an emergency
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- [ ] Do not create release flags without a cleanup date — flags without expiry dates become permanent technical debt that accumulates silently until the codebase is unmaintainable
|
||||
- [ ] Do not skip monitoring setup for flags between 1–99% rollout — a partially-rolled-out flag without metric comparison is a risk without a sensor
|
||||
- [ ] Do not nest flags inside other flags — compound flag logic makes cleanup nearly impossible and creates untestable code paths
|
||||
- [ ] Do not allow flag owners to leave the team without reassigning ownership — orphan flags with no owner never get cleaned up
|
||||
- [ ] Do not use feature flags as a permanent configuration system — flags that have been at 100% or 0% for more than 30 days must be cleaned up; using flags as permanent config couples business logic to a feature flag platform
|
||||
|
||||
@@ -140,6 +140,14 @@ Rules for action items:
|
||||
- [ ] 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
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- [ ] Do not assign blame to individuals — postmortems must focus on system and process failures
|
||||
- [ ] Do not write action items with vague language like "improve monitoring" — each must name a specific, ownable change
|
||||
- [ ] Do not skip the contributing factors — root cause alone misses the systemic issues that enable incidents
|
||||
- [ ] Do not omit the detection timeline — how long it took to detect matters as much as how long it took to resolve
|
||||
- [ ] Do not treat the postmortem as closed until all action items have named owners and due dates
|
||||
|
||||
## Usage Examples
|
||||
- "Write a postmortem for the [incident name] outage"
|
||||
- "Help me write a P1 incident report"
|
||||
|
||||
@@ -290,3 +290,11 @@ Medium and Low findings should be tracked as follow-up issues with a committed r
|
||||
- [ ] Code snippets in findings show both the problematic code AND the corrected version
|
||||
- [ ] Overall risk rating is justified by the highest-severity open finding
|
||||
- [ ] Checklist items are binary (checkable) — not narrative observations
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- [ ] Do not mark a finding as Low if it involves hardcoded credentials or secrets in any form — always Critical
|
||||
- [ ] Do not review IaC in isolation from the deployment context — networking and IAM must be evaluated together
|
||||
- [ ] Do not produce narrative findings without the specific resource name, file, and line number
|
||||
- [ ] Do not skip the "Required Actions Before Merge" summary — reviewers need a clear blocking list, not just a full report
|
||||
- [ ] Do not approve code where encryption at rest or in transit is missing on data stores, even if not explicitly flagged by the requester
|
||||
|
||||
@@ -430,3 +430,11 @@ load-test:
|
||||
- [ ] CI integration blocks promotion on threshold failure — not just records results
|
||||
- [ ] Soak test has been run at least once to establish a memory and connection pool baseline
|
||||
- [ ] Results comparison to previous run is part of the analysis — not just absolute pass/fail
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- [ ] Do not set thresholds without grounding them in actual SLO targets or production baselines — arbitrary numbers produce meaningless pass/fail results
|
||||
- [ ] Do not run the load generator on the same host as the service under test — this contaminates both the test results and the service metrics
|
||||
- [ ] Do not use production user data in load test seeding — all test data must be synthetic, tagged, and cleaned up after each run
|
||||
- [ ] Do not skip the soak test on first deployment — only a soak test reveals slow memory leaks and connection pool exhaustion that short tests miss
|
||||
- [ ] Do not treat a passing baseline test as evidence the service handles spikes — baseline, stress, spike, and soak scenarios test fundamentally different failure modes
|
||||
|
||||
@@ -482,3 +482,11 @@ Before opening your first pull request, verify:
|
||||
- [ ] Docker Compose version and Docker Desktop memory requirements are stated explicitly
|
||||
- [ ] "Expected output" is shown for key commands so engineers know whether a step succeeded
|
||||
- [ ] Setup time estimate is honest — verified by timing a real onboarding session, not estimated
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- [ ] Do not write setup steps from memory without testing them on a clean machine — steps that skip implicit knowledge break for new engineers
|
||||
- [ ] Do not leave environment variables undocumented — every variable in .env.example must appear in the Variables table with a description and source
|
||||
- [ ] Do not write troubleshooting entries for theoretical issues — only include problems that have actually occurred during real onboarding sessions
|
||||
- [ ] Do not assume Docker Desktop is configured correctly — memory limits and platform (M1/M2) compatibility must be explicitly called out
|
||||
- [ ] Do not omit expected output for key commands — without "expected output", engineers cannot tell whether a step succeeded or silently failed
|
||||
|
||||
@@ -288,3 +288,11 @@ Conway's Law: the architecture of a system mirrors the communication structure o
|
||||
- [ ] If decomposing a monolith, the strangler fig migration plan has phases with durations, dependencies, and success criteria
|
||||
- [ ] Risk register addresses at minimum: data consistency, distributed transactions, and Conway's Law alignment
|
||||
- [ ] Organizational alignment section maps services to teams and identifies misalignments that need to be resolved
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- [ ] Do not define service boundaries before completing the domain analysis — services derived without bounded context mapping will split the wrong things and couple the wrong things
|
||||
- [ ] Do not assign multiple teams as co-owners of a single service — shared ownership is no ownership; every service needs exactly one team accountable for it
|
||||
- [ ] Do not default to synchronous REST calls for all inter-service communication — using sync calls where async events would decouple services creates cascading failure modes
|
||||
- [ ] Do not propose more than one service per bounded context without a clear justification — over-decomposition (nanoservices) creates operational overhead that exceeds the decomposition benefit
|
||||
- [ ] Do not begin migration without deploying distributed tracing first — migrating without observability means flying blind when the first extraction causes a production incident
|
||||
|
||||
@@ -434,3 +434,11 @@ Honest assessment of what is missing today and what the priority to add it is:
|
||||
- [ ] The primary dashboard answers "is the service healthy?" in under 10 seconds — no hunting for the right panel
|
||||
- [ ] Business metrics are tracked alongside infrastructure metrics — not just four golden signals
|
||||
- [ ] Observability debt items have owners and dates — not just "would be nice to have"
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- [ ] Do not create alerts without a specific on-call action — an alert that just says "investigate" trains engineers to ignore it
|
||||
- [ ] Do not set alert thresholds from a template without calibrating against production baselines — uncalibrated thresholds cause either alert fatigue or missed incidents
|
||||
- [ ] Do not log PII, tokens, or secrets — a logging standard is incomplete without an explicit list of what must never be logged
|
||||
- [ ] Do not measure only the four golden signals without adding at least one business metric alert — infrastructure health can be green while the business-critical path is silently failing
|
||||
- [ ] Do not deploy distributed tracing without verifying that trace IDs propagate across all service boundaries — partial tracing is worse than no tracing because it produces misleading incomplete traces
|
||||
|
||||
@@ -362,3 +362,11 @@ ANYTHING ELSE:
|
||||
- [ ] Diagnostic commands work — they have been run by at least one person recently
|
||||
- [ ] Handoff template is used at every shift change — not just during incidents
|
||||
- [ ] "Things I had to figure out that weren't documented" are added to this runbook after every incident
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- [ ] Do not write alert runbooks with vague diagnostic steps like "check the logs" — every step must specify the exact command, dashboard link, or query to run
|
||||
- [ ] Do not include an alert in the runbook that has no specific on-call action — an alert that pages someone with no defined response path creates panic, not resolution
|
||||
- [ ] Do not leave the rollback command undocumented or untested — a rollback procedure that has never been run will fail when needed most
|
||||
- [ ] Do not list escalation contacts without phone numbers and Slack handles — email-only escalation paths are useless during a 3am incident
|
||||
- [ ] Do not write the runbook once and treat it as permanent — runbooks go stale after incidents; every incident must trigger a review of the relevant runbook entries
|
||||
|
||||
@@ -275,3 +275,11 @@ When a breach is detected, work through this checklist in order:
|
||||
- [ ] Budget breach response process names specific Slack channels and owners
|
||||
- [ ] Budget thresholds are anchored to baseline measurements or a justified target — not pulled from thin air
|
||||
- [ ] Per-journey targets are defined for critical user journeys, not just global averages
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- [ ] Do not set budget thresholds without measuring a current baseline first — targets must be anchored to reality
|
||||
- [ ] Do not define global averages only — critical user journeys need individual budgets as they may diverge significantly
|
||||
- [ ] Do not omit CI enforcement — a performance budget that is not enforced in the build pipeline will not be respected
|
||||
- [ ] Do not leave the breach response process without named owners and escalation channels
|
||||
- [ ] Do not set budgets that apply only to one environment — production and staging targets should be documented separately if they differ
|
||||
|
||||
@@ -82,6 +82,14 @@ Flag anything that warrants extra attention:
|
||||
- [ ] Testing steps are reproducible by someone unfamiliar with the code
|
||||
- [ ] 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
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- [ ] Do not write a description that only restates what changed — explain why the change was made
|
||||
- [ ] Do not skip the testing steps — reviewers need to know how to verify the change works
|
||||
- [ ] Do not omit the reviewer notes for high-risk PRs — flag deliberate trade-offs and areas needing careful review
|
||||
- [ ] Do not describe implementation details that are obvious from the diff — add context that the diff cannot convey
|
||||
- [ ] Do not produce a single paragraph — structure with headers so reviewers can navigate to what they need
|
||||
|
||||
## Usage Examples
|
||||
- "Write a PR description for these changes" + [paste diff or description]
|
||||
- "Draft a pull request for [feature]"
|
||||
|
||||
@@ -397,3 +397,11 @@ Accept the current state and revisit the problem in [timeframe].
|
||||
- [ ] Open questions are assigned to named owners with deadlines — not floating
|
||||
- [ ] The RFC is written to be read by someone who was not in the planning conversations
|
||||
- [ ] Migration plan addresses all affected parties — users, API consumers, data — not just the technical steps
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- [ ] Do not write the RFC as a persuasion document — its purpose is to expose trade-offs, not sell a decision
|
||||
- [ ] Do not list alternatives without explicit rejection reasons — "we preferred the proposed solution" is not a reason
|
||||
- [ ] Do not leave the security implications section blank or write "N/A" without a reasoned explanation
|
||||
- [ ] Do not write open questions without assigning a named owner and a resolution deadline
|
||||
- [ ] Do not skip the "impact of not solving this" section — without it, reviewers cannot assess urgency
|
||||
|
||||
@@ -145,3 +145,11 @@ After completing the runbook:
|
||||
- "I need a runbook for [procedure]"
|
||||
- "Document the operational procedure for [X]"
|
||||
- "Write an ops playbook for [scenario]"
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- [ ] Do not write steps as vague actions like "run the deploy script" — every step must include the exact command
|
||||
- [ ] Do not leave the rollback section as a placeholder — a runbook without a tested rollback procedure is incomplete and dangerous
|
||||
- [ ] Do not omit expected output for each step — without it, the on-call engineer cannot tell if the step succeeded
|
||||
- [ ] Do not write escalation contacts as "[Team name]" — every escalation row must have a real contact or an explicit flag to fill in
|
||||
- [ ] Do not assume the reader knows the system — write for someone who has never touched it before
|
||||
|
||||
@@ -251,3 +251,11 @@ Accepted risks are threats the team has decided not to mitigate right now. Every
|
||||
- [ ] STRIDE analysis covers all major components — not just the API layer
|
||||
- [ ] Mitigation actions are specific enough to become a ticket (not "improve security")
|
||||
- [ ] The ASCII trust boundary diagram matches the architecture description provided
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- [ ] Do not restrict STRIDE analysis to only the API layer — threats exist at every component including the database and internal services
|
||||
- [ ] Do not leave mitigations as vague directives like "improve security" — every mitigation must be specific enough to become a ticket
|
||||
- [ ] Do not accept risks without a named owner and a review date — unowned accepted risks are not managed risks
|
||||
- [ ] Do not write a threat model that covers only theoretical threats — prioritise by likelihood and impact using the risk register
|
||||
- [ ] Do not omit the asset register — without knowing what is being protected, the STRIDE analysis has no anchor
|
||||
|
||||
@@ -290,3 +290,11 @@ Document limitations honestly — this section prevents other teams from buildin
|
||||
- [ ] All runbook links are live — not broken references or TODO placeholders
|
||||
- [ ] Data classification includes retention period and encryption status — not just sensitivity level
|
||||
- [ ] The entry has been reviewed by at least one consumer team to confirm it matches their experience of the service
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- [ ] Do not write aspirational SLO targets — targets must be agreed with stakeholders and based on historical data, not copied from a template
|
||||
- [ ] Do not leave runbook links as TODO placeholders — broken or missing links make the catalog entry worse than useless during an incident
|
||||
- [ ] Do not omit the "Known Limitations" section to make the service look better — undisclosed limitations cause incorrect integrations and downstream incidents
|
||||
- [ ] Do not list API error codes without testing them — aspirational error documentation misleads consumers
|
||||
- [ ] Do not write the "What It Does" section with jargon — a new engineer from another team must understand it in under 2 minutes
|
||||
|
||||
@@ -229,3 +229,11 @@ This policy defines what to do with the error budget — both when it's healthy
|
||||
- [ ] Error budget policy has clear triggers and clear actions — not "discuss as a team"
|
||||
- [ ] Burn rate alerts have different windows to catch both fast burns and slow burns
|
||||
- [ ] Exclusions are documented so they don't silently inflate the SLO number
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- [ ] Do not set SLO targets at 100% — this discourages feature development and does not reflect how users experience reliability
|
||||
- [ ] Do not measure internal system metrics as SLIs — SLIs must reflect what users directly experience, not internal CPU or memory
|
||||
- [ ] Do not write an error budget policy with vague triggers — "discuss as a team" is not an actionable policy; triggers must be specific percentages
|
||||
- [ ] Do not base targets on aspirational round numbers — always derive from historical baseline data
|
||||
- [ ] Do not configure only one burn-rate alert window — a single window misses both fast burns and slow burns that exhaust the budget quietly
|
||||
|
||||
@@ -261,3 +261,11 @@ If cycle time data was not provided: *Cycle time data was not included in this a
|
||||
- [ ] Next-sprint capacity forecast uses historical average as the baseline and deducts specific known reducers
|
||||
- [ ] Health diagnosis table uses Red/Yellow/Green with evidence cited in the Evidence column — no unsupported scores
|
||||
- [ ] If metrics are missing (cycle time, blocker log), the report explicitly calls them out as recommended additions
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- [ ] Do not generate the velocity chart from placeholder data — it must reflect the actual sprint data provided
|
||||
- [ ] Do not diagnose trend direction without computing trailing vs leading averages — "it looks like it's declining" is not a diagnosis
|
||||
- [ ] Do not list carry-over as a generic observation — identify root cause categories with counts for the analysis to be actionable
|
||||
- [ ] Do not produce recommendations without a named owner, a start date, and a measurable target
|
||||
- [ ] Do not score health dimensions without citing evidence in the Evidence column — unsupported Red/Yellow/Green scores are not credible
|
||||
|
||||
@@ -125,6 +125,14 @@ Things to tackle in production but out of scope for this design session:
|
||||
- [ ] Trade-offs section is honest (not just benefits of chosen approach)
|
||||
- [ ] Data flow is described end-to-end for the critical path
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- [ ] Do not jump to solutions before clarifying requirements — always establish functional and non-functional requirements first
|
||||
- [ ] Do not present a design without discussing trade-offs — every architecture decision has costs and benefits that must be acknowledged
|
||||
- [ ] Do not use vague capacity estimates — show the actual calculation (QPS, storage bytes, bandwidth) not just "this handles scale"
|
||||
- [ ] Do not design for unlimited scale by default — match the design to the requirements stated
|
||||
- [ ] Do not skip the data model — a system design without entity definitions and data flow is incomplete
|
||||
|
||||
## Usage Examples
|
||||
- "Help me answer a system design interview: [question]"
|
||||
- "Design [system] for a system design interview"
|
||||
|
||||
@@ -288,3 +288,11 @@ This log records every ring movement since the radar's first edition. Use it to
|
||||
- [ ] Maintenance process includes: nomination channel, review cadence, who decides, and ring-change criteria
|
||||
- [ ] Technologies identified as "strategic bets" in the inputs are placed in Adopt (if proven) or Trial (if being rolled out)
|
||||
- [ ] Technologies identified for deprecation are in Hold with a rationale that references the replacement
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- [ ] Do not place a technology in Adopt without evidence it is proven at the team's scale — aspirational placements mislead engineers
|
||||
- [ ] Do not add a blip without a written rationale paragraph — table rows without context are unusable
|
||||
- [ ] Do not create a Hold entry without specifying a concrete migration path or target technology
|
||||
- [ ] Do not skip the maintenance process — a radar with no process for updates becomes stale within two quarters
|
||||
- [ ] Do not omit ring definitions — engineers need to know what they should do in response to each ring, not just what the ring means
|
||||
|
||||
@@ -258,3 +258,11 @@ Items where the cost of remediation currently exceeds the business value, accept
|
||||
- [ ] Accepted/deferred items have a review date and a named owner — no permanently deferred items
|
||||
- [ ] The register distinguishes between debt (deliberate or accumulated shortcuts) and bugs (unintended defects)
|
||||
- [ ] Items are closed as resolved only when acceptance criteria are met — not when the PR is merged
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- [ ] Do not score debt items arbitrarily — priority scores must be calculated using the documented formula
|
||||
- [ ] Do not conflate technical debt (deliberate shortcuts) with bugs (unintended defects) — they require different remediation strategies
|
||||
- [ ] Do not underrate security and dependency items because they feel abstract — score based on actual business impact
|
||||
- [ ] Do not create "permanently deferred" items — every accepted item must have a review date and named owner
|
||||
- [ ] Do not include resolution plans that are vague descriptions — each plan must have specific, ticketable steps
|
||||
|
||||
@@ -122,6 +122,14 @@ Testing is complete when:
|
||||
- [ ] Each test type names a concrete tool (not "some testing framework")
|
||||
- [ ] Definition of Done is measurable (not "tests are done when QA is happy")
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- [ ] Do not write a test strategy without a risk table that drives test priority — generic coverage targets are not a strategy
|
||||
- [ ] Do not leave the "out of scope" section blank — every test strategy must explicitly name what is not being tested and why
|
||||
- [ ] Do not specify test types without naming a concrete tool for each — "some testing framework" is not actionable
|
||||
- [ ] Do not define a Definition of Done that is not measurable — "QA is happy" is not a completion criterion
|
||||
- [ ] Do not create P0 risk areas without corresponding P0 test cases — risk rating must map to test coverage
|
||||
|
||||
## Usage Examples
|
||||
- "Write a test strategy for [feature]" + [paste spec or PRD]
|
||||
- "Create a test plan for [system]"
|
||||
|
||||
Reference in New Issue
Block a user