Owner: @Daniel Sanchez Quiros

Ensuring Nomos Specifications are correctly implemented

We must ensure our specifications are correctly implemented. It's crucial to maintain context in both the specification and the implementation, meaning that if either side is out of sync, it needs to be updated.

Specifications may:

• Lack details
• Contain mismatched information across different documents referring to the same piece

We need to ensure that code reviews identify these issues and code aligns the specification and implementation.

Steps

1. Implementers must to read the entire specification for what they need to implement.
2. Implementers should thoroughly understand the documentation and, if necessary, raise issues and questions beforehand, identifying any missing or incorrect information.
3. Proceed with full or partial implementation based on the specification.
4. Take notes, mark TODO's, or maintain a change list for any deviations from the specification.
5. Provide the necessary information in the PR so other team members can keep track of what's happening.

Maintaining Context

To ensure specifications and implementations align, we need to address key questions and align as much information as possible.

• Link specification notes to the actual PR (pull request) that implements or modifies it.
• If the specification lacks details:
  • Explain what was missing.
  • Propose changes to include the missing details.
  • Engage the original authors for discussion.
• If modifications are necessary because the specification couldn’t be implemented as is:
  • Explain why implementation wasn’t possible.
  • Identify the main issue.
  • Describe any proposed or implemented solution.
  • Suggest changes to the specification to resolve the issue.
  • Engage the original specification authors for discussion.

PR Template