PBS Documentation

This directory contains the working and normative documentation for PBS.

Tree

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:

agendas/: open and discuss unresolved topics.
decisions/: record the decision and its constraints.
specs/: integrate the closed decision into normative text.
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.