discussion framework migration
This commit is contained in:
@@ -0,0 +1,59 @@
|
||||
# PBS Specs
|
||||
|
||||
This directory contains the normative PBS specification set.
|
||||
|
||||
## Purpose
|
||||
|
||||
Specs define the official PBS language/frontend contract.
|
||||
|
||||
They exist to make behavior, constraints, and interfaces stable across implementations and reviews.
|
||||
|
||||
Cross-language acceptance rules are not defined here.
|
||||
Those are maintained in `docs/general/specs`.
|
||||
|
||||
## Expected Format
|
||||
|
||||
The exact structure may vary by document, but a spec should usually contain:
|
||||
|
||||
1. Title
|
||||
2. Status
|
||||
3. Scope or Applies To
|
||||
4. Purpose
|
||||
5. Authority and Precedence
|
||||
6. Normative Inputs
|
||||
7. Core Rules
|
||||
8. Non-Goals
|
||||
9. Exit Criteria
|
||||
|
||||
Some specs may also include:
|
||||
|
||||
- already-settled inputs,
|
||||
- initial section targets,
|
||||
- `TODO` sections for tracked unresolved items,
|
||||
- cross-references to adjacent specs.
|
||||
|
||||
## Writing Rules
|
||||
|
||||
- Write in normative language.
|
||||
- Integrate only decisions that have already been closed.
|
||||
- Keep debate history and exploratory alternatives out of the spec body.
|
||||
- Preserve clear boundaries between adjacent specs.
|
||||
- Use `TODO` only for explicitly tracked unresolved items, not as a substitute for agenda work.
|
||||
|
||||
## Upstream Rule
|
||||
|
||||
Specs should normally be fed by:
|
||||
|
||||
1. agendas that frame the open topic,
|
||||
2. decisions that close the architectural question,
|
||||
3. then spec integration.
|
||||
|
||||
If a spec edit would require guessing an unresolved design choice, the correct action is to stop and surface the missing decision first.
|
||||
|
||||
## Current Chapter Focus
|
||||
|
||||
The active PBS chapter focus is:
|
||||
|
||||
- `11. AST Specification.md`
|
||||
- `12. Diagnostics Specification.md`
|
||||
- `13. Lowering IRBackend Specification.md`
|
||||
Reference in New Issue
Block a user