feat(skills): extract-general-pattern skill

.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-<pattern-kebab>`.
+
+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-<pattern>`, `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 (`<br/>`, 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.

.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-<pattern-kebab>`.
+
+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-<pattern>`, `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 (`<br/>`, 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`.

.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 `<UseCaseDiagram>`. **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
+
+<!-- Append what you learned each disentangling: a new shape, or a sharpened recognition tell.
+     Format: "- YYYY-MM-DD (source post): <rule>". Nothing here yet — seed shapes above are from
+     the ecommerce-scanner + self-healing-storefront posts. -->