openjobdescription/openjd-specifications/openjd-rfc-review-2

OpenJD RFC Review

Overview

Guide for reviewing Open Job Description RFC proposals to ensure quality, completeness, alignment with project tenets, and compatibility with existing specifications.

Usage

Use this skill when:

• Reviewing an Open Job Description RFC document for the openjd-specifications project in its rfcs/ directory.
• Providing feedback on an RFC pull request
• Evaluating whether an RFC is ready for final comments period
• Checking RFC compliance with template requirements

Core Concepts

Design Tenets

Every RFC MUST align with these tenets (unless you know better ones):

1. Portable - Features should work across different operating systems, queuing implementations, and technology stacks
2. Expressive - Features should be general, not narrowly tailored to specific use cases
3. Human readable and writable - Artifacts should be easily understood and authored with a text editor
4. Tooling parseable - Artifacts should be parseable by automated tooling

RFC Template Sections

Required sections per 0000-template.md:

• Summary - One paragraph overview
• Basic Examples - Usage demonstrations for schema/syntax changes
• Motivation - Use cases, workflows enabled, how common they are
• Specification - Specific changes in formal specification style
• Design Choice Rationale - Reasoning for each significant decision
• Prior Art - Similar features in other systems
• Rejected Ideas - Ideas considered but not pursued
• Copyright - Public domain or CC0-1.0-Universal

RFC Metadata

Required header fields:

• Feature Name (unique identifier)
• RFC Tracking Issue URL
• Start Date (YYYY-MM-DD)
• Specification Version (e.g., 2023-09 extension EXTENSION_NAME)
• Accepted On (filled when accepted)

Compatibility with Open Job Description Specifications

Every RFC proposed change must fit into the formal template specification in the openjd-specifications repo in wiki/2023-09-Template-Schemas, or downloadable at https://github.com/OpenJobDescription/openjd-specifications/wiki/2023-09-Template-Schemas.

• If the RFC adds sections similar to existing sections, are they consistent with the existing sections in context?
• Does the proposed new language fit naturally into the specification?
• Do the high level ideas fit well with the existing concepts in the specification?
• Do they apply orthogonally, as general features should, or do they have special cases that limit applicability?
• Does the combined system feel consistent and whole, not disparate pieces bolted together?

Review Checklist

Completeness

• [ ] All template sections present and substantive
• [ ] Metadata fields filled correctly
• [ ] Tracking issue exists and linked
• [ ] Examples are runnable and demonstrate the feature

Clarity

• [ ] Summary captures the essence in one paragraph
• [ ] Motivation explains WHY, not just WHAT
• [ ] Examples succinctly demonstrate the proposal in practice
• [ ] Specification is precise enough to implement
• [ ] Design rationale explains key decisions

Tenet Alignment

• [ ] Portable: Does this work across systems? Does it make any assumptions that won't apply on a different OS, data management system, etc.?
• [ ] Expressive: Is this general or too narrowly tailored?
• [ ] Human readable: Can users understand this from reading the template?
• [ ] Human writeable: Can users write templates with this, and not get lost in boilerplate or complicated details?
• [ ] Tooling parseable: Can automated tools process a template with the feature and unambiguously determine author intent?

Specification Compatibility

• [ ] Proposed language fits naturally into the specification
• [ ] High level ideas fit well with existing concepts
• [ ] New concepts apply orthogonally with existing features
• [ ] Combined work is consistent and whole

Technical Quality

• [ ] Specification diff is syntactically correct
• [ ] Examples validate against proposed schema
• [ ] Edge cases addressed
• [ ] Backward compatibility considered
• [ ] Extension naming follows conventions

Process

• [ ] Prior art section shows research was done
• [ ] Rejected ideas explain why alternatives weren't chosen
• [ ] No unresolved open questions blocking acceptance

Common Issues

Weak Motivation

Problem: "Users want this feature" without explaining workflows enabled. Fix: Describe concrete use cases and how common they are.

Vague Specification

Problem: Prose description instead of formal specification language. Fix: Write as if it could be dropped into the spec document directly.

Missing Rationale

Problem: Design choices made without explaining alternatives considered. Fix: For each significant choice, explain why this option over others.

Tenet Violations

Problem: Feature is too specific to one workflow or system. Fix: Generalize the feature or justify why specificity is necessary.

Quick Reference

Providing Feedback

When reviewing, structure feedback as:

1. Summary assessment - Overall readiness for acceptance
2. Strengths - What the RFC does well
3. Tenet alignment - How well the RFC exemplifies each tenet
4. Specification compatibility - How well the RFC fits with existing specification
5. Required changes - Blocking issues that must be addressed
6. Suggestions - Non-blocking improvements
7. Questions - Clarifications needed

Reference specific sections and line numbers. Cite design tenets when relevant.