- Introduce the problem statement here. This might be well-defined ('we need to tweak the parameter of a rule from X to Y to help reduce a certain type of abuse'), or more fuzzy ('we need to invest more in paying back technical debt').
- Focus on the underlying problem that needs to be solved, as opposed to jumping to how you will solve it.
- Why is this an important problem for us to solve?
- Is it a big enough problem to solve?
- Should we solve it now, or later?
- Provide specific data (quantitative or qualitative) wherever possible.
- Add details of your proposed change. This can be high-level as psuedocode and sketches of the architecture, or as low-level as Protocol Buffer and interface definitions. Decide what the context of the proposal is, and write appropriately.
- Be explicit about what you are optimising for in this proposed solution — for example, 'we need to hit this deadline, so we'll accept the tech debt this entails'.
- In general, it's a red-flag if you haven't thought of a couple of different ways that you could approach the problem.
- What does your proposed solution give you that these approaches don't?
- What are they optimising for that isn't appropriate in this case?
- What risks does your proposed change entail?
- How will you mitigate them?
- How could this system fail, and what would be the impact if it did?