From 9a4685179191dfb9259d7c4967b31fe9ad17917f Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Tue, 3 Mar 2026 05:03:58 +0000 Subject: [PATCH] add README files to improve documentation organization and structure --- docs/pbs/README.md | 87 ++++++++++++++++++++++++++++++++ docs/pbs/agendas/README.md | 46 +++++++++++++++++ docs/pbs/decisions/README.md | 44 ++++++++++++++++ docs/pbs/pull-requests/README.md | 78 ++++++++++++++++++++++++++++ docs/pbs/specs/README.md | 48 ++++++++++++++++++ 5 files changed, 303 insertions(+) create mode 100644 docs/pbs/README.md create mode 100644 docs/pbs/agendas/README.md create mode 100644 docs/pbs/decisions/README.md create mode 100644 docs/pbs/pull-requests/README.md create mode 100644 docs/pbs/specs/README.md diff --git a/docs/pbs/README.md b/docs/pbs/README.md new file mode 100644 index 00000000..2f0759ba --- /dev/null +++ b/docs/pbs/README.md @@ -0,0 +1,87 @@ +# PBS Documentation + +This directory contains the working and normative documentation for PBS. + +## Tree + +```text +docs/pbs/ +├── agendas/ +├── decisions/ +├── pull-requests/ +└── specs/ +``` + +## Responsibilities + +### `agendas/` + +`agendas/` contains open topics. + +Use it to: + +- record unresolved questions, +- define scope, dependencies, and non-goals, +- structure discussion order, +- keep only active TODO topics visible. + +An agenda is a discussion artifact, not a final normative document. +Once a topic is settled, it should leave this directory. + +### `decisions/` + +`decisions/` contains closed decision records between discussion and spec integration. + +Use it to: + +- record the adopted decision clearly, +- capture invariants and architectural constraints, +- state what was explicitly left undecided, +- identify which specs must be updated, +- preserve traceability without turning specs into debate logs. + +Architecture and decisions come before implementation. + +### `specs/` + +`specs/` contains the normative PBS corpus. + +Use it to: + +- consolidate the official PBS contract, +- integrate already-closed decisions in normative language, +- define precedence, scope, rules, and exit criteria, +- provide the baseline for implementation, verification, and conformance. + +Specs must not operate as discussion backlogs. +If a point is still disputed or underspecified, it belongs in `agendas/` or `decisions/`, not directly in `specs/`. + +### `pull-requests/` + +`pull-requests/` contains self-contained change proposals for review. + +Use it to: + +- package a proposed change across multiple documents, +- explain motivation, target, method, acceptance criteria, and tests, +- make the review surface explicit before final integration, +- keep architectural and decision-level review ahead of implementation work. + +If implementation reveals an unresolved ambiguity, stop and ask the question explicitly. +Do not infer missing architectural decisions during implementation. + +## Recommended Flow + +The preferred pipeline is: + +1. `agendas/`: open and discuss unresolved topics. +2. `decisions/`: record the decision and its constraints. +3. `specs/`: integrate the closed decision into normative text. +4. `pull-requests/`: use when a change should be reviewed as a self-contained proposal before merge. + +## Practical Rule + +- `agendas/` stores open questions. +- `decisions/` stores closed answers. +- `specs/` stores the normative contract. +- `pull-requests/` stores reviewable change packages. diff --git a/docs/pbs/agendas/README.md b/docs/pbs/agendas/README.md new file mode 100644 index 00000000..62348f26 --- /dev/null +++ b/docs/pbs/agendas/README.md @@ -0,0 +1,46 @@ +# PBS Agendas + +This directory contains active PBS discussion agendas. + +## Purpose + +An agenda exists to drive a decision, not to serve as final normative text. + +Use an agenda when: + +- the topic is still open, +- multiple options or tradeoffs must be evaluated, +- the scope and non-goals need to be made explicit, +- the order of discussion matters. + +Remove an agenda from this directory once the topic is no longer active. + +## Expected Format + +An agenda should usually include: + +1. Title +2. Status +3. Purpose +4. Context +5. Decisions to Produce +6. Core Questions +7. Expected Spec Material +8. Non-Goals +9. Inputs + +## Writing Rules + +- Keep the document oriented around unresolved questions. +- Separate open questions from assumptions already fixed elsewhere. +- Name the concrete decisions the discussion must produce. +- Avoid drafting large blocks of final normative spec text here. +- Prefer explicit non-goals to prevent scope drift. + +## Exit Rule + +An agenda should move out of the active set when: + +- the key questions have been answered, +- the architectural direction is clear enough to record, +- and the topic is ready to become a decision record and then a spec update. diff --git a/docs/pbs/decisions/README.md b/docs/pbs/decisions/README.md new file mode 100644 index 00000000..4aab3723 --- /dev/null +++ b/docs/pbs/decisions/README.md @@ -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. diff --git a/docs/pbs/pull-requests/README.md b/docs/pbs/pull-requests/README.md new file mode 100644 index 00000000..111d5e04 --- /dev/null +++ b/docs/pbs/pull-requests/README.md @@ -0,0 +1,78 @@ +# 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: + +1. Briefing +2. Target +3. Method +4. Acceptance Criteria +5. Tests, when needed + +Recommended additional sections: + +6. Motivation +7. Scope +8. Non-Goals +9. Affected Documents +10. 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. diff --git a/docs/pbs/specs/README.md b/docs/pbs/specs/README.md new file mode 100644 index 00000000..639a59d3 --- /dev/null +++ b/docs/pbs/specs/README.md @@ -0,0 +1,48 @@ +# PBS Specs + +This directory contains the normative PBS specification set. + +## Purpose + +Specs define the official PBS contract. + +They exist to make behavior, constraints, and interfaces stable across implementations and reviews. + +## 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.