diff --git a/.claude/plans/extract-general-pattern-skill.md b/.claude/plans/extract-general-pattern-skill.md new file mode 100644 index 000000000..a2d5e6649 --- /dev/null +++ b/.claude/plans/extract-general-pattern-skill.md @@ -0,0 +1,96 @@ +# Plan: `extract-general-pattern` skill + +## Goal + +A new skill that reads one of your concrete `/designs` posts (e.g. the ecommerce-scanner or +self-healing-storefront HLDs) and turns the **reusable patterns intertangled inside it** into +**generalized, standalone `/designs` posts** — the specific business stripped out, only the +reusable mechanism left. + +## Scope for v1 (explicitly narrowed per our Q&A) + +- **IN:** source design post → **disentangle** its many intertangled patterns → **AskUserQuestion + to agree** on which to extract → produce **one general `/designs` post per approved pattern**, + **one at a time with a checkpoint between each** → hand each draft to `refine-design-post`. +- Extracted posts are **standalone** (no backlink to the source post). +- **LATER (out of scope, noted in SKILL.md "Not yet"):** actually exporting to another external + blog/repo; batch-producing all posts without per-post checkpoints; a deterministic transformer. + +## The flow the skill encodes + +1. **Read the source post** (a `/designs/*.mdx`). Parse its section structure (the HLD skeleton: + §6.2 Architecture Options, §6.5 Key Design Decisions, §7 Components/Data Model, §7.3 Data Flows, + §8 Use Cases, §10 Diagrams, §11 NFRs). These sections are where reusable patterns hide. + +2. **Disentangle → surface the patterns.** Produce a candidate list: each pattern gets + - a **name** (the reusable mechanism, e.g. "crawl-then-enrich prospect pipeline", + "build-vs-buy comparison-matrix decision", "self-healing experiment loop", + "confidence-tagged diagram provenance"), + - **where it lives** in the post (section refs), + - a **one-line reusable claim** ("what stays true when you remove this specific business"), + - a proposed **`kind:`** (`system-design` / `backend-design` / `frontend-design` / + `agent-design` / `tooling-cli-design`) and a proposed **slug** `design-`. + +3. **Agree via AskUserQuestion.** Present the candidate patterns as options (multiSelect) so you + pick which become posts. Nothing is written before you choose. (This is the "told to apply and + agree on patterns via ask-question tool first" requirement.) + +4. **Per approved pattern, one at a time (checkpoint between each):** apply the **single-post + authoring guidance** (the core of SKILL.md) to generalize that one pattern into a new draft + `/designs` post: + - **De-specify:** remove personas/GTM/employer specifics, keep the abstract mechanism + (reuses `refine-design-post`'s GENERALITY dimension + STYLE-GUIDE). + - **Frontmatter:** `slug: design-`, `kind:`, `draft: true`, + `sidebar_position:` = current max+1 (currently 21 → next is 22), `authors: [oeid]`, + a `description:` (~50–160ch), `tags:`. **No `source:` provenance block** (that's repo-work + specific and the post is standalone). + - **Body:** de-em-dash (the `em-dash-voice-hook.sh` **BLOCKS** `—` in `designs/*.mdx`); + MDX-clean (`
`, escape stray `<`, `{braces}`); mermaid with **no hardcoded fills** so + the theme colors it; keep the pattern's own worked example generic (not the real business). + - **Voice:** neutralize "I built this specific thing" into the reusable pattern voice. + - Then **hand to `refine-design-post`** for the GENERALITY/CLARITY audit with your approval. + - **Checkpoint:** confirm this post before starting the next approved pattern. + +5. **Validate:** `make build` (or at least the em-dash + MDX + `validate-seo --file` checks) on + each new post; note the draft stays `draft: true` until you publish. + +## Files to create + +``` +.claude/skills/extract-general-pattern/ + SKILL.md # the flow above: disentangle → AskUserQuestion agree → per-pattern single-post + # authoring guidance → hand to refine-design-post; frontmatter/MDX/em-dash rules; + # a "Not yet" section for the deferred external-export + batch modes. + PATTERN-TYPES.md # (living) a small catalog of the recurring pattern SHAPES worth extracting from + # an HLD (architecture-option tradeoff, pipeline/dataflow, decision-record, + # NFR strategy, use-case model, diagram-provenance) with how to recognize each. + # Grows as you approve/reject candidates — the "sharpen with every post" pattern + # refine-design-post uses. +``` + +No new Node transformer, hook, Make target, or generated asset in v1 — this is a **judgment-guided +authoring skill** (like `import-marketplace-plugin`), not a deterministic pipeline (like +`import-co-design`). It leans on existing enforcement (em-dash hook, validate-seo, refine-design-post). + +## Registration touchpoints (keep the repo's conventions) + +1. **`CLAUDE.md` Skills map table** — add a row for `extract-general-pattern` under the authoring + cluster, cross-linking `refine-design-post`, `import-co-design`, `author-blog-post`, `manage-hubs`. +2. **Memory** — add one `reference`/`project` memory + a `MEMORY.md` index line pointing at the skill + and its v1 scope (so a future session knows the external-export step is deferred). +3. No `settings.json` hook change (no new automated behavior). + +## What I will NOT do in this plan + +- Not write any extracted pattern post yet (the skill is the deliverable; running it on the two + posts is a follow-up you trigger). +- Not build the external-blog export mechanism (deferred by your "move later"). +- Not touch the two source posts. + +## Verification + +- Lint the new SKILL.md frontmatter (`name`/`description` present, description is a single rich line + in house style). +- Dry-run the *reasoning* of step 1–3 against the ecommerce-scanner post in the plan discussion (show + you the candidate patterns it would surface) so you can sanity-check the disentangling before we + ever author a post — optional, on your say-so. diff --git a/.claude/plans/swirling-dazzling-pony.md b/.claude/plans/swirling-dazzling-pony.md new file mode 100644 index 000000000..725f1a661 --- /dev/null +++ b/.claude/plans/swirling-dazzling-pony.md @@ -0,0 +1,105 @@ +# Plan: `extract-general-pattern` skill + +## Context + +You have concrete design posts in `/designs` (e.g. +`bytesofpurpose-blog/designs/2026-06-21-ecommerce-site-scanner-and-lead-generation-engine.mdx` +and `2026-06-22-self-healing-storefront.mdx`) that were imported from work-repo HLDs. Each of +these is a specific-business write-up, but **many reusable patterns are intertangled inside a +single post** (a build-vs-buy decision method, a crawl-then-enrich pipeline, a self-healing +experiment loop, confidence-tagged diagram provenance, and so on). + +You want to eventually **export** the reusable, generalized versions of those patterns to another +blog. We agreed to **start narrow**: v1 is a skill that turns a concrete design post into +**generalized, standalone `/designs` posts** (one per pattern) in *this same* blog. The +external-blog export and any deterministic transformer come **later**. + +This is a **judgment-guided authoring skill** (like `import-marketplace-plugin` / +`refine-design-post`), NOT a deterministic Node pipeline (like `import-co-design`). It adds no +hook, Make target, or generated asset — it leans on existing enforcement. + +## Requirements locked via Q&A + +- **Disentangle first**, then **agree on patterns via `AskUserQuestion` before writing anything**. +- **One generalized `/designs` post per approved pattern.** +- Produce them **one at a time, with a checkpoint between each** (single-post authoring guidance + applied per pattern). +- Each extracted post is **standalone** (no backlink to the source post). +- Skill **drafts** the general post, then **hands to `refine-design-post`** for the + GENERALITY/CLARITY audit (reuse, don't duplicate, that machinery). + +## The flow the SKILL.md encodes + +1. **Read the source `/designs/*.mdx`.** Parse its HLD section skeleton (§6.2 Architecture Options, + §6.5 Key Design Decisions, §7 Components/Data Model, §7.3 Data Flows, §8 Use Cases, §10 Diagrams, + §11 NFRs) — these sections are where reusable patterns hide. + +2. **Disentangle → surface candidate patterns.** For each: a **name** (the reusable mechanism), the + **section(s)** it lives in, a **one-line reusable claim** ("what stays true once the specific + business is removed"), a proposed **`kind:`** (`system-design`/`backend-design`/`frontend-design`/ + `agent-design`/`tooling-cli-design`, source of truth `scripts/lib/blog-kinds.json`), and a + proposed **slug** `design-`. + +3. **Agree via `AskUserQuestion`** (multiSelect): you pick which candidates become posts. Nothing is + written before you choose. (This is the "agree on patterns via ask-question tool first" rule.) + +4. **Per approved pattern, one at a time (checkpoint between each)** apply the **single-post authoring + guidance**: + - **De-specify** (reuse `refine-design-post` GENERALITY + `STYLE-GUIDE.md`): remove personas / + GTM / employer specifics; keep the abstract mechanism. + - **Frontmatter:** `slug: design-`, `kind:`, `draft: true`, `authors: [oeid]`, + `sidebar_position:` = current designs max + 1 (currently 21 → next 22), a `description:` + (~50–160ch for SEO/share), `tags:`. **No `source:` provenance block** (standalone). + - **Body:** de-em-dash (the `.claude/hooks/em-dash-voice-hook.sh` **BLOCKS** any `—` in + `designs/*.mdx`, incl. mermaid/frontmatter); MDX-clean (`
`, escape stray `<`, `{braces}`); + mermaid with **no hardcoded fills** (theme colors it); keep the worked example generic. + - **Voice:** neutralize "I built this specific thing" into reusable pattern voice. + - Then **hand to `refine-design-post`** for the audit with your approval. + - **Checkpoint** before starting the next approved pattern. + +5. **Validate** each new post: `make build` (or at minimum the em-dash + MDX + `make validate-seo` + `--file`-scoped checks). Post stays `draft: true` until you publish. + +## Files to create + +``` +.claude/skills/extract-general-pattern/ + SKILL.md # the flow above + frontmatter/MDX/em-dash rules; a "Not yet" section listing + # the deferred external-blog export + batch-all mode. + PATTERN-TYPES.md # (living) catalog of recurring pattern SHAPES worth extracting from an HLD + # (architecture-option tradeoff, pipeline/dataflow, decision-record, NFR + # strategy, use-case model, diagram-provenance) + how to recognize each. + # Grows as you approve/reject candidates (the refine-design-post capture pattern). +``` + +## Registration touchpoints (repo conventions) + +1. **`CLAUDE.md` Skills map table** — add a row for `extract-general-pattern` in the authoring + cluster, cross-linking `refine-design-post`, `import-co-design`, `author-blog-post`, `manage-hubs`. +2. **Memory** — add one memory file + a `MEMORY.md` index line recording the skill and that the + external-export step is deferred (so a future session knows v1 scope). +3. No `settings.json` / hook change (no new automated behavior). + +## Reused existing assets (do not reinvent) + +- `.claude/skills/refine-design-post/` — its **GENERALITY** dimension + `STYLE-GUIDE.md` + + `SECTION-QUESTIONS.md` are the abstraction/voice authority; the new skill routes to it. +- `bytesofpurpose-blog/scripts/lib/blog-kinds.json` — the `*-design` kinds + emoji. +- `.claude/hooks/em-dash-voice-hook.sh`, `make validate-seo` — existing enforcement the drafts pass. +- `import-marketplace-plugin` SKILL.md — the house shape for a judgment-guided `/designs` authoring skill. + +## Explicitly deferred (SKILL.md "Not yet") + +- Exporting to an external blog/repo (the "move later"). +- Batch-producing every approved post without per-post checkpoints. +- A deterministic Node transformer. +- The source posts are not modified; no extracted post is authored as part of building the skill. + +## Verification + +- New `SKILL.md` frontmatter has `name` + a single rich `description` line in house style. +- Sanity-run steps 1–3 **in discussion** against the ecommerce-scanner post (show you the candidate + patterns the skill would surface) so you can validate the disentangling before any post is authored — + optional, on your say-so. +- When you later run the skill for real, each produced draft must `make build` clean and pass the + em-dash hook + `validate-seo`. diff --git a/.claude/skills/extract-general-pattern/PATTERN-TYPES.md b/.claude/skills/extract-general-pattern/PATTERN-TYPES.md new file mode 100644 index 000000000..770dff5dc --- /dev/null +++ b/.claude/skills/extract-general-pattern/PATTERN-TYPES.md @@ -0,0 +1,106 @@ +# PATTERN-TYPES — the reusable shapes worth extracting from an HLD (living) + +> **What this is.** A catalog of the recurring PATTERN SHAPES that hide inside a concrete `/designs` +> post, and how to RECOGNIZE each one while disentangling (step 1 of `extract-general-pattern`). Naming +> patterns the same way across posts is what lets the skill get sharper with use. +> +> **Living file.** As the user approves or rejects candidate patterns, capture the reusable +> recognition rule back here (the same self-healing loop `refine-design-post` uses for its guides). A +> new shape the corpus reveals gets its own section; a sharpened "how to recognize" gets edited in +> place. Do not hand-curate silently — every rule should trace to a real disentangling. + +## How to use this + +When you read a source post, walk these shapes and ask, per section, "is one of these here?" Each +shape below gives: **where it lives** in the HLD skeleton, **the recognition tell**, **what the +general post keeps vs. drops**, and a **proposed `kind:`**. A single source post usually contains +several of these intertangled — that is the whole reason for the disentangle step. + +## The shapes + +### 1. Architecture-option tradeoff (a DECISION METHOD) + +- **Where:** §6.2 Architecture Options → §6.3 Comparison Matrix → §6.4 Recommendation. +- **Tell:** two or more options weighed against the same axes, then one chosen. The reusable thing is + the *method of choosing* (the axes, the comparison matrix, the recommendation logic), which is + SEPARATE from the option that happened to win. +- **Keep:** the decision axes, the comparison-matrix structure, "when you'd pick each option", the + build-vs-buy reasoning. **Drop:** the specific vendors/APIs and the specific winner as a foregone + conclusion. +- **`kind:`** usually `system-design`. + +### 2. Decision record (one D-entry = one pattern) + +- **Where:** §6.5 Key Design Decisions (the D1, D2, … entries). +- **Tell:** a titled decision with a concern, options, and a rationale. In the two seed posts these + are things like *site/traffic/contact discovery*, *scoring model*, *outreach-automation level*, + *measurement rigor across traffic levels*, *autonomy & guardrails*, *outcome attribution*, + *compliance posture*. Several of these are transferable patterns in their own right (e.g. + "measurement rigor across traffic levels" is a general statistics-under-low-traffic pattern; "autonomy + & guardrails model" is a general human-in-the-loop pattern). +- **Keep:** the concern the decision answers and the reusable rule of thumb. **Drop:** the + business-specific instantiation (what exactly was scored, whose contacts). +- **`kind:`** matches the decision's nature (`backend-design` for a data/scan decision, `agent-design` + for an autonomy/guardrails decision, etc.). + +### 3. Pipeline / dataflow (input → transform → output) + +- **Where:** §7.1 Components + §7.3 Data Flows (and often §10 sequence diagrams). +- **Tell:** a chain of stages where each stage transforms and passes on. The seed example is + "crawl-then-enrich" (discover → size → find contacts → score → act). The reusable thing is the + STAGE SHAPE and the contract between stages, not the specific enrichment sources. +- **Keep:** the stages, what each guarantees, where it can fail/retry, the mermaid flow. **Drop:** the + concrete data sources and field names tied to the business. +- **`kind:`** usually `backend-design`. + +### 4. Self-healing / closed-loop control + +- **Where:** the "target state" (§6.1) + §10 lifecycle sequence + a North Star section, taken together. +- **Tell:** a loop that measures, decides, acts, and feeds the result back to improve the next cycle + (the self-healing-storefront's experiment lifecycle: ideate → generate variant → run → attribute + outcome → adopt/rollback). The reusable thing is the LOOP and its guardrails. +- **Keep:** the loop stages, the guardrails/rollback, the "how it improves each cycle". **Drop:** the + domain being optimized (CRO, storefront conversion). +- **`kind:`** `system-design` or `agent-design` (if autonomy is central). + +### 5. Use-case / persona model + +- **Where:** §1.4 System Users & Personas, §8 Use Cases, §9 Customer Journey. +- **Tell:** a class of user with a repeatable job-to-be-done, rendered as a use-case diagram. The + reusable thing is the ROLE SHAPE ("a two-person founding team split into a technical operator and a + BD partner" generalizes to "a small team split by build-vs-sell"), not the named personas. +- **Keep:** the role archetypes and their use cases, the ``. **Drop:** named personas, + employer org structure. +- **`kind:`** `system-design`. + +### 6. NFR strategy for a class of system + +- **Where:** §11 Non-Functional Requirements (performance, security, scalability, compliance). +- **Tell:** how a whole CLASS of system meets a non-functional need — e.g. crawl-ethics + outreach-law + compliance for any scraping+outreach system, or "statistical reality for mid-market stores" (how to + get signal at low traffic). Reusable when the strategy transfers beyond the one product. +- **Keep:** the strategy and its constraints. **Drop:** the specific SLAs/thresholds/legal jurisdiction + tied to one org (generalize numbers per `refine-design-post` axis 1). +- **`kind:`** `backend-design` or `system-design`. + +### 7. Diagram / documentation convention + +- **Where:** §10 Architecture Diagrams (and the post's frontmatter `diagrams:` block). +- **Tell:** a reusable way of PRESENTING a design, not a design itself — e.g. the confidence-tagged + diagram provenance (`type` + `confidence` + `heading` per diagram), the HLD section skeleton itself, + the animated-mermaid-flow convention. Reusable as a documentation pattern for other design docs. +- **Keep:** the convention and why it helps a reader. **Drop:** the specific diagrams' content. +- **`kind:`** `tooling-cli-design` or `frontend-design` (it's about presentation). + +## Not every section is a pattern + +Executive Summary, Purpose/Context, Scope, Current-State, Problem Statement, Risks, Revision Log, and +Appendices are usually the SPECIFIC INSTANCE, not a reusable pattern — they exist to ground THIS +system. Do not manufacture a "pattern" out of them. If a candidate has no lesson once the business is +removed, that is a signal it isn't a pattern (the same finding `refine-design-post` makes: cut it). + +## Captured this session + + diff --git a/.claude/skills/extract-general-pattern/SKILL.md b/.claude/skills/extract-general-pattern/SKILL.md new file mode 100644 index 000000000..aa1f45b2e --- /dev/null +++ b/.claude/skills/extract-general-pattern/SKILL.md @@ -0,0 +1,153 @@ +--- +name: extract-general-pattern +description: Turn ONE concrete /designs post (an imported HLD like the ecommerce-scanner or self-healing-storefront) into generalized, standalone /designs posts by DISENTANGLING the many reusable patterns intertangled inside it. The flow is DISENTANGLE (read the post, surface every distinct reusable pattern — a name, where it lives, the one-line reusable claim, a proposed kind + slug) → AGREE via the AskUserQuestion tool (you pick which candidates become posts; nothing is written before you choose) → author ONE generalized post per approved pattern, ONE AT A TIME with a checkpoint between each (de-specify the business, no source: provenance, draft: true, de-em-dash, MDX-clean) → hand each draft to refine-design-post for the GENERALITY/CLARITY audit. Each extracted post is STANDALONE (no backlink to the source). Use when the user says "extract the general pattern(s) from this design post", "pull the reusable patterns out of this", "generalize this design", "this post has many patterns intertangled — separate them", or "make a general version of this design". Deferred to a later version (say so, do not build): exporting to an external blog/repo, batch-producing every post without a checkpoint, a deterministic transformer. Pairs with refine-design-post (the audit it hands off to), import-co-design + import-marketplace-plugin (which CREATE the concrete /designs posts this reads), author-post (MDX pitfalls), manage-hubs (where a pattern MAY later be cataloged). +--- + +# Extract the general pattern(s) from a design post + +Your `/designs` posts are concrete write-ups of specific systems (imported from work-repo HLDs by +`import-co-design`). Inside a single one of them, **many reusable patterns are intertangled**: a +build-vs-buy decision method, a crawl-then-enrich pipeline, a self-healing experiment loop, a +confidence-tagged diagram provenance convention. This skill pulls those threads apart and turns the +approved ones into **generalized, standalone `/designs` posts** — the reusable mechanism kept, the +specific business stripped out. + +This is a **judgment-guided authoring skill**, not a deterministic transformer. There is no Node +script, hook, or Make target to run — you read, you disentangle, you get agreement, you author. It +leans on the repo's existing enforcement (the em-dash hook, `validate-seo`) and hands the finished +draft to `refine-design-post` for the generality/clarity audit rather than re-implementing it. + +## Philosophy: the concrete post is the WITNESS; the general post is the LESSON + +A concrete design post proves a pattern WORKED in one real place — it is the witness. The general +post is the **lesson** you can carry anywhere: the same mechanism with the one business removed. The +job is not to summarize the source and not to copy it. It is to answer, per pattern, *"what stays +true here once you delete the specific company, personas, and numbers?"* — and write only that. + +Two consequences shape every step below: + +- **One source post yields MANY general posts.** The patterns are separable, so the output is + one standalone post PER approved pattern, not one summary of the whole source. +- **Standalone means standalone.** No `source:` provenance block, no "seen concretely in " + backlink, no employer trace. A reader of the general post should not be able to tell which company + it came from. (This is the strongest form of `refine-design-post`'s axis-1 GENERALITY rule; you + hand off to that skill precisely to prove the leak is gone.) + +## The flow (do these in order) + +### 1. DISENTANGLE — read the source, surface the candidate patterns + +Read the target `/designs/*.mdx` in full. The reusable patterns hide in the same HLD sections every +time, so scan these first (headings may vary; match by intent): + +- **§6.2 Architecture Options / §6.3 Comparison Matrix / §6.4 Recommendation** — a *decision method* + (how you chose among options) is almost always a pattern, separate from the option you picked. +- **§6.5 Key Design Decisions** — each decision record (D1, D2, …) is often its own pattern. +- **§7.1 Components / §7.3 Data Flows** — a *pipeline / dataflow* shape (input → transform → output). +- **§8 Use Cases / §9 Customer Journey** — a *use-case model* for a class of user. +- **§10 Architecture Diagrams** — a reusable *diagram convention* (e.g. confidence-tagged provenance). +- **§11 NFRs** — an *NFR strategy* (how you met performance / compliance / scale for a class of system). + +For each candidate pattern, capture four things (this is what you'll present for agreement): + +1. **Name** — the reusable mechanism, not the product. "Crawl-then-enrich prospect pipeline", not + "the ecommerce lead-gen engine". +2. **Where it lives** — the section(s) in the source it's drawn from. +3. **The one-line reusable claim** — what stays true once the specific business is removed. +4. **Proposed `kind:` + slug** — one of the `*-design` kinds (`system-design` / `backend-design` / + `frontend-design` / `agent-design` / `tooling-cli-design`; source of truth + `bytesofpurpose-blog/scripts/lib/blog-kinds.json`) and a slug `design-`. + +`PATTERN-TYPES.md` (next to this file) is the catalog of the recurring pattern SHAPES and how to +recognize each — read it before disentangling so you name patterns the same way across posts. It is a +living file: as the user approves or rejects candidates, capture the reusable recognition rule back +into it (the same self-healing loop `refine-design-post` uses for its guides). + +### 2. AGREE — get sign-off on the patterns via the AskUserQuestion tool (before writing anything) + +**Nothing is written to disk until the user picks.** Present the candidates through the +**AskUserQuestion tool** (multiSelect): one option per candidate pattern, the label being the pattern +name and the description being its one-line reusable claim + where it lives. The user selects which +become posts. This gate is the whole point of the skill's first half — you disentangle, they decide. + +If the user names a specific pattern up front ("just pull out the self-healing loop"), you can skip +the enumeration and confirm that single pattern instead — but still confirm before authoring. + +### 3. AUTHOR — one generalized post per approved pattern, ONE AT A TIME + +Produce the approved posts **one at a time, with a checkpoint between each** (do NOT batch them). The +guidance below is written for making ONE post; apply it per approved pattern, then confirm that post +with the user before starting the next. Each post is a normal `/designs` post, so it obeys +`author-post`; the pattern-specific rules are: + +**De-specify (the core move).** Remove personas, go-to-market, employer names, internal codenames, +real scale numbers, and one-off internal process. Keep the abstract mechanism. This is +`refine-design-post`'s axis-1 GENERALITY rewrite applied at AUTHORING time: "at $EMPLOYER we ran 40k +RPS through the Foobar service" becomes "a high-throughput service under sustained load". If a passage +has no lesson once the specifics are gone, it does not belong in the general post. + +**Frontmatter (match the other design posts, with two deliberate differences):** +- `slug: design-` +- `kind:` — the chosen `*-design` kind +- `sidebar_position:` — current designs max + 1 (check with + `grep -h '^sidebar_position:' bytesofpurpose-blog/designs/*.mdx | grep -oE '[0-9]+' | sort -n | tail -1`) +- `draft: true` (always; it stays draft until the user publishes) +- `authors: [oeid]`, `tags:` (general tags, not the business), and a `description:` (~50 to 160 chars, + powers the social card + share text; `validate-seo` checks it) +- **NO `source:` provenance block** and **NO backlink** — this is what makes it standalone. (The + concrete posts carry `source:` because they're imports; a general pattern has no single source to + cite.) + +**Body rules that keep the build green (non-negotiable):** +- **De-em-dash.** `.claude/hooks/em-dash-voice-hook.sh` **BLOCKS** any `—` (U+2014) — and any `--` + used as a sentence dash — anywhere in `designs/*.mdx`, including inside mermaid and frontmatter, + with no code-fence exemption. Write with commas / colons / period-splits from the start. +- **MDX-clean.** Use `
` not `
`; escape a stray `<` before a space/digit (`< 50ms` → + `< 50ms`); escape or fence `{braces}` that aren't real JSX. See `author-post`. +- **Mermaid with NO hardcoded fills** so the theme colors it light and dark. Escape a label dash to + the `—` entity if you truly need one (the hook greps source bytes and never sees the entity). +- **Keep the worked example generic.** A pattern post benefits from ONE concrete illustration, but + invent a neutral one (a generic "orders service", a generic "content platform"), never the real + business the source came from. + +**Voice.** Neutralize "I built this specific thing" into the reusable pattern voice ("this pattern +applies when…", "the mechanism is…"). Preserve the author's texture per `refine-design-post`'s +"preserve the voice" list (question-hook openings, bold-key-term, the long-then-short cadence). + +### 4. HAND OFF to refine-design-post, then checkpoint + +After drafting each general post, **hand it to `refine-design-post`** for the full audit — most +importantly axis 1 (GENERALITY / leak-risk), which is the proof that the de-specify worked. Walk its +findings with the user, apply the approved trims, and let its capture step record any new rule. THEN +**checkpoint**: confirm this post is done before starting the next approved pattern. + +### 5. VALIDATE + +Each new draft must build clean. Run `make build` (or at minimum the em-dash hook fires on write, and +`make validate-seo` `--file`-scoped covers the frontmatter). The post stays `draft: true` until the +user runs `publish-site`. + +## Not yet (deferred — say so, do not build) + +These were explicitly moved to a later version. If the user asks for them, name them as the next step, +do not silently build them: + +- **Export to another blog / repo.** v1 keeps every general post in THIS `/designs` blog. The + external-export mechanism (portable, component-free markdown to a staging dir) is a later version. +- **Batch mode.** v1 authors one post at a time with a checkpoint between each; a "generate all + approved posts at once" mode is deferred. +- **A deterministic transformer.** v1 is judgment-guided (like `import-marketplace-plugin`), not a + Node pipeline (like `import-co-design`). A transformer only makes sense once the shape is proven by + hand on several posts. +- **Cataloging on a hub.** A general pattern MAY later belong on the `/craft` Patterns 🧱 / Techniques + 🔩 hub (see `manage-hubs`). v1 does not auto-file it there; that is a deliberate separate decision. + +## Pointers + +- `refine-design-post` (+ its `STYLE-GUIDE.md` / `SECTION-QUESTIONS.md`) — the audit this hands off + to; its axis-1 GENERALITY rule is the same de-specify move applied at review time. +- `import-co-design` / `import-marketplace-plugin` — how the concrete `/designs` posts this reads were + created; the house shape for a judgment-guided `/designs` authoring skill. +- `author-post` — MDX pitfalls + the blog `kind:` / `sidebar_label` system. +- `bytesofpurpose-blog/scripts/lib/blog-kinds.json` — the `*-design` kinds + their emoji. +- `manage-hubs` — the durable Patterns/Techniques hub a general pattern may later be cataloged on. diff --git a/CLAUDE.md b/CLAUDE.md index caa6d721c..c10b361bb 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -468,6 +468,7 @@ via the root `Makefile`. Secrets in the gitignored root `.env`. | Import from NotePlan | `import-noteplan` | migrate content out of NotePlan's `🏡 Personal/🏡📋 Lists` folder onto the blog **non-destructively**: migrating COPIES a link/section into a real post and APPENDS a `## 🔗 Migrated to Blog` provenance table to the NotePlan file (records the true final blog URL, knowable at draft time since slugs are absolute + deterministic) — it NEVER removes a line the user wrote. Deterministic, idempotent Node transformer (`import-noteplan.js`: `--inventory`/`--append-migration`/`--verify`/`--snapshot`/`--audit`) whose non-destructive contract is proven byte-for-byte (original is always an exact PREFIX) and guarded fail-closed by the `noteplan-no-drop-hook.sh` PostToolUse hook (blocks any edit that drops a link/line vs a session baseline). Tracks one task PER FILE; classifies each cluster via `organize-post` then drafts `draft: true` posts. Allow/deny list keeps private notes (Shopping/Brag Sheet/Habits/…) off the blog by default. Pairs with `organize-post`, `mature-content`, `groom-initiatives`, `author-post`, `audit-glossary-links`, `validate-links`, `publish-site` | | Import a personalbook role | `import-personalbook-role` | consolidate a role from the private **personalbook** knowledge base into one durable `/journey/roles/.md` portrait (why the role matters · the skills I use · the KINDS of artifacts I produce · the habits I keep). **STRICTLY READ-ONLY on personalbook** (never writes a marker/note/edit back — the old personalbook-side flow's coupling is what this replaces): reads `Overview.md` + `skills/` + `knowledge/` + `habits/` (+ `Activities.md` as influence) and publishes only the transferable half; the private half (intent triad `obligations`/`desires`/`motivations`, dated todos, family/finance/medical, raw artifact bodies) stays behind. **Anti-drift**: a Step 0 reconcile re-reads personalbook's role-STRUCTURING skills (`extract-role-skills`/`establish-role-habits`/`establish-role-learning`/`structure-role-purpose`/`extract-obligations-desires`) so the model of role anatomy never goes stale (`role-anatomy.json`, keyed to personalbook HEAD). **Fail-closed guards**: `personalbook-read-only-hook.sh` BLOCKS any personalbook write; `make validate-role-privacy` (+ blocking hook) BLOCKS a post carrying private residue; `make validate-roles` adds a warn-tier structure check. Blog-side `import-ledger.json` records the excluded-files privacy trail. Worked example: `docs/journey/roles/the-analyzer.md`. Pairs with `author-post`, `audit-post-names`, `upgrade-post`, `audit-glossary-links`, `review-reader-experience` | | Import a marketplace plugin | `import-marketplace-plugin` | turn a Claude Code plugin/skill you feature in your marketplace (`omars-lab/claude-plugin-marketplace`, `plugins//`) into a build-clean `/designs` skill-design post. A JUDGMENT-guided checklist (not a transformer): the framing (plugin = ROLE, skills = ABILITIES/verbs; skills carry judgment, the tool carries muscle — state once), frontmatter (`kind: tooling-cli-design`, `sidebar_position` = max+1, `draft: true`), the source-repo `` with the fail-closed **404-gate** (draft until the repo path resolves 200; optional `commit=` pin), the body rules (de-em-dash — the hook BLOCKS `designs/*.mdx`; mermaid with NO hardcoded fills so the theme colors it; a REAL worked example from live runs), then hands to `refine-design-post` + a full `make build`. Flags the "post leads the code" trap. Worked example: `designs/2026-07-06-local-guide-skill.mdx`. Pairs with `author-post`, `refine-design-post`, `upgrade-post`, `publish-site`, the `` convention | +| Extract a general pattern | `extract-general-pattern` | turn ONE concrete `/designs` post (an imported HLD) into generalized, standalone `/designs` posts by DISENTANGLING the many reusable patterns intertangled inside it. Judgment-guided (no transformer): DISENTANGLE (surface every distinct reusable pattern — name, where it lives, the one-line reusable claim, a proposed `*-design` kind + slug; the recurring shapes live in `PATTERN-TYPES.md`) → AGREE via AskUserQuestion (you pick which become posts; nothing written first) → AUTHOR one generalized post per approved pattern, ONE AT A TIME with a checkpoint (de-specify the business, NO `source:` provenance/backlink, `draft: true`, de-em-dash, MDX-clean) → hand each to `refine-design-post` for the GENERALITY/CLARITY audit. Each post is STANDALONE (a reader can't tell which company it came from). DEFERRED (say so, don't build): external-blog export, batch mode, a deterministic transformer, auto-cataloging on a hub. Pairs with `refine-design-post`, `import-co-design` + `import-marketplace-plugin` (which CREATE the posts it reads), `author-post`, `manage-hubs` | | Enrich a post | `upgrade-post` | weave reusable MDX components into any post/doc (animated mermaid, DiagramWithFootnotes, admonitions, carousels, SvgVariantGrid, Evidence, Timeline; the question-set kit: `` cards with power/priority/cron/depth badges + Tooltip, QuestionSection, SectionBanner, PowerLegend; the quote kit: ``/`` pull-quotes + ``, the general ``/`` poster construct, the per-quote `video` link, ``) — the what/when/snippet/gotcha catalog | | Author a slide deck | `author-slide-deck` | how to build a slide/deck-style post that renders as a real reveal.js deck embedded IN the post, themed entirely from the repo's design-system tokens (no reveal theme shipped). Covers the ``/`` API + on-brand primitives (``/``/``/``/``/``), the reveal.js integration model (lazy-loaded browser-only via ``, the exports-map import paths `reveal.js`/`reveal.js/reveal.css`/`reveal.js/plugin/notes`), the raw-design-to-token color/type mapping, the design-system discipline (pastels = fills only; `--surface-page` ink on deep-green slides), and the GOTCHAS that bit (the nested-`

` hydration trap: slide text primitives render `

` not `

`; the em-dash hook; the `frontend-design` outline check that `` satisfies as the visual). Worked example: `designs/2026-07-01-blog-pitch-deck.mdx`. Pairs with `implement-with-design-system`, `import-co-design`, `author-post`, `serve-locally` | | Modify a blog-ui component | `modify-blog-ui-component` | the end-to-end loop for changing a `@omars-lab/blog-ui` component: where source lives (`packages/blog-ui/src/components/`), the `file:`-link model, the `tsup` ESM+dts+bundled-CSS build, `make build-blog-ui` rebuild+RELINK + the Yarn-1 stale-dist cache gotcha (the #1 "my edit did not show up" trap; clean-relink/cp-dist/clear-webpack-cache/restart), `MDXComponents.tsx` registration, CSS-module + theme-token conventions, no-em-dash + visual+mobile-pass rules, publish-vs-relink. Pairs with `publish-blog-ui` (release), `upgrade-post` (catalog), `serve-locally`, `maintain-showcase` |