PBS Pull Requests
This directory contains self-contained PBS change proposals for review.
Purpose
A pull request document packages a proposed change so it can be reviewed as a coherent unit before final integration.
Use this directory when a change:
- touches multiple documents,
- changes architecture or semantics,
- needs explicit review criteria,
- or should be assessed before editing the final normative corpus.
Architecture and decisions come before implementation.
Required Properties
Every pull request document must be self-contained.
A reviewer should be able to understand the proposal without reconstructing context from chat history or scattered notes.
Required Sections
Each pull request should include, at minimum:
- Briefing
- Target
- Method
- Acceptance Criteria
- Tests, when needed
Recommended additional sections:
- Motivation
- Scope
- Non-Goals
- Affected Documents
- Open Questions
Section Expectations
Briefing
Summarize the problem and the proposed change in a short, readable form.
Target
State exactly what documents, behaviors, or contracts the proposal changes.
Method
Explain the architectural and editorial approach. If the proposal depends on prior decisions, name them explicitly.
Acceptance Criteria
List the conditions that must be true for the proposal to be accepted. These should be specific and reviewable.
Tests
Include tests when the change affects executable behavior, conformance, verification, lowering, or observable runtime semantics.
If tests are not necessary, say why.
Writing Rules
- Keep the proposal self-contained.
- Prefer explicit architectural reasoning over implementation detail.
- Do not bury acceptance criteria inside prose.
- Do not assume unresolved details.
- If a required decision is missing, stop and raise the question instead of inferring an answer.
Review Rule
A pull request may propose implementation consequences, but it must not smuggle in unresolved architectural choices as implementation details.