didericis/bot-bottle
1
0
Fork 0
Code Issues 34 Pull Requests 9 Actions 7 Packages Releases Wiki Activity

docs: streamline design workflow guidance

Browse Source
This commit is contained in:
didericis (codex)
2026-07-26 06:37:43 +00:00
committed by didericis
parent 6b43fe73c1
commit 9537c96586
1 changed files with 13 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/design-workflow.md
+13 -15
View File
@@ -13,16 +13,16 @@ Design artifacts have different jobs:
| Artifact | Authority | | Artifact | Authority |
|---|---| |---|---|
| Architecture and decision records | Stable system-wide boundaries, policies, and invariants | | Decision records | Stable system-wide boundaries, policies, and invariants |
| PRDs | The current design for a feature | | PRDs | The current design for a feature |
| Research notes | Evidence and tradeoff analysis; informative, not normative | | Research notes | Evidence and tradeoff analysis; informative, not normative |
| Issues | Work tracking, open questions, and discussion | | Issues | Work tracking, open questions, and discussion |
| Pull-request comments | Review history; never the final home of a design decision | | 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, When a discussion changes the design, update the relevant PRD or decision
or architecture document before treating the discussion as resolved. A comment record before treating the discussion as resolved. A comment may explain why a
may explain why a decision changed, but future implementers must not need to decision changed, but future implementers must not need to reconstruct the
reconstruct the decision from a thread. decision from a thread.
Avoid duplicating the same rule in several canonical documents. Prefer one Avoid duplicating the same rule in several canonical documents. Prefer one
canonical statement and links from dependent documents. canonical statement and links from dependent documents.
@@ -37,10 +37,6 @@ constrain several future features. Examples include state ownership, credential
boundaries, compatibility policy, and what the project does or does not claim boundaries, compatibility policy, and what the project does or does not claim
as a security guarantee. 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, Use a research note when the conclusion depends on comparing external systems,
protocols, or approaches. Promote any resulting project decision into a PRD or protocols, or approaches. Promote any resulting project decision into a PRD or
decision record. decision record.
@@ -70,14 +66,11 @@ An active design should make these relationships visible near its top:
```markdown ```markdown
Status: Draft | Active | Superseded | Retargeted Status: Draft | Active | Superseded | Retargeted
Depends on: #... Depends on: #...
Blocks: #...
Supersedes: ... Supersedes: ...
Last validated against main: <commit or date>
``` ```
`Last validated against main` is a staleness signal, not a promise that no code Record dependencies only on the dependent document. Do not maintain reverse
has changed. Update it after a meaningful design review against the current `Blocks` lists that can drift as dependent work changes.
architecture.
For security-sensitive work, state: For security-sensitive work, state:
@@ -174,6 +167,12 @@ Reason: <one paragraph>
If part of a PRD remains valid, mark it Retargeted and identify which scope moved If part of a PRD remains valid, mark it Retargeted and identify which scope moved
elsewhere. elsewhere.
Add a short supersession note near the top explaining what changed, why the old
design is no longer current, and where the current design lives. For a research
note whose original analysis remains useful, preserve that analysis and append
a dated addendum with the newer finding instead of rewriting the note as though
it had always reached the new conclusion.
### Architecture sweeps ### Architecture sweeps
After a foundational change, do a targeted architecture sweep before building After a foundational change, do a targeted architecture sweep before building
@@ -200,7 +199,6 @@ Use the relevant items in design and implementation pull requests:
- [ ] Security guarantees and non-guarantees are precise. - [ ] Security guarantees and non-guarantees are precise.
- [ ] Open questions do not change the promised guarantee or ownership model. - [ ] Open questions do not change the promised guarantee or ownership model.
- [ ] Implementation deviations updated the canonical design. - [ ] Implementation deviations updated the canonical design.
- [ ] The design was validated against a current `main`.
## Lightweight maintenance ## Lightweight maintenance