91 lines
2.5 KiB
Markdown
91 lines
2.5 KiB
Markdown
# 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.
|
|
|
|
`docs/pbs/specs` is language-specific.
|
|
Cross-language acceptance specs live in `docs/general/specs`.
|
|
|
|
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 PBS-specific normative contract.
|
|
- `pull-requests/` stores reviewable change packages.
|