diff --git a/docs/README.md b/docs/README.md index 3e4cd0eb..b26f8ecf 100644 --- a/docs/README.md +++ b/docs/README.md @@ -7,6 +7,7 @@ picking the right document for what you're capturing. | Artifact | For | |---|---| +| **Design workflow** (`docs/design-workflow.md`) | How discussion becomes canonical design, how dependencies are recorded, and when implementation may begin. | | **Glossary** (`docs/glossary.md`) | Canonical term definitions — what words mean in this project. | | **PRD** (`docs/prds/`) | A feature: what to build, scope, success criteria. | | **Research note** (`docs/research/`) | A landscape/tradeoff investigation. | diff --git a/docs/design-workflow.md b/docs/design-workflow.md new file mode 100644 index 00000000..7de49d8b --- /dev/null +++ b/docs/design-workflow.md @@ -0,0 +1,220 @@ +# Design workflow + +How bot-bottle turns discussion into canonical design and then into +implementation without leaving the repository's architecture scattered across +issue and review threads. + +The goal is not more documentation. The goal is one discoverable current answer +for every load-bearing design question. + +## Sources of truth + +Design artifacts have different jobs: + +| Artifact | Authority | +|---|---| +| Architecture and decision records | Stable system-wide boundaries, policies, and invariants | +| PRDs | The current design for a feature | +| Research notes | Evidence and tradeoff analysis; informative, not normative | +| Issues | Work tracking, open questions, and discussion | +| Pull-request comments | Review history; never the final home of a design decision | + +When a discussion changes the design, update the relevant PRD, decision record, +or architecture document before treating the discussion as resolved. A comment +may explain why a decision changed, but future implementers must not need to +reconstruct the decision from a thread. + +Avoid duplicating the same rule in several canonical documents. Prefer one +canonical statement and links from dependent documents. + +## Choosing the canonical artifact + +Use a PRD when the decision describes a feature: its behavior, scope, success +criteria, trust model, implementation slices, and tests. + +Use a decision record when the choice is broader than one feature or will +constrain several future features. Examples include state ownership, credential +boundaries, compatibility policy, and what the project does or does not claim +as a security guarantee. + +Use an architecture document or concise architecture section when readers need +a current cross-feature map: component ownership, control-plane and data-plane +boundaries, durable state, credential flow, and network choke points. + +Use a research note when the conclusion depends on comparing external systems, +protocols, or approaches. Promote any resulting project decision into a PRD or +decision record. + +## From discussion to implementation + +### 1. Open the design discussion + +An issue may start with incomplete requirements. Record: + +- the problem and desired outcome; +- known security or compatibility constraints; +- the current owner of affected state and credentials; +- related PRDs, decisions, issues, and pull requests; +- open questions that would materially change the implementation. + +Do not disguise an unresolved trust-boundary or state-ownership decision as an +implementation detail. + +### 2. Draft or update the canonical design + +Before substantial implementation, write the feature PRD and update any +system-wide decision it changes. + +An active design should make these relationships visible near its top: + +```markdown +Status: Draft | Active | Superseded | Retargeted +Depends on: #... +Blocks: #... +Supersedes: ... +Last validated against main: +``` + +`Last validated against main` is a staleness signal, not a promise that no code +has changed. Update it after a meaningful design review against the current +architecture. + +For security-sensitive work, state: + +- the exact guarantee and explicit non-guarantees; +- trusted and untrusted components; +- who creates each identity or attribution field; +- who owns durable state; +- failure and recovery behavior; +- how the design is tested at its boundaries. + +### 3. Resolve review into the repository + +When review settles a design-changing question: + +1. Update the canonical document in the same pull request. +2. Mark conflicting documents Superseded or Retargeted, or update them. +3. Add or adjust dependency links. +4. Leave a concise resolution comment linking to the canonical change. + +A useful resolution comment is: + +```text +Resolution: +Canonicalized in: +Supersedes: +Follow-up: +``` + +The resolution is incomplete until the repository reflects it. + +### 4. Check design readiness + +Implementation may begin when: + +- the PRD's material trust, ownership, and compatibility questions are settled; +- dependencies and blockers are explicit; +- the design agrees with current architecture and decision records; +- superseded documents are marked or updated; +- success criteria and boundary tests are concrete; +- remaining open questions can be answered during implementation without + changing the feature's guarantee or component ownership. + +Small exploratory spikes may happen earlier. A spike proves feasibility; it does +not establish a production contract or silently settle the design. + +### 5. Implement in ordered slices + +Prefer small, independently reviewable slices after the parent design is +accepted. Record the dependency chain explicitly. + +Parallel work is safe when slices do not compete for the same unsettled +interface or ownership boundary. If a foundational change will alter the +transport, schema, state owner, or trust domain used by another slice, land the +foundation first. + +An implementation pull request should identify: + +- the PRD or decision it implements; +- the implementation chunk; +- its base and blockers; +- any design deviation discovered during implementation. + +If implementation reveals a load-bearing design change, pause that slice and +update the canonical design. Do not let the code and review thread become an +undocumented replacement for the PRD. + +## Dependency and staleness management + +### Dependency direction + +Write dependencies in terms of contracts, not chronology: + +```text +credential provisioning contract + -> host-controller authentication + -> privileged host operations +``` + +If only part of a feature is blocked, say so. For example, a manifest parser may +proceed while that feature's durable audit-storage chunk waits for the canonical +audit schema. + +### Superseding documents + +Do not silently edit history to make an old design appear to have always said +the new thing. Preserve the rationale, but make current status unmistakable: + +```markdown +Status: Superseded +Superseded by: +Reason: +``` + +If part of a PRD remains valid, mark it Retargeted and identify which scope moved +elsewhere. + +### Architecture sweeps + +After a foundational change, do a targeted architecture sweep before building +more features on it: + +1. Identify the concepts the change affects, such as `bot-bottle.db`, host + controller, orchestrator, audit ownership, or signing key. +2. Search active PRDs, decisions, and open issues for those concepts. +3. Update or supersede contradictory statements. +4. Refresh dependency links and the current architecture summary. +5. Confirm stacked implementation branches still have the correct base. + +This is a milestone activity, not a recurring documentation ceremony. + +## Pull-request checklist + +Use the relevant items in design and implementation pull requests: + +- [ ] The canonical PRD or decision is linked. +- [ ] Design-changing review decisions are reflected in-repo. +- [ ] Dependencies and blockers are explicit. +- [ ] State, credential, and trust ownership agree with current architecture. +- [ ] Superseded or retargeted documents are marked. +- [ ] Security guarantees and non-guarantees are precise. +- [ ] Open questions do not change the promised guarantee or ownership model. +- [ ] Implementation deviations updated the canonical design. +- [ ] The design was validated against a current `main`. + +## Lightweight maintenance + +Automation should enforce document shape, not pretend to understand +architecture. Useful checks include: + +- active PRDs contain status and dependency metadata; +- superseded PRDs link to their replacement; +- referenced documents and issues exist; +- implementation pull requests identify their PRD and chunk; +- document filenames and lifecycle states follow repository conventions. + +Human review remains responsible for detecting conflicting guarantees or +ownership claims. + +The durable rule is simple: **discussion discovers the decision; the repository +records it; implementation follows it.**