{
  "uid": "cogitave.learn.reuse-first-engineering.why-reuse-first",
  "kind": "moduleUnit",
  "href": "/modules/reuse-first-engineering/why-reuse-first/",
  "title": "Why reuse-first, and what enforces it",
  "summary": "",
  "type": null,
  "products": [],
  "roles": [],
  "levels": [],
  "subjects": [],
  "headings": [
    "The problem is measured, not anecdotal",
    "The hard rule: discover before generate",
    "One canonical thing to reuse at every layer",
    "The anti-duplication gates"
  ],
  "source": "## The problem is measured, not anecdotal\n\nGitClear's 2025 analysis of 211M changed lines found copy/pasted code rising from\n8.3% (2020) to 12.3% (2024), while refactored (\"moved\") code collapsed from ~25%\nto under 10% - in 2024, cloned code **surpassed refactored code for the first\ntime**, duplicate blocks up roughly 8x. The mechanism is structural: an LLM\ngenerates by statistical prediction, so similar problems yield\nsimilar-but-not-identical solutions, and most AI review tooling only sees the\ndiff - a freshly generated helper that already exists elsewhere is invisible to\nit. Without a deliberate counter-force, more AI means more divergence. Full\nevidence and citations: [AI-Native Development](../../../../standards/docs/standards/ai-native-development.md).\n\n## The hard rule: discover before generate\n\nThis is the development-time analogue of capability default-deny: the default is\n*reuse*, and \"write new\" is the privileged path that must be justified. The order\nof operations for any feature:\n\n1. **Discover** - `component_search` / `pattern_search` / `find_similar` over MCP.\n2. **Compose** - if a golden component or primitive matches above the repo's\n   similarity threshold, assemble from it. Styling is **semantic tokens only**.\n3. **Justify + author** - only if nothing fits: a short design review decides\n   whether a *new* primitive is warranted, and it is built once, in the shared\n   library.\n4. **Contribute back** - published to the library and projected into the\n   registry, so the *next* query finds it.\n\n## One canonical thing to reuse at every layer\n\nA reuse rule is only enforceable if there is exactly one canonical thing to\nreuse at each layer, queried through a single MCP-native registry that is a\n**Core projection, not a new engine**: the `ui`/`design` catalogs publish\n`Component`/`Primitive`/`Pattern`/`Token` entities that designers, developers,\nand agents all query identically.\n\n| Layer | What | Rule |\n| --- | --- | --- |\n| **Tokens** | color/space/type/motion + a semantic alias layer | Components consume `semantic.*` only - never a literal hex/px - so a re-theme is a re-point of the alias, not a hunt through every component. |\n| **Primitives** | headless behavior + accessibility, token-styled | Assemble behavior; never reimplement keyboard/focus/ARIA. |\n| **Golden components** | canonical, versioned, accessibility-complete compositions (Button, Field, DataTable, Form, Dialog, ...) | **One** way to render each concept. Agents compose these; they do not author rivals. |\n\n## The anti-duplication gates\n\nDiscovery is the carrot; these keep divergence out of `main` - symmetric with\n\"if code changes, docs change,\" the rule here is *\"if code is added, reuse is\nproven\"*:\n\n- **`no-duplication` CI gate (required check).** Token-level **jscpd** plus\n  AST/semantic **similarity-ts** fail a PR above the repo's duplication\n  threshold.\n- **Reuse review (PR expectation).** A PR must cite the registry query that\n  justified new code; rejecting a needless re-author is a reviewer's job.\n- **AGENTS.md** points every repo at the primitives with a decision table\n  (\"need a table? -> `cogitave.ui.component.data-table`\").\n- **Eval gate.** The reuse metric fails an agent that regenerates a component\n  when a registry match existed, exactly as a safety regression would.\n\n> [!NOTE]\n> Per [ADR-0003](../../../../standards/docs/decisions/0003-build-from-scratch-reference-not-dependency.md),\n> jscpd and similarity-ts are the **reference we port** to a native Core\n> checker. The next unit covers that same port-then-rebuild discipline for\n> whole engines and tools, not just components.\n",
  "partOf": "cogitave.learn.reuse-first-engineering",
  "durationInMinutes": 8,
  "quiz": null
}