Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 39 additions & 0 deletions .okf/log.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,45 @@ make it green: restructure same-day entries under one heading, and add
`timestamp` to the 23 concepts missing it (anchored to each file's last commit
time, which is verifiable - never invented).

## 2026-08-21 - two lanes on the redesign, and three confusions removed

Paul opened a from-scratch design exploration ALONGSIDE the extraction, not
instead of it. Recorded everywhere a cold session might read one as the other:
`docs/projects/2608-site-design-system/README.md`, the rollout plan, and
[workflows/site-redesign-rollout.md](workflows/site-redesign-rollout.md).

**Extraction governs; discovery has no authority.** ADR-0003 states plainly that
this is "extraction and propagation, not a redesign" - the system comes from the
course page and `/services/vibe-code-rescue/`. The discovery lane produces
candidate designs and never a PR; it wins only via a superseding ADR carrying
evidence, because 2.1/2.2 already shipped the extracted system to the blog,
which is 77% of the site's Google traffic. Brand invariants (logo, ruby, display
face, covers) are fixed even in discovery - "from scratch" means layout,
structure and components, not a rebrand.

The discovery brief deliberately never mentions the course page. Anchoring it
there would reproduce extraction wearing a different hat and prove nothing.
First artifact: Stitch project `4487418121858436329`, which produced a system it
called "Artifact Editorial" and, unprompted, rejected the logo wall, the
testimonial carousel and the repeated "Book a call".

Three confusions removed while writing this up:

1. **"Held until the read is in" hid a date.** The 2.4 gate needs a read due
approximately 2026-09-17 - 28 days after the `e1fa5409d` DEPLOY, which was
never confirmed. It reads as imminent and is not. Anything depending on 2.4
is parked until mid-September, and the first action on picking it up is
confirming that live date.
2. **Phase 2.5 has no spec.** 2.1 and 2.2 each got one; 2.5 is nine words in a
table cell. Its first deliverable is `20.05`, not code - and the binding
constraint is canon-sensitive copy across 12 pages, not the code-line cap.
Only 2 of 12 service pages carry screenshot baselines.
3. **The sequencing decision was unrecorded.** Next unit is 2.3, not 2.5,
decided by a three-lens panel that SPLIT - the ICP lens ranked service pages
first, the risk lens won on facts the ICP lens lacked (no spec, 2/12
baselines, and 2.3 rehearses the gate chain that failed in #540 at near-zero
blast radius).

## 2026-08-21 - what 15 review findings on one document taught, and one rule reversed

Closing the OKF gap on PRs #541/#543: the delivery prompt shipped and was then
Expand Down
2 changes: 1 addition & 1 deletion .okf/workflows/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
* [Blog Post Pipeline](blog-pipeline.md) - mandatory end-to-end workflow for writing/publishing blog posts, plus the execute-don't-read claims gate, the frontmatter claims check, and the `## Sources` citation convention
* [LinkedIn Post Pipeline](linkedin-post-pipeline.md) - Paul Keen voice rules and posting workflow
* [CSS Maintainability Redesign](css-maintainability-plan.md) - approved plan for hand-editable CSS + FL-Builder retirement
* [Rescue Room rollout sequence](site-redesign-rollout.md) - why phases are ordered by whether layout moves, why blog runs before site-wide chrome, why phase status must be checked against git rather than the plan table, and the gates that block regardless
* [Rescue Room rollout sequence](site-redesign-rollout.md) - why phases are ordered by whether layout moves, why blog runs before site-wide chrome, why phase status must be checked against git rather than the plan table, and the gates that block regardless; plus the extraction-vs-discovery lane split and the 2.4 gate date
* [Visual Scroll Gate](visual-scroll-gate.md) - blocking pre-handback visual walk for content/visual changes
* Test suites, rake tasks, and the visual-regression gate live in [test-gates](/build/test-gates.md) (`workflows/testing.md` was squashed into it 2026-08-20 - it duplicated the gate rules and still carried the superseded "run both suites per commit" instruction)
* [Analytics Access](analytics-access.md) - live GA4 + Search Console MCP servers, correct property IDs, credential split, data-lag traps, and why GA4 sessions must be reconciled against GSC clicks before being quoted
Expand Down
36 changes: 34 additions & 2 deletions .okf/workflows/site-redesign-rollout.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,8 @@ tags: [design, rollout, sequencing, decision, adr]
status: stable
generated:
by: claude/opus-5
at: 2026-08-20T23:11:35Z
timestamp: 2026-08-20T23:44:03Z
at: 2026-08-21T10:57:01Z
timestamp: 2026-08-21T10:57:01Z
---

# Why this concept exists
Expand Down Expand Up @@ -119,6 +119,38 @@ learning whether the design engages anyone before the whole site commits to it.
moves PDFs too. Scope tripwire: `macos/{desktop,mobile}/course/chapter.png`
must come out byte-identical.

# Two lanes: extraction governs, discovery explores

Since 2026-08-21 the redesign runs an **extraction** lane and a **discovery**
lane at once, and conflating them is the live confusion risk.

* **Extraction governs.** ADR-0003 is the decision of record and says plainly
that it is "extraction and propagation, not a redesign" - the system is taken
from the two pages already implementing it (course page,
`/services/vibe-code-rescue/`). 2.1/2.2 shipped it to the blog.
* **Discovery has no authority.** A from-scratch exploration (Paul, 2026-08-21)
runs ALONGSIDE extraction, not instead of it. Its brief deliberately never
mentions the course page - anchoring it there reproduces extraction wearing a
different hat and proves nothing. Output is candidate designs, never a PR.
* **Brand invariants are fixed even in discovery**: logo, ruby `#cc342d`,
display face, cover system. "From scratch" means layout, structure and
components.
* **Switching lanes costs shipped work.** Discovery wins only via a superseding
ADR carrying evidence, because 2.1/2.2 already shipped the extracted system to
the blog - 77% of the site's Google traffic.

A discovery lane does not consume WIP: it produces nothing mergeable, so it
cannot collide with the delivery lane. That is continuous discovery, not a third
parallelism exception.

# The 2.4 gate is time-bound, and "held until the read is in" hides the date

The homepage phase is gated on a blog engagement read due **28 days after the
`e1fa5409d` deploy, approximately 2026-09-17** - and that clock starts at the
first production DEPLOY, which was never confirmed. Writing the read up early
does not unblock anything; it pre-writes a conclusion the data cannot support.
Confirm the live date first, because the window is measured from it.

# Citations

[1] `docs/projects/2608-site-design-system/20-29-strategy/20.01-rollout-plan.md`
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -238,6 +238,38 @@ bot-filtered): blog pages **25.2% avg scroll depth, 26.3s avg engagement,
- Watch Clarity recordings of ≥20 post sessions in week one after ship — the
qualitative gate stays primary at this traffic.

**The 2.4 gate is time-bound, and the date is NOT soon (recorded 2026-08-21).**
"Held until the read is in" reads as imminent; it is not. Per
[40.01](../40-49-measurement/40.01-blog-engagement-baseline.md) the read is due
**28 days after the `e1fa5409d` deploy — ≈2026-09-17**, and that clock starts at
the first production DEPLOY, which was never confirmed (deploys were managed by
another session at merge time). So:

* Writing the read up before the window closes does not unblock 2.4 — it
pre-writes a conclusion the data cannot support.
* Anything that depends on 2.4 is parked until mid-September. Plan around it
rather than waiting on it.
* **First action when picking this up:** confirm the live date of `e1fa5409d`,
because the whole 28-day window is measured from it and it is currently
unknown.

**Sequencing decided 2026-08-21 (three-lens panel, recorded here because it
deviates from "biggest ICP impact first").** Next unit is **2.3 course-single**,
not 2.5. The panel split — the ICP lens ranked service pages first (they are the
worst ICP betrayal per unit of traffic, at the highest purchase intent), the
risk lens ranked 2.3 first and won on facts the ICP lens did not have:

* **2.5 has no spec.** 2.1 and 2.2 each got one (20.03, 20.04); 2.5 exists as
nine words in a table cell. Its first deliverable is `20.05`, not code.
* **Baseline coverage on service pages is 2 of 12** — ten money pages would ship
visually blind.
* 2.3 is ~47 lines, baseline-covered, and rehearses the exact gate chain that
failed in #540 (merge-base run, CI baseline record, browser-computed seam/AA)
at near-zero blast radius, before that chain is trusted across 12 money pages.
* The plan already sequences 2.3 "immediately after 2.2", and 2.2 shipped
2026-08-20 — so 2.3 is overdue, not a detour.


### 2.4 (homepage) carries an extra, blocking gate

The homepage cut removes the twelve service tiles and the framework logo grid.
Expand Down
57 changes: 57 additions & 0 deletions docs/projects/2608-site-design-system/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,48 @@ mobile; and a lead conversion event exists so the next change can be measured.
page, and `/services/vibe-code-rescue/` as a dark-variant campaign page.
Phase 1a is unblocked — see [20.02](20-29-strategy/20.02-phase-1a-plan.md).

## Two lanes — read this before changing any design artifact

Since 2026-08-21 this project runs **two lanes at once**, and confusing them is
the failure this section exists to prevent.

| Lane | Authority | Produces | Status |
|---|---|---|---|
| **Extraction** (governing) | **ADR-0003** — the decision of record | merged CSS, shipped phases | active; 2.1/2.2 shipped, 2.3 next |
| **Discovery** (exploration) | **none** — informs a future decision | candidate designs only, never a PR | opened 2026-08-21 (Paul) |

**Extraction is still the decision.** ADR-0003 is explicit: *"this ADR is not
proposing a new language… That makes this extraction and propagation, not a
redesign."* The system is taken from the two pages that already implement it —
the course page and `/services/vibe-code-rescue/`. Nothing below changes that.

**Discovery answers a different question:** what would a designer produce for
this ICP with no anchor at all? Paul asked for it 2026-08-21 *alongside*
extraction, explicitly not instead of it. Its brief deliberately never mentions
the course page — anchoring it there would reproduce extraction wearing a
different hat and prove nothing.

**Fixed even in discovery** (ADR-0003 brand invariants, not up for exploration):
logo, ruby `#cc342d`, display face, cover system. "From scratch" means layout,
structure and components — a rebrand was not asked for.

**Discovery artifacts so far** — Stitch project `4487418121858436329`
("JetThoughts — From-Scratch Exploration"), generated 2026-08-21. It produced a
system it named *"Artifact Editorial"*: warm paper `#fbf9f8`, Source Serif 4
headlines with Hanken Grotesk body, sharp 0px corners, ruby reserved for
critical actions only, evidence-over-assertion structure. Unprompted, it
rejected the logo wall, the testimonial carousel and the repeated
"Book a call". A Claude Design project (*JetThoughts — Rescue Room*, 14
previews) predates this and renders the EXTRACTED system — do not confuse the
two.

**What it would take for discovery to win:** a superseding ADR, with evidence
that it beats the extracted system for the ICP. Until that exists, discovery
output has **no authority** and must not be implemented. The cost of switching
is not theoretical: 2.1 and 2.2 already shipped the extracted system to the
blog, which carries 77% of the site's Google traffic.


## Current state

**Re-sequenced 2026-08-20 (Paul): BLOG FIRST** — confirm engagement on the
Expand Down Expand Up @@ -79,6 +121,21 @@ estimated) the cheapest viable test needs 192 days.

## Outstanding

**Phase 2.5 has no spec — write `20.05` before any 2.5 code.** 2.1 and 2.2 each
got a written spec (`20.03`, `20.04`); 2.5 is nine words in the Phase 2 table:
"stock photo → month-one card, decision table, 4-step timeline". Found
2026-08-21 while sequencing. Two things the spec must settle, because they are
not CSS decisions:

* The real bulk of 2.5 is **per-page frontmatter copy ×12**, not stylesheet —
and that copy is canon-sensitive. `content/services/fractional-cto/index.md`
already carries "15+ years of industry experience" in its FAQs, the exact
figure class corrected on 2026-08-14. Copy review, not the ~500-line code cap,
is the binding constraint.
* **Only 2 of 12 service pages have screenshot baselines** (`fractional_cto`,
`app_web_development`). Ten ship visually blind unless coverage is added
first — the plan's own 0.3 coverage rule applies.

**Regenerate root `DESIGN.md` against ADR-0003.** It still frames dark
JetVelocity as *"normative for new brand/conversion surfaces"*, calls LIGHT
page chrome *"legacy/incumbent"*, and specifies `#1a8cff` primary buttons —
Expand Down