Skip to content

docs(adr): compress to 3 records in the domain-modeling format - #106

Merged
lesnik512 merged 1 commit into
mainfrom
docs/compress-adrs
Sep 19, 2026
Merged

lesnik512 merged 1 commit into
mainfrom
docs/compress-adrs

Conversation

@lesnik512

Copy link
Copy Markdown
Member

Rewrites docs/adr/ from 3 records (839 words) to 3 (459 words), one paragraph each, in the shape docs/standard.md asks for. This repo owns that sentence, so its own records should read like it. Same treatment as modern-python/compose2pod#102.

Nothing was dropped or merged: all three records pass the admission test, so the numbering is untouched and no citation moves. The compression is in the prose and the format, the **Decision:** lead and the **Revisit trigger:** footer are gone, with a trigger folded into the paragraph only where it is the real boundary of the decision.

Evaluation

Old Outcome New Reason
0001 project marks single gold inner kept, rewritten 0001 Hard to reverse across 26 published marks, surprising to a reader who sees a palette and no per-project accent, and a real trade-off against the drawn Heritage and Vivid accent palettes.
0002 Discussions is the only owned channel kept, rewritten 0002 A boundary decision with a standing no to Discord and Telegram, argued from the empty-room threshold rather than from preference.
0003 Flask horn historical artwork grant kept, rewritten 0003 A constraint invisible in the code: the permission relied on was withdrawn from the Pallets repo, so it cannot be reconstructed from anywhere else. The redraw is cheap, but the artwork has already shipped in the brand kit, and the rule it sets ("a partner's literal path needs a grant") is what a future symbol would be measured against.

The rules that survived from the sections that were cut, rather than being lost with them: the two templates reuse the org chevron (0001), ALLOWED_COLORS is where the colour rule is enforced (0001), and one org-wide room per platform, never per-repo, if rooms ever open (0002).

Citations

None moved. tests/test_projects.py (0001), CONTEXT.md (0002), brand/build/symbols.py (0003) and docs/agents/domain.md (ADR-0001 plus the file tree) all cite names that are unchanged. The repo-wide sweep finds no reference to a number that no longer exists.

mkdocs.yml excludes /adr/ from the published site, so these files render on GitHub only; nothing here adds a link that would have to resolve in both renderings.

Stale claims corrected

  • 0001 claimed a single gold inner symbol with no qualification. projects.py::ALLOWED_COLORS admits symbols._BAR_TINTS, the pytest bars' four-step gold ramp, which the code calls "the one allowed non-token palette". The record now names it as the one sanctioned exception.
  • 0002 pointed its revisit trigger at modern-python/.github#58 for launch week. That number resolves to neither an issue nor a PR today, so the bare reference is dropped and launch week is stated as the boundary instead.
  • 0002's "all 28 repos" was checked and is current: the org has 28 repos, 26 of them carrying project marks.
  • 0003's account of the Flask Artwork License matches the comment above FLASK_PATHS in symbols.py; the scope claim (FastStream's mark and Flask's horn are the only literal partner paths) was re-checked against symbols.py and holds.

Gates

Gate Result
pytest -q tests/test_adr_citations.py 7 passed
pytest -q 132 passed, 29 skipped
lychee --offline over the three records, CONTEXT.md, AGENTS.md 2 links, 1 OK, 0 errors, 1 excluded
mkdocs build --strict builds clean; docs/adr/ stays out of the site, as exclude_docs intends
ruff skipped, not installed in this repo's venv
eof-fixer skipped, not installed in this repo's venv
justfile docs build target none exists; just has test and sync-assets only

Rewrite each record as a title plus one paragraph, dropping the
**Decision:** lead and the **Revisit trigger:** footer. No record was
dropped or merged: all three pass the admission test, so the numbering
and every citation are unchanged.

- 0001: fold the templates-reuse-the-chevron rule and the ALLOWED_COLORS
  gate into the paragraph; record the pytest bars' gold ramp as the one
  sanctioned exception to the single-gold inner.
- 0002: keep the empty-room threshold as the load-bearing reason, fold
  the borrow-audiences principle and the conditional backlink into one
  clause, and drop the reference to a tracking issue that no longer
  resolves.
- 0003: fold the redraw cost into the paragraph as the boundary of the
  decision.
@lesnik512
lesnik512 merged commit 54fd3de into main Sep 19, 2026
3 checks passed
@lesnik512
lesnik512 deleted the docs/compress-adrs branch September 19, 2026 11:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant