Repository navigation
OKF: route design review through /stitch-design - #523
Merged
Merged
Conversation
Paul, 2026-08-21: "for design review use /stitch-design to provide feedback and use it for critical stuff to consult when it's not clear." Recorded in workflows/review-swarm.md next to the taste pass, and surfaced from design/index.md. Stitch reviews a change against the DESIGN SYSTEM rather than against taste - which is what a generic critic gives you, and why generic critics keep proposing recolours the anchor text already ruled out. It is also the consult for a critical call that is genuinely unclear: input BEFORE deciding, not instead of deciding. Decide-don't-wait still holds; stitch informs a call, it never owns one and is never grounds to park a decision. Two boundaries recorded because both are easy to get wrong: * It COMPLEMENTS the rendered gates rather than replacing them. Baselines and the scroll gate check what SHIPPED; stitch checks what was INTENDED. A change can match its baseline exactly and still be wrong against the system, and a stitch-approved design can still ship broken. * Its output is scoped like any critic's - a punch-list of surgical fixes, not a licence to redesign a working page. Deliberately NOT recorded: that a parallel PR currently owns the Linux baseline re-record (Paul, same message). The accepted-debt POLICY already lives in build/test-gates.md; who holds the work this hour is a state snapshot that would rot within days. okf validate --strict conformant, no warnings on either edited file; bin/hugo-build clean. Bundle only. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Contributor
|
Important
This repository does not receive automatic reviews because it has fewer than 10 stars. ⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
… the mandatory route **The rule could have caused the exact failure it prevents.** "Route design review through /stitch-design" did not say WHICH design system stitch should load, and there are three: | Surface | Source | | |---|---|---| | Blog cover images | `.stitch/design.md` | "The Obsidian Engine" — DARK, 2400x1260 | | Site chrome and pages | `.okf/design/site-palette.md` | LIGHT (ADR-0003), confirmed by Paul 2026-08-21 | | Course pages | `.stitch/course-taste-design.md` | taste-scoring anchor | `.stitch/design.md` is the COVER project, not the site. Point stitch at it while reviewing a light page and it judges light chrome against dark cover tokens and recommends the recolour ADR-0003 explicitly rules out — the precise failure this route exists to prevent. The surface table is now the first thing the rule says. **An OKF sentence an agent never reaches is worthless.** AGENTS.md sends every session through `docs/workflows/flow-router.md`; that router routed HTML/CSS to css-consolidation only, `new-page.md`'s Evaluate step named Impeccable alone, and review-swarm step 2 still spawned a generic DESIGN critic. An agent following the canonical flow would finish without ever seeing the rule. Wired into all three, each carrying the surface warning so the routing cannot be followed into the wrong system. Generalisable, and worth the note: recording a rule in the bundle is not the same as putting it ON THE PATH. The bundle is what a session reads when it goes looking; the router is what it reads when it does not. okf validate --strict conformant; bin/hugo-build clean. Docs + bundle only. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
… list **The follow-up commit edited a concept without refreshing its surfaces.** It added the surface-to-source table and the routing wiring, but left review-swarm.md's timestamp at the pre-edit value, left workflows/index.md describing only "the two-critic pattern and its failure modes", and left the log entry claiming only two files changed when five did (three bundle files plus flow-router.md and new-page.md). Both halves matter and for different reasons: a stale timestamp loses conflict ordering during concurrent maintenance, and a stale index means a cold session browsing the bundle cannot discover the rule from its owning listing. All three refreshed; the timestamp is a measured `date -u` value. **A sentence rendered as a broken list.** A leading-space hyphen mid-sentence opens an unordered-list item, splitting the clause and orphaning the text after it. Joined into one paragraph. The log entry now also records the two things review caught in the first draft - that it named no design source among three, and that it lived in the bundle but not on the mandatory path - because both are the kind of mistake that repeats. okf validate --strict conformant; bin/hugo-build clean. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Two findings, both about the routing I added flattening a nuance the source concepts already carried. **"Site pages are LIGHT" would have had a critic flag intentional dark design.** site-palette.md says it plainly: "Light is the default, not a monopoly" — three surfaces keep dark BY DESIGN and anything else going dark is the defect. Blog cover art; ONE dark proof band per page; and `/services/vibe-code-rescue/`, a dark variant of the same tokens rather than a second design system. A reviewer following my flat summary would have recommended recolouring a deliberate campaign landing page. Now stated as default-plus-named-exceptions in the router, the concept's surface table, and the new-page evaluate row. **The route sent every surface into a course-scoped playbook.** review-swarm's step 2 diffs content against the COURSE canon and its taste pass scores against `.stitch/course-taste-design.md`. Since AGENTS.md makes the router mandatory, site and blog reviews would have collected findings from rules that do not govern those pages. The loop now declares its scope up front, and the router says to take the stitch step and the render gate from it while skipping the course-canon steps off-surface. Both are the same failure: summarising a source into a routing line drops the qualifier, and the summary is what gets read. When a route points at a concept, the exceptions travel with it or the route is wrong. okf validate --strict conformant; bin/hugo-build clean. Docs + bundle only. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…esign surface **new-page.md §4 instructed new pages to use `--color-primary` (#1a8cff)** — the token Phase 1a.2 DELETED in #518. `var(--color-primary)` now resolves to nothing and CSS drops the declaration silently, so the paved path was producing invisible breakage on the newest pages. Found while fixing the contradiction review flagged; it is the more serious half. **And §4's visual language pointed at `.stitch/design.md`** while the gate added lower in the same file says that file is the dark COVER system and using it on a page yields the forbidden recolour. One document, two contradictory sources. §4 now names `.okf/design/site-palette.md` (LIGHT by default, three deliberate dark surfaces) and sends in-body SVG to the house spec. **There are four design sources, not three.** In-post SVG, Mermaid diagrams and LinkedIn exhibits are governed by `.okf/design/house-visual-spec.md` (hand-drawn style, 2-2.5px strokes, semantic colour — green = money ONLY, labels INSIDE shapes), with social assets also under `linkedin-posts/README.md`. Omitting that row would have sent a diagram review through the page palette and missed its typography and mobile rules entirely. Added to the concept table and the router. Pattern across this branch, now three for three: every time a routing summary compressed a source, it dropped the qualifier that made the source correct — the exceptions, the scope, or the surface it applies to. okf validate --strict conformant; bin/hugo-build clean. Docs + bundle only. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…superseded **P1: I mandated a gate with no way to run it.** All three stitch skills GENERATE — `stitch-design` makes screens, `stitch-design-taste` makes a DESIGN.md, `stitch-loop` iterates — and the MCP surface is create/edit/apply with no critique verb. "Route design review through stitch" was therefore an instruction an agent could only improvise, or satisfy by generating a screen nobody asked for. Contract now explicit: render at 1280x800 and 390x844 first (stitch reviews an image, not a URL), NAME the governing source and paste its rules in (stitch assumes whatever was last loaded), ask for a DELTA against those rules rather than an opinion, and verify each item against the render. If a step cannot be performed, report the gate DID NOT RUN rather than substituting a generic design opinion — that substitution is the failure this route exists to prevent. **Root DESIGN.md contradicted the resolved palette, and would have been followed.** It declares dark JetVelocity "normative for new brand/conversion surfaces", calls light chrome "legacy/incumbent", and specifies `#1a8cff` primary buttons. ADR-0003 resolved chrome to LIGHT on 2026-08-20, and #518 DELETED that token. An agent building a new conversion page today would have gone dark with a token that resolves to nothing. Added a superseded-in-part banner naming all three reversals and corrected the two-layers section; full regeneration is a separate job and is called out as outstanding rather than half-done here. **Precedence for course visuals.** An SVG inside a course lesson matched two rows. Use BOTH, course first: the course file declares itself the single source of truth for course in-post visuals, the house spec carries stroke, semantic colour and label rules the course file does not repeat. Taking either alone drops half the governing rules. okf validate --strict conformant; bin/hugo-build clean. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…compression pattern **site-palette.md is the LIGHT authority and never mentioned root DESIGN.md, which says the opposite.** DESIGN.md frames dark JetVelocity as normative for new conversion surfaces, calls light chrome "legacy/incumbent", and specifies a token deleted in #518. The banner added there yesterday helps someone who opens that file; it does nothing for someone who opens the authority and reasonably assumes it is uncontested. site-palette now names the sibling, states which wins for page design, and records that regeneration is outstanding. The general form is worth the line it costs: an authority that does not name what contradicts it leaves the reader to discover the conflict by shipping the wrong thing. **Routing text drops the qualifier that made the source correct.** Adding ONE routing rule took five review rounds and every finding had that shape: * "site pages are LIGHT" — lost three surfaces that are dark BY DESIGN * "detail in review-swarm" — lost that the loop's canon/taste steps are COURSE-scoped * "there are three sources" — lost the in-post SVG/Mermaid/social fourth * "route review through stitch" — lost that stitch has no review verb at all Routing text is the most-read and least-reviewed prose in a repo, and the compression that makes it readable is what makes it wrong. Carry the qualifier into the routing line — "LIGHT by default, three documented exceptions" is barely longer than "LIGHT" and is the difference between a correct review and a recolour of a deliberate dark page. And check the destination is EXECUTABLE before making a route mandatory: a gate an agent cannot run gets improvised, which is worse than no gate because it reports as done. Recorded alongside: a rule in this bundle is not ON THE PATH. AGENTS.md routes sessions through docs/workflows/flow-router.md, so a concept nobody is routed to is read only by sessions already looking for it. okf validate --strict conformant, no warnings on either edited concept; bin/hugo-build clean. Bundle only. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Review's last finding argues /stitch-design cannot perform the delta review and the route should use /impeccable critique instead. The technical half is correct - all three stitch skills generate, and the MCP surface has no critique verb. But Paul's 2026-08-21 instruction named stitch specifically, and he has not seen this objection, so silently rerouting his gate to a different tool would be substituting my judgment for a decision he made. Resolved by honouring the instruction and making the gap visible instead: * The route stays /stitch-design with the explicit render/anchor/delta contract. * If stitch returns a generated screen rather than a delta, pair it with /impeccable critique against the SAME named source and SAY which produced the findings. A tooling gap gets reported, never silently rerouted. * The concept carries an explicit open question for Paul: stitch has no critique verb, so if a delta review is the intent, either a wrapper is needed or impeccable should carry this gate with stitch reserved for generation. This keeps the gate runnable today without pretending the tooling fits, and puts the decision where it belongs rather than burying it in a routing line. okf validate --strict conformant; bin/hugo-build clean. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Paul reversed his own instruction the same day: "i was wrong, you should use `/impeccable critique`." Review had established the gap — all three stitch skills GENERATE (`stitch-design` screens, `stitch-design-taste` a DESIGN.md, `stitch-loop` iterations) and the MCP surface is create/edit/apply with no critique verb, so a review routed there returns a generated screen or an improvisation. Switched at all four sites: workflows/review-swarm.md, design/index.md, and the two repo docs on the mandatory path (flow-router.md, new-page.md). The retraction is recorded at each site rather than silently overwritten — a reader who remembers the first instruction learns why it changed instead of wondering which is current. **What survived the tool change is the part that mattered: the ANCHOR.** Four design sources, and the wrong one inverts the verdict no matter which critic runs. The surface-to-source table, the course-visual precedence rule (use both, course first), and the render / name-the-anchor / ask-for-a-delta contract are all tool-independent and unchanged. The tool turned out to be the least durable thing in the rule — worth remembering next time a routing rule is written around a command name. Private memory corrected rather than accumulated, so the retracted instruction cannot resurface from there. okf validate --strict conformant; bin/hugo-build clean. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…real home The banner I added to DESIGN.md earlier today said the full regeneration "is tracked separately". Nothing tracked it. The 2608 project had no outstanding section at all, so the only record of the work was a sentence inside the very file that cannot be trusted — which is to say, no record. Now an **Outstanding** section in docs/projects/2608-site-design-system/README.md with the scope written out: reconcile the two-layers section with ADR-0003, strip every --color-primary reference including the primary-button spec, restate .stitch/design.md as cover-scoped rather than "the site design system", and regenerate .impeccable/design.json if it encodes the same palette — verified that file exists, and /impeccable critique now carries the design-review gate, so it would score pages against stale values. DESIGN.md's banner and site-palette both point at it. Worth keeping as a shape: **"tracked separately" is a claim like any other.** It is the most natural thing to write when deferring work and among the least likely to be checked, because it reads as process rather than as fact. If no tracker can be named, the work is not deferred — it is dropped. okf validate --strict conformant; bin/hugo-build clean. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Bundle-only. One new standing rule, recorded so agents other than this session
can act on it.
The rule
Paul, 2026-08-21: "for design review use /stitch-design to provide feedback and
use it for critical stuff to consult when it's not clear."
Recorded in
workflows/review-swarm.mdbeside the taste pass, and surfaced fromdesign/index.md.Why it belongs in the bundle rather than a session's memory: stitch reviews a
change against the design system, not against taste — which is what a generic
critic gives you, and why generic critics keep proposing recolours the anchor
text already ruled out. That distinction is only useful if every agent has it.
Two boundaries, both easy to get wrong
the scroll gate check what shipped. Stitch checks what was intended. A
change can match its baseline exactly and still be wrong against the system,
and a stitch-approved design can still ship broken.
not a licence to redesign a working page.
Also recorded: it is the consult for a critical call that is genuinely unclear —
input before deciding, not instead of deciding. Decide-don't-wait still
holds; stitch informs a call, never owns one, and is never grounds to park a
decision on Paul.
Deliberately not recorded
That a parallel PR currently owns the Linux baseline re-record (Paul, same
message). The accepted-debt policy already lives in
build/test-gates.md;who holds the work this hour is a state snapshot that would rot within days.
Gates
okf validate --strictconformant, no warnings on either edited file.bin/hugo-buildclean. Bundle only — no code, templates, or CSS.🤖 Generated with Claude Code