plugins/pm-engineering/skills/rfc-writer/SKILL.md
Write an engineering RFC (Request for Comments) for a technical decision, architectural change, or significant implementation approach. Use when asked to write an RFC, document a technical proposal, create a design doc, write an architecture decision for review, or produce a technical specification for team feedback. Produces a complete RFC document covering problem statement, motivation, proposed solution, alternatives rejected, implementation plan, migration plan, security and performance implications, observability changes, rollout plan, and open questions.
npx skillsauth add mohitagw15856/pm-claude-skills rfc-writerInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
Produce a complete engineering RFC (Request for Comments) for a technical decision or architectural change. An RFC is a structured proposal document — not a persuasion document. Its purpose is to expose a decision to scrutiny, surface trade-offs, document alternatives considered, and create a permanent record of why a choice was made.
A good RFC makes it possible for someone who wasn't in the room to understand years later why the team built something the way they did.
Ask for these if not already provided:
Author: [Name] | Team: [Team name] Created: [Date] | Last updated: [Date] Status: Draft | In Review | Approved | Rejected | Superseded by RFC-[X] Ticket: [JIRA-XXX] | Slack thread: [#channel link] Review deadline: [Date — when comments should be submitted by]
[2–4 sentences summarising the entire RFC. Should stand alone — someone reading only this should understand what is being proposed, why, and what the main trade-off is. Write this last.]
[Describe the problem being solved. Focus on the problem, not the solution. Be specific and quantified where possible.]
Current state: [Describe how things work today — the existing system, process, or architecture. Include any relevant constraints or limitations.]
Why this is a problem now: [Why is this being addressed now rather than earlier or later? Reference metrics, incidents, product requirements, or scaling thresholds that make this urgent or timely.]
Example of the problem in practice: [A concrete scenario or incident that illustrates the problem. This helps reviewers understand the real-world impact, not just the abstract description.]
// Example: current behaviour that illustrates the problem
[code snippet, log output, or sequence description showing the problem]
Impact of not solving this:
Goals:
Non-goals: (what this RFC explicitly does not address)
Success metrics: | Metric | Current | Target | Measurement method | |---|---|---|---| | [e.g. Onboarding time] | [3 hours] | [<5 minutes] | [Prometheus histogram on onboarding job duration] | | [e.g. Auth latency P99] | [120ms] | [≤50ms] | [Datadog APM] | | [e.g. Engineer setup time] | [4 hours] | [<30 minutes] | [Onboarding survey] |
[Provide the context a reviewer needs to evaluate the proposal. This is not a repeat of the problem statement — it is the surrounding technical and business context.]
Existing system overview: [Describe the relevant parts of the current architecture. Include an ASCII diagram if the relationships between components help understanding.]
[ASCII diagram of current architecture — optional but strongly recommended for architectural RFCs]
┌──────────┐ ┌──────────────┐ ┌──────────────┐
│ Client │────▶│ [Service A] │────▶│ [Service B] │
└──────────┘ └──────────────┘ └──────────────┘
│
▼
┌──────────────┐
│ [Database] │
└──────────────┘
Prior work and related decisions:
Constraints:
[Describe the proposed approach clearly and specifically. Include enough detail that an engineer could begin implementing from this document, but don't write the code — that is for the PR.]
[1–3 paragraphs describing the overall solution. Explain the key idea and why it solves the problem.]
[ASCII diagram of the proposed architecture — what the system looks like after this RFC is implemented]
┌──────────┐ ┌──────────────────┐ ┌──────────────┐
│ Client │────▶│ [New Component] │────▶│ [Service B] │
└──────────┘ └──────────────────┘ └──────────────┘
│ │
▼ ▼
┌──────────────┐ ┌──────────────┐
│ [Store A] │ │ [Store B] │
└──────────────┘ └──────────────┘
[Break the solution into its key components or decisions. For each, explain what it does and why it was designed this way.]
Component / Decision 1: [Name]
[Description of this component — what it does, how it works, why this approach was chosen.]
// Example interface, API contract, or pseudocode (not implementation code)
[Relevant schema, API definition, data flow, or pseudocode]
Component / Decision 2: [Name]
[Description]
Component / Decision 3: [Name]
[Description]
Complete this section if the RFC introduces or modifies any API endpoints, events, or interfaces.
New endpoints / events:
[HTTP method + path or event name]
Request: { ... }
Response: { ... }
Modified endpoints:
[endpoint]: [what changes and why; backward compatibility note]Deprecated endpoints:
[endpoint]: deprecated in favour of [new endpoint] — removal timeline: [date/version]Complete this section if any database schema or data structure changes are required.
[Describe schema changes at a high level. Reference the database-migration-plan skill for detailed migration steps.]
-- Key schema changes (abbreviated — full migration in [link])
[DDL statements for key additions/changes]
Every alternative must include an explicit reason why it was rejected. "We went with the proposed solution" is not a reason.
Description: [What this alternative would involve.]
Pros:
Cons:
Why rejected: [Specific reason — e.g. "Requires 3× the infrastructure cost", "Incompatible with multi-region requirement", "Team has no expertise in this technology and the ramp-up would miss the Q3 deadline"]
Description: [What this alternative would involve.]
Pros:
Cons:
Why rejected: [Specific reason]
Description: Accept the current state and revisit the problem in [timeframe].
Why rejected: [Why deferring is not acceptable — reference the impact of not solving this from Section 1.]
Estimated effort: [X engineer-weeks] | Target completion: [Date / Quarter] Team: [Who is building this — names or roles]
| Phase | Description | Duration | Dependencies | Owner | |---|---|---|---|---| | 1 | [e.g. Core implementation — new component built and tested] | [X weeks] | [None] | [Name] | | 2 | [e.g. Integration — connect new component to existing services] | [X weeks] | [Phase 1 complete] | [Name] | | 3 | [e.g. Rollout — canary deploy, then full rollout] | [X weeks] | [Phase 2 + staging validated] | [Name] | | 4 | [e.g. Cleanup — deprecate old system, remove feature flags] | [X weeks] | [Phase 3 stable for X weeks] | [Name] |
Key milestones:
Complete this section if the RFC requires migrating existing users, data, or API consumers.
Migration strategy: [Big-bang / Phased / Parallel-run / Opt-in]
Who is affected:
orders table require backfilling]Migration steps:
Backward compatibility window: [How long will the old system/API remain available?]
Communication plan:
[Describe the security impact of this change. If there are no security implications, state that explicitly with reasoning — do not leave this section blank.]
| Concern | Impact | Mitigation | |---|---|---| | [e.g. New API endpoint exposed to internet] | [e.g. New attack surface] | [e.g. Rate limiting, auth required, WAF rules] | | [e.g. New data stored — user PII] | [e.g. GDPR scope expanded] | [e.g. Encrypted at rest, access log, data retention policy] | | [e.g. Service-to-service communication] | [e.g. Token forgery risk] | [e.g. mTLS between services] |
Has a threat model been produced or updated? [Yes — link / No — required before implementation / Not required — reason]
[Describe the expected performance impact. Include projections for the new system and how it was estimated.]
| Metric | Current | Projected | Measurement method | |---|---|---|---| | [e.g. P99 latency — /api/auth] | [120ms] | [≤50ms] | [Load test results — link] | | [e.g. Database query count per request] | [12] | [3] | [Query logging in staging] | | [e.g. Memory per instance] | [512MB] | [768MB] | [Profiling — link] | | [e.g. Infrastructure cost] | [$X/month] | [$Y/month] | [AWS cost calculator estimate] |
Load testing: [Has load testing been done? Link to results. If not, when will it be done?]
Performance risks:
Describe what new or changed metrics, logs, traces, and alerts this RFC introduces.
New metrics:
| Metric name | Type | Description | Alert threshold |
|---|---|---|---|
| [service].[component].[metric] | [counter/gauge/histogram] | [What it measures] | [e.g. P99 > 100ms for 5 min] |
New log events:
| Event | Level | When emitted | Key fields |
|---|---|---|---|
| [event.name] | INFO | [When] | user_id, duration_ms, result |
Distributed tracing: [Are spans added for new components? Which operations are instrumented?]
Dashboard changes: [New dashboard / updated existing dashboard — link]
Rollout strategy: [Feature flag / Canary / Blue-green / Gradual traffic shift / Full deploy]
| Stage | Traffic % | Duration | Success criteria | Rollback trigger | |---|---|---|---|---| | Internal testing | 0% (dogfood) | [X days] | [No errors in internal usage] | Any error | | Canary | 1% | [X hours] | [Error rate <0.1%; P99 latency within budget] | Error rate >0.5% | | Limited rollout | 10% | [X days] | [As above + business metrics stable] | Error rate >0.2% | | Full rollout | 100% | — | [All success metrics from Section 2 met] | Any SLO breach |
Feature flag: [Name of feature flag, if applicable] — managed in [LaunchDarkly / Unleash / config]
Rollback procedure:
// How to roll back if the rollout needs to be reversed
1. [Step 1 — e.g. Toggle feature flag to off]
2. [Step 2 — e.g. Deploy previous version]
3. [Step 3 — e.g. Notify stakeholders]
[List any unresolved questions, design decisions not yet made, or areas where the author is specifically seeking feedback. Assign an owner and a resolution deadline for each.]
| # | Question | Owner | Deadline | Resolution | |---|---|---|---|---| | 1 | [e.g. Should we use optimistic or pessimistic locking for concurrent updates to [resource]?] | [Name] | [Date] | [Pending / [Answer]] | | 2 | [e.g. What is the retention policy for [new data type]?] | [Name] | [Date] | [Pending / [Answer]] | | 3 | [e.g. Do we need a read replica for this query pattern at launch, or can we defer it?] | [Name] | [Date] | [Pending / [Answer]] |
To be filled in after the review period closes.
Decision: [Approved / Rejected / Approved with modifications] Decision date: [Date] Decision makers: [Names]
Summary of key feedback addressed:
Conditions of approval (if any):
development
Analyse competitor moves and translate them into strategic implications for your product roadmap. Use when a competitor announces a new feature, pricing change, partnership, or strategic shift, or when producing a periodic competitive intelligence report. Produces a categorised signal analysis with reactive-vs-proactive assessment, threat ratings, specific roadmap implications, and recommended responses with owners.
development
Build a community management playbook for a brand's social media channels. Use when asked to create guidelines for managing comments, DMs, and community interactions, define a moderation policy, or build response frameworks for social media community managers. Produces a complete playbook with response templates, escalation paths, moderation rules, and tone guidelines.
development
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.
development
Optimize an article for Answer Engine Optimization (AEO) — restructuring content so AI engines like ChatGPT, Perplexity, and Claude can extract, quote, and cite it. Rewrites headings as questions, drops 50-80 word answer capsules, audits paragraph length, and flags trust signals. Use when asked to AEO-optimize, make content AI-readable, improve AI citation chances, or adapt an article for answer engines.