ai-for-dummies/submitted-skills/Marcos Silva/templates/rfc.md

RFC — Template

Use for proposals that need a written decision record. Status field goes at the top so the page reader sees it before the rest.

Sections

• Status (DRAFT / REVIEW / ACCEPTED / REJECTED / SUPERSEDED)
• Author + reviewers (the people whose names should be on the proposal)
• Context (the problem and why now)
• Proposal (the change, in concrete terms)
• Alternatives considered (one paragraph each, with the reason rejected)
• Risks and mitigations (table)
• Rollout plan (phases, owners, rollback)
• Open questions (the things still being decided)

Anti-patterns

• Don't write an RFC without alternatives. A proposal that has no rejected alternatives either didn't think hard enough or didn't consider the reader.
• Don't hide the status. The reader's first question is "is this decided?"; answer it in the first line.
• Don't open questions at the end of the proposal. Put them after the rollout plan, where they don't read as part of the decision.

Storage template

<h1>{Title — verb-first}</h1>

<ac:structured-macro ac:name="status">
  <ac:parameter ac:name="colour">Yellow</ac:parameter>
  <ac:parameter ac:name="title">DRAFT</ac:parameter>
</ac:structured-macro>

<table>
  <tbody>
    <tr>
      <th>Author</th>
      <td>{name}</td>
    </tr>
    <tr>
      <th>Reviewers</th>
      <td>{names}</td>
    </tr>
    <tr>
      <th>Status</th>
      <td>DRAFT</td>
    </tr>
  </tbody>
</table>

<h2>Context</h2>
<p>{problem + why now}</p>

<h2>Proposal</h2>
<p>{the change in concrete terms}</p>

<h2>Alternatives considered</h2>
<h3>{Alternative 1}</h3>
<p>{why rejected}</p>
<h3>{Alternative 2}</h3>
<p>{why rejected}</p>

<h2>Risks and mitigations</h2>
<table>
  <tbody>
    <tr>
      <th>Risk</th>
      <th>Mitigation</th>
    </tr>
    <tr>
      <td>{risk}</td>
      <td>{mitigation}</td>
    </tr>
  </tbody>
</table>

<h2>Rollout plan</h2>
<table>
  <tbody>
    <tr>
      <th>Phase</th>
      <th>Owner</th>
      <th>Rollback</th>
    </tr>
    <tr>
      <td>{phase}</td>
      <td>{owner}</td>
      <td>{how to roll back}</td>
    </tr>
  </tbody>
</table>

<h2>Open questions</h2>
<ul>
  <li>{question}</li>
</ul>

Cross-references

• Storage macros: confluence-page/references/macros.md
• Status colors: Yellow (DRAFT), Blue (REVIEW), Green (ACCEPTED), Red (REJECTED), Grey (SUPERSEDED)