Build a pattern catalog site with one teaching page per pattern

jared commented

2026-11-06 13:09:58 +00:00

Owner

Problem

The grid names 24 patterns, but Jared does not yet know them well enough to judge a cell. He needs one reference page per pattern, written to be easy to digest. The page must have no running LLM cost.

Reproduce

n/a: feature ticket.

Approach

Each pattern has one reviewed text file in plugins/os-sdlc/pattern-pages/<name>.yml. Those files already exist on main. A Ruby build merges each file with Catalog.patterns and writes static HTML to plugins/os-sdlc/pattern-site/. The build calls no LLM.

plugins/os-sdlc/bin/system-model pattern-site

Each page has these sections, in this order: Intent, Problem (text and wrong code), Solution (text and right code), Structure (SVG diagram from the catalog allowed edges, then the Roles table), Ruby example (intro, code, output), Rules (rule text from the catalog, why, Breaks, Follows), Applicability, How to Implement, Pros and Cons, Relations with Other Patterns (links to the other pages), and the catalog source. index.html lists every pattern with its one-line intent. Take the page CSS from docs/system-design-format/proof/2026-11-06-repository-pattern-page.html: light and dark palette, side navigation, side-by-side Breaks and Follows.

The build reads the role names, rule text, allowed edges, and source from the catalog. It never reads them from the YAML file. The build refuses and writes nothing when one of these is true: a catalog pattern has no file, a file has an unknown id, role names or rule ids differ from the catalog, or a relation names an unknown id. The refusal names each pattern, and it gives the command /os-sdlc:pattern-page <id> for a missing page. The build runs each example.code with ruby and refuses if stdout differs from example.output.

A test runs the same content checks on the real files, without the ruby runs. So a new pattern in the catalog fails the suite until its page exists. The skill /os-sdlc:pattern-page then writes the file. This is the automatic part: the code detects the gap, and one command fills it.

Required work:

Add the pattern-site analysis to system-model — check: present pattern-site in plugins/os-sdlc/lib/os_sdlc/system_model/run.rb
Keep the skill that writes one page file, already on main — check: present orwell-writing in plugins/os-sdlc/skills/pattern-page/SKILL.md
Build and commit the site — check: present Repository in plugins/os-sdlc/pattern-site/index.html

Orchestrator work: run bin/refresh-plugins, add the History row, and link the site from docs/system-design-format/README.md.

Rejected: Astro — a Node build for 24 static pages adds a dependency with no gain, and a Ruby script reads the catalog directly.
Rejected: generate the page text at build time with an LLM — it costs money on each build and can change the text with no review.
Rejected: output under design/ — ADR-0300 fixes that layout.

Acceptance criteria

Given every pattern in Catalog.patterns has a valid file, when system-model pattern-site runs, then each pattern has a page and index.html links to it.
Given a catalog pattern with no file, when the build runs, then it exits non-zero, writes no page, and names the id with the command /os-sdlc:pattern-page <id>.
Given a file whose role names or rule ids differ from the catalog, when the build runs, then it exits non-zero and names the difference.
Given a pattern page, when a reader opens it, then the role names, rule text, and source match the catalog.
Given a relation in a file, when a reader follows its link, then the page of the named pattern opens.
Given a pattern with allowed edges, when a reader opens its page, then the diagram shows one box per role and one arrow per edge, and a self edge such as Builder -> Builder renders.
Given an example.output that differs from what its code prints, when the build runs, then it exits non-zero and names the pattern.
Given the real files in plugins/os-sdlc/pattern-pages/, when the suite runs, then a test confirms that each catalog pattern has a valid file.

Owner sketch

class OsSdlc::SystemModel::PatternSite
  def initialize(catalog:, pages_dir:, out_dir:)
  def problems
  def build
end

class OsSdlc::SystemModel::PatternSite::Page
  def initialize(pattern, content, slug)
  def html
end

class OsSdlc::SystemModel::PatternSite::Diagram
  def initialize(pattern)
  def svg
end

Non-goals

Links from grid columns stay with #1580. A generated "In this codebase" section waits for a role-to-class view in the gauge, and it should follow #1584. Impeccable styling comes later.

Origin

Trigger: Jared on 2026-11-06, after he read the grid.
Improvised this session: none
Chain: Jared cannot judge a grid cell ← the catalog holds rules for a detector, not for a reader. Ends at DESIGN: plugins/os-sdlc/lib/os_sdlc/system_model/catalog/.
Root candidate: none found; searched catalog, teaching page, pattern page, site, landscape
Where: plugins/os-sdlc/lib/os_sdlc/system_model/catalog.rb
Session: 8720f6ad-c6db-428e-977f-7511559fbfbb
Transcript: /home/jared/.claude/projects/-home-jared-dev-cc-os/8720f6ad-c6db-428e-977f-7511559fbfbb.jsonl

VERDICT: CREATE

## Problem The grid names 24 patterns, but Jared does not yet know them well enough to judge a cell. He needs one reference page per pattern, written to be easy to digest. The page must have no running LLM cost. ## Reproduce n/a: feature ticket. ## Approach Each pattern has one reviewed text file in `plugins/os-sdlc/pattern-pages/<name>.yml`. Those files already exist on `main`. A Ruby build merges each file with `Catalog.patterns` and writes static HTML to `plugins/os-sdlc/pattern-site/`. The build calls no LLM. ``` plugins/os-sdlc/bin/system-model pattern-site ``` Each page has these sections, in this order: Intent, Problem (text and wrong code), Solution (text and right code), Structure (SVG diagram from the catalog `allowed` edges, then the Roles table), Ruby example (intro, code, output), Rules (rule text from the catalog, why, Breaks, Follows), Applicability, How to Implement, Pros and Cons, Relations with Other Patterns (links to the other pages), and the catalog `source`. `index.html` lists every pattern with its one-line intent. Take the page CSS from `docs/system-design-format/proof/2026-11-06-repository-pattern-page.html`: light and dark palette, side navigation, side-by-side Breaks and Follows. The build reads the role names, rule text, allowed edges, and source from the catalog. It never reads them from the YAML file. The build refuses and writes nothing when one of these is true: a catalog pattern has no file, a file has an unknown `id`, role names or rule ids differ from the catalog, or a relation names an unknown id. The refusal names each pattern, and it gives the command `/os-sdlc:pattern-page <id>` for a missing page. The build runs each `example.code` with `ruby` and refuses if stdout differs from `example.output`. A test runs the same content checks on the real files, without the `ruby` runs. So a new pattern in the catalog fails the suite until its page exists. The skill `/os-sdlc:pattern-page` then writes the file. This is the automatic part: the code detects the gap, and one command fills it. Required work: 1. Add the `pattern-site` analysis to system-model — check: present `pattern-site` in `plugins/os-sdlc/lib/os_sdlc/system_model/run.rb` 2. Keep the skill that writes one page file, already on main — check: present `orwell-writing` in `plugins/os-sdlc/skills/pattern-page/SKILL.md` 3. Build and commit the site — check: present `Repository` in `plugins/os-sdlc/pattern-site/index.html` Orchestrator work: run `bin/refresh-plugins`, add the History row, and link the site from `docs/system-design-format/README.md`. Rejected: Astro — a Node build for 24 static pages adds a dependency with no gain, and a Ruby script reads the catalog directly. Rejected: generate the page text at build time with an LLM — it costs money on each build and can change the text with no review. Rejected: output under `design/` — ADR-0300 fixes that layout. ## Acceptance criteria 1. Given every pattern in `Catalog.patterns` has a valid file, when `system-model pattern-site` runs, then each pattern has a page and `index.html` links to it. 2. Given a catalog pattern with no file, when the build runs, then it exits non-zero, writes no page, and names the id with the command `/os-sdlc:pattern-page <id>`. 3. Given a file whose role names or rule ids differ from the catalog, when the build runs, then it exits non-zero and names the difference. 4. Given a pattern page, when a reader opens it, then the role names, rule text, and source match the catalog. 5. Given a relation in a file, when a reader follows its link, then the page of the named pattern opens. 6. Given a pattern with `allowed` edges, when a reader opens its page, then the diagram shows one box per role and one arrow per edge, and a self edge such as `Builder -> Builder` renders. 7. Given an `example.output` that differs from what its code prints, when the build runs, then it exits non-zero and names the pattern. 8. Given the real files in `plugins/os-sdlc/pattern-pages/`, when the suite runs, then a test confirms that each catalog pattern has a valid file. ## Owner sketch ```ruby class OsSdlc::SystemModel::PatternSite def initialize(catalog:, pages_dir:, out_dir:) def problems def build end class OsSdlc::SystemModel::PatternSite::Page def initialize(pattern, content, slug) def html end class OsSdlc::SystemModel::PatternSite::Diagram def initialize(pattern) def svg end ``` ## Non-goals Links from grid columns stay with #1580. A generated "In this codebase" section waits for a role-to-class view in the gauge, and it should follow #1584. Impeccable styling comes later. ## Origin - Trigger: Jared on 2026-11-06, after he read the grid. - Improvised this session: none - Chain: Jared cannot judge a grid cell ← the catalog holds rules for a detector, not for a reader. Ends at `DESIGN`: `plugins/os-sdlc/lib/os_sdlc/system_model/catalog/`. - Root candidate: none found; searched catalog, teaching page, pattern page, site, landscape - Where: plugins/os-sdlc/lib/os_sdlc/system_model/catalog.rb - Session: 8720f6ad-c6db-428e-977f-7511559fbfbb - Transcript: /home/jared/.claude/projects/-home-jared-dev-cc-os/8720f6ad-c6db-428e-977f-7511559fbfbb.jsonl VERDICT: CREATE

jared added the

plugin/os-sdlc

filed-by/user

category/no-test-target

labels

2026-11-06 13:09:58 +00:00

jared referenced this issue from a commit

2026-11-06 14:30:34 +00:00

docs(system-design): add the pilot Repository pattern page (#1581)

jared referenced this issue

2026-11-06 14:31:05 +00:00

Make the REPO role see network stores and stop counting input reads as storage #1584

jared commented

2026-11-06 15:09:58 +00:00

Author

Owner

Jared ruled 2026-11-06: one reviewed text file per pattern plus a Ruby build, no running LLM cost. Page sections follow refactoring.guru in structure, language, and approach, with Ruby examples and our own text. Build next. A new catalog pattern fails the suite and names /os-sdlc:pattern-page.

jared added

category/code-change

and removed

category/no-test-target

labels

2026-11-06 15:10:01 +00:00

jared commented

2026-11-06 15:12:51 +00:00

Author

Owner

Work started on branch ticket-1581 through the os-sdlc pipeline.

jared referenced this issue

2026-11-06 16:13:31 +00:00

Check present patterns against the conventions that give each pattern its benefit #1555

jared commented

2026-11-06 16:13:35 +00:00

Author

Owner

Resolution

Done: Built one reference page for each of the 24 catalog patterns, plus an index, as static HTML. The text is in reviewed YAML files. The build uses no LLM. A suite test and the build refuse a catalog pattern with no page and name /os-sdlc:pattern-page .

Evidence: Commits f28a0674, 9fb8c1be, 40e85ffd, ce72ff07. tests/system_model_pattern_site_test.rb: 13 runs, 0 failures. rubocop clean. system-model pattern-site writes 25 files in about 4 s. Render checked on index, repository, hex, and mediator.

Follow-ups: Grid links to pages: #1580. Generated In this codebase section: after #1584. Catalog mismatches found in review: recorded on #1555.

## Resolution **Done:** Built one reference page for each of the 24 catalog patterns, plus an index, as static HTML. The text is in reviewed YAML files. The build uses no LLM. A suite test and the build refuse a catalog pattern with no page and name /os-sdlc:pattern-page <id>. **Evidence:** Commits f28a0674, 9fb8c1be, 40e85ffd, ce72ff07. tests/system_model_pattern_site_test.rb: 13 runs, 0 failures. rubocop clean. system-model pattern-site writes 25 files in about 4 s. Render checked on index, repository, hex, and mediator. **Follow-ups:** Grid links to pages: #1580. Generated In this codebase section: after #1584. Catalog mismatches found in review: recorded on #1555.

jared closed this issue

2026-11-06 16:13:35 +00:00

jared referenced this issue from a commit

2026-11-06 16:14:37 +00:00

docs(os-sdlc): add the 24 pattern page files and the pattern-page skill (#1581)

jared referenced this issue from a commit

2026-11-06 16:14:37 +00:00

docs(os-sdlc): correct the pattern pages after review (#1581)

jared referenced this issue from a commit

2026-11-06 16:14:37 +00:00

feat(os-sdlc): Audited POODR boundaries for the pattern-site change; design is sound, and two specified refusals have no test. (#1581)

jared referenced this issue from a commit