add README files to improve documentation organization and structure
This commit is contained in:
@@ -0,0 +1,44 @@
|
||||
# PBS Decisions
|
||||
|
||||
This directory contains PBS decision records.
|
||||
|
||||
## Purpose
|
||||
|
||||
A decision record is the bridge between agenda discussion and normative spec text.
|
||||
|
||||
Use this directory to capture:
|
||||
|
||||
- what was decided,
|
||||
- why that direction was chosen,
|
||||
- which constraints now apply,
|
||||
- what remains intentionally out of scope,
|
||||
- which specs must be updated.
|
||||
|
||||
Architecture and decisions must be resolved before implementation.
|
||||
|
||||
## Expected Format
|
||||
|
||||
A decision record should usually include:
|
||||
|
||||
1. Title
|
||||
2. Status
|
||||
3. Date or Cycle
|
||||
4. Context
|
||||
5. Decision
|
||||
6. Invariants
|
||||
7. Explicit Non-Decisions
|
||||
8. Spec Impact
|
||||
9. Validation Notes or Examples
|
||||
|
||||
## Writing Rules
|
||||
|
||||
- Write in stable, reviewable language.
|
||||
- State the adopted decision first and clearly.
|
||||
- Capture architectural constraints and invariants explicitly.
|
||||
- Record what is still not decided so later implementation does not guess.
|
||||
- Point to the exact specs that need integration.
|
||||
|
||||
## Implementation Rule
|
||||
|
||||
If implementation work exposes a missing decision, do not infer it.
|
||||
Stop, surface the ambiguity, and return it to agenda or decision review.
|
||||
Reference in New Issue
Block a user