@grainulation/silo 1.0.0 → 1.0.2

package/packs/coverage-ramp.json

@@ -0,0 +1,180 @@
+{
+  "meta": {
+    "id": "coverage-ramp-playbook-v2-generalized",
+    "name": "coverage-ramp-playbook-v2-generalized",
+    "type": "claims",
+    "claimCount": 14,
+    "hash": "4288c54fcbe0d3ea836bea7dd17f660d9e747b57929726a333c0b46d9f535208",
+    "storedAt": "2026-03-24T16:48:23.846Z"
+  },
+  "claims": [
+    {
+      "id": "p001",
+      "type": "recommendation",
+      "topic": "phase-1-exclusions",
+      "content": "PHASE 1: Audit jest.config.js exclusions BEFORE writing tests. Categories to exclude: (1) generated/codegen files, (2) canvas/d3/charting that requires real browser, (3) vendored third-party libs, (4) barrel/index re-exports if trivial, (5) platform-specific files (Cordova/Electron-only). Each exclusion must be justified. Run coverage to establish the MEASURED scope — this is your denominator. Removing unjustified exclusions (like bootstrap/) later can ADD to denominator, so only remove when you have tests ready.",
+      "evidence": "Removing bootstrap/** exclusion without tests dropped coverage. Always test BEFORE removing exclusions.",
+      "tags": [
+        "phase-1",
+        "exclusions",
+        "denominator"
+      ]
+    },
+    {
+      "id": "p002",
+      "type": "recommendation",
+      "topic": "phase-2-zero-cov-grind",
+      "content": "PHASE 2: Write tests for all zero-coverage files using parallel worktree agents. Key rules: (1) Verify files exist on disk with fs.existsSync before targeting (coverage reports go stale), (2) Each agent gets 15-20 files, (3) Agents ONLY create new .test.* files — never edit jest.config or package.json, (4) Run 4-5 agents at a time, (5) After each wave: copy test files from worktree, run prettier, audit against testing rules, verify tests pass. Sort files by churn score × testability for priority.",
+      "evidence": "Coverage reports list files that may have been deleted. ~30% of files from stale reports don't exist. Verifying existence first prevents wasted agent time.",
+      "tags": [
+        "phase-2",
+        "zero-coverage",
+        "agents"
+      ]
+    },
+    {
+      "id": "p003",
+      "type": "recommendation",
+      "topic": "phase-3-deep-test-pattern",
+      "content": "PHASE 3: Deepen partial coverage using .deep.test.js files (NEVER rewrite existing tests). Create new test files alongside existing ones named *.deep.test.js that target only uncovered paths. If a file already has .deep.test.js, use .deep2.test.js. This is critical — worktree agents start from git HEAD and will REWRITE existing test files with shallower versions if told to 'deepen'. The .deep.test.js pattern is purely additive.",
+      "evidence": "Lost 1.5% coverage when agents 'deepened' files by rewriting them. The .deep.test.js pattern prevents this entirely.",
+      "tags": [
+        "phase-3",
+        "deepening",
+        "additive",
+        "critical"
+      ]
+    },
+    {
+      "id": "p004",
+      "type": "constraint",
+      "topic": "never-rewrite-tests",
+      "content": "NEVER let worktree agents modify existing test files. Worktrees start from git HEAD, not your working tree. An agent that 'deepens' a test file will read the HEAD version (which may be older/shallower) and write a 'new' version that loses coverage from your current working tree. Only create NEW test files from agents. If you need to modify existing tests, do it manually in the main tree.",
+      "evidence": "Coverage dropped from 60.01% to 59.22% when deepening agents overwrote test files with shallower versions from git HEAD.",
+      "tags": [
+        "constraint",
+        "critical",
+        "worktree"
+      ]
+    },
+    {
+      "id": "p005",
+      "type": "recommendation",
+      "topic": "churn-based-prioritization",
+      "content": "Prioritize files by git churn score: `git log --format=format: --name-only --since=12.month | sort | uniq -c | sort -nr`. High churn = actively developed = highest risk from low coverage = test first. Zero-churn files (0 commits in 12+ months) are candidates for exclusion since nobody is changing them. Use 3-year window for exclusion decisions (stricter), 1-year for prioritization (more selective).",
+      "evidence": "Churn-based prioritization ensures the most actively developed files get tested first. Zero-churn exclusions are defensible in code review.",
+      "tags": [
+        "prioritization",
+        "churn",
+        "strategy"
+      ]
+    },
+    {
+      "id": "p006",
+      "type": "recommendation",
+      "topic": "wave-structure",
+      "content": "Structure work in 4 phases with waves of 5 parallel agents each: (1) Zero-coverage grind — exhaust all untested files, sorted by churn × stmts. (2) Mixin/helper extraction — extract pure functions from untestable files into .helpers.js, test those. (3) Deep testing — .deep.test.js for 70-80% files (cheapest gains), then 50-70%. (4) Prescription mop-up — target specific uncovered lines from coverage-final.json. Each wave: launch agents → copy files → prettier → audit → verify → commit → coverage check.",
+      "evidence": "This ordering maximizes ROI. Phase 1 gives ~60% of gains. Phase 3 targets cheapest per-statement gains. Phase 4 is surgical.",
+      "tags": [
+        "process",
+        "waves",
+        "structure"
+      ]
+    },
+    {
+      "id": "p007",
+      "type": "recommendation",
+      "topic": "module-resolution-fixes",
+      "content": "Common jest module resolution blockers and fixes: (1) Missing bare-import aliases — add `'^@foo$': '<rootDir>/path/index.js'` to moduleNameMapper (not just `'^@foo/(.*)$'`). (2) Generated files (.gen.js) — create thin re-export stub: `export { default } from './File.gen'`. (3) Build-time-only modules — create stub files that re-export from canonical locations. (4) Files using `{ virtual: true }` in jest.mock don't work when moduleNameMapper already maps the path — use stubs instead.",
+      "evidence": "5 bare-import aliases + 4 module stubs unblocked ~15 previously-untestable files worth 500+ statements.",
+      "tags": [
+        "infrastructure",
+        "jest",
+        "module-resolution"
+      ]
+    },
+    {
+      "id": "p008",
+      "type": "recommendation",
+      "topic": "mixin-helper-extraction",
+      "content": "For excluded createReactClass mixins: DON'T refactor the mixin itself. Instead, identify pure module-scope functions (no `this` binding, no side effects) and extract them into a .helpers.js file. Test the helpers. The new file is automatically in-scope for coverage. Pattern: read first 100 lines of mixin → find functions defined outside the mixin object → extract to FileName.helpers.js → write thorough tests. Most mixins have 0-6 extractable pure functions. Assess before extracting — many have none.",
+      "evidence": "5 mixins assessed → 15 pure functions extracted → 55 tests. 6 other mixins had 0 extractable functions (all this-bound).",
+      "tags": [
+        "refactoring",
+        "mixins",
+        "helpers"
+      ]
+    },
+    {
+      "id": "p009",
+      "type": "recommendation",
+      "topic": "diminishing-returns-strategy",
+      "content": "Coverage gains follow a curve: 0-60% is fast (zero-cov grind), 60-75% is moderate (mix of new + deep), 75-80% is slow (deep testing of already-tested files). Strategy shifts: (1) Below 70%: batch zero-cov files, 15-20 per agent. (2) 70-80%: target files at 70-79% with smallest gaps (5-15 uncov stmts each — cheapest per-file). (3) Above 78%: test tiny 0% files (barrel re-exports, configs) that don't grow denominator. (4) The denominator grows ~5-10 stmts per new test file discovered, so the target keeps moving.",
+      "evidence": "Each wave above 78% yielded ~0.1-0.3% gain vs ~2-5% below 60%. Targeting 75-80% files with 5-8 uncov stmts was the most efficient late-game strategy.",
+      "tags": [
+        "strategy",
+        "efficiency",
+        "late-game"
+      ]
+    },
+    {
+      "id": "p010",
+      "type": "recommendation",
+      "topic": "testing-rules-enforcement",
+      "content": "Embed testing rules in EVERY agent prompt. Key rules to enforce: (1) import from @test-utils not @testing-library/react, (2) userEvent.setup() not fireEvent, (3) query by role/label first, (4) mock at boundaries not local components, (5) top-level imports only (no inline require), (6) max 2 describe nesting, (7) no 'should' in test names, (8) AAA pattern, (9) beforeEach with jest.clearAllMocks. Run audit after each wave: grep for violations, fix before committing.",
+      "evidence": "3 violations found in 1,700+ test files when rules were embedded in every prompt. Without embedding, early waves had 292 require() and 7 fireEvent violations.",
+      "tags": [
+        "quality",
+        "rules",
+        "enforcement"
+      ]
+    },
+    {
+      "id": "p011",
+      "type": "recommendation",
+      "topic": "exclusion-analysis",
+      "content": "When considering excluding files from coverage: (1) NEVER exclude to game the number — only exclude genuinely untestable code. (2) Cross-reference with churn: 0 commits in 3+ years = safe to exclude. 0 in 1 year = gray area. Any recent churn = keep measured. (3) Removing exclusions ADDS to denominator — only remove when tests are ready. (4) Categories that are permanently untestable in jsdom: canvas rendering, d3/charting, golden layout, CodeMirror/Monaco, PhoneGap/Cordova native APIs. (5) Track two numbers: measured scope coverage and original codebase coverage.",
+      "evidence": "Removing bootstrap/** exclusion without ready tests dropped coverage by 0.8%. Churn-based exclusion analysis showed 0 files with 0 churn in 5 years — everything was touched at least once.",
+      "tags": [
+        "exclusions",
+        "transparency",
+        "strategy"
+      ]
+    },
+    {
+      "id": "p012",
+      "type": "recommendation",
+      "topic": "merge-checklist",
+      "content": "After EVERY agent completes, run this checklist: (1) Copy ONLY .test.* and .helpers.* files from worktree (never jest.config.js or package.json). (2) npx prettier --write on all new files. (3) Audit against testing rules (grep for violations). (4) Verify jest.config.js thresholds not stomped. (5) npx jest --ci --no-coverage on new files to verify pass. (6) git add + commit. (7) Run full coverage after each wave to track progress. This checklist prevents the most common agent mistakes.",
+      "evidence": "Agent overwrote jest.config.js once, resetting thresholds. Another agent created module stubs that shouldn't have been copied to main tree. Checklist catches these.",
+      "tags": [
+        "checklist",
+        "quality",
+        "process"
+      ]
+    },
+    {
+      "id": "p013",
+      "type": "factual",
+      "topic": "velocity-benchmarks",
+      "content": "On a ~2,000-file / 300K-line React codebase: Phase 1 (zero-cov grind) covered ~350 files in ~8 waves, gaining ~25% coverage. Phase 2 (mixin extraction) added ~200 stmts from 5 mixins. Phase 3 (deep testing) pushed from 77% to 80% over ~6 waves. Total: 45% → 80% in one extended session, ~10,000 new tests, ~1,700 test files. Each 5-agent wave takes 5-15 minutes and yields 50-500 new covered stmts depending on phase.",
+      "evidence": "NT-38884 session data, March 2026.",
+      "tags": [
+        "benchmarks",
+        "velocity"
+      ]
+    },
+    {
+      "id": "p014",
+      "type": "recommendation",
+      "topic": "branch-coverage-strategy",
+      "content": "Branches are the hardest metric to improve. Each if/else, ternary, switch, &&, || has two paths. To specifically target branches: (1) Score files by uncovered-branches count, not stmts. (2) Tell agents explicitly to test every conditional path. (3) Create .branch.test.js files for branch-specific testing. (4) Small zero-cov files with high branch counts (e.g., 10 branches in a 15-stmt utility) give the best branch ROI. (5) Branches in complex components (Recoil state, router conditions) are the hardest — save for manual deepening.",
+      "evidence": "Branch-targeted waves moved branches from 58% to 66% — each wave adding ~1-2%. Statements and functions moved faster because they benefit from any test, while branches require path-specific tests.",
+      "tags": [
+        "branches",
+        "strategy",
+        "hard-metric"
+      ]
+    }
+  ]
+}

package/packs/data-engineering.json

@@ -8,7 +8,11 @@
       "type": "factual",
       "topic": "ETL vs ELT tradeoffs",
       "content": "ETL (Extract-Transform-Load) transforms data before loading into the target, reducing storage costs but making the pipeline brittle to schema changes. ELT (Extract-Load-Transform) loads raw data first and transforms in the warehouse, leveraging cheap columnar storage and enabling reprocessing without re-extraction. ELT is the dominant pattern for cloud data warehouses (Snowflake, BigQuery, Redshift).",
-      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
       "evidence": "documented",
       "status": "active",
       "phase_added": "define",
@@ -22,7 +26,11 @@
       "type": "constraint",
       "topic": "schema evolution compatibility",
       "content": "Schema changes must be backwards-compatible for consumers: adding optional fields (safe), removing fields (breaking), renaming fields (breaking), changing types (breaking). Use schema registries (Confluent, AWS Glue) to enforce compatibility rules. Avro supports full forward/backward/full compatibility modes. Breaking changes require a new topic or table version.",
-      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
       "evidence": "documented",
       "status": "active",
       "phase_added": "define",
@@ -36,7 +44,11 @@
       "type": "recommendation",
       "topic": "data quality checks in pipelines",
       "content": "Every data pipeline should include automated quality checks: row count expectations (within 10% of previous run), null rate thresholds per column, uniqueness constraints on key columns, freshness checks (data arrived within expected window), and referential integrity across tables. Use tools like Great Expectations, dbt tests, or Soda to define checks as code.",
-      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
       "evidence": "production",
       "status": "active",
       "phase_added": "define",
@@ -64,7 +76,11 @@
       "type": "factual",
       "topic": "batch vs streaming latency tradeoffs",
       "content": "Batch processing (hourly/daily) is simpler, cheaper, and sufficient when business requirements tolerate T+1 or T+hour latency. Streaming (Kafka, Kinesis, Flink) delivers sub-second latency but costs 3-10x more in infrastructure and 2-3x more in engineering complexity (exactly-once semantics, out-of-order events, state management). Default to batch unless latency requirements demand streaming.",
-      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
       "evidence": "production",
       "status": "active",
       "phase_added": "define",
@@ -78,7 +94,11 @@
       "type": "recommendation",
       "topic": "change data capture pattern",
       "content": "Change Data Capture (CDC) reads database transaction logs (binlog, WAL) to stream row-level changes to downstream systems. Use Debezium for open-source CDC from PostgreSQL, MySQL, MongoDB, and SQL Server. CDC avoids polling overhead, captures deletes (which polling misses), and preserves event ordering. Initial snapshot + streaming log is the standard bootstrap pattern.",
-      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
       "evidence": "documented",
       "status": "active",
       "phase_added": "define",
@@ -92,7 +112,11 @@
       "type": "risk",
       "topic": "late-arriving data in event streams",
       "content": "Event streams contain late-arriving data due to network delays, mobile offline sync, or batch uploads. Windowed aggregations must handle late data with watermarks (maximum allowed lateness). Flink default watermark is 0 (no late data tolerance). Set watermarks based on observed p99 lateness in your data. Late events beyond the watermark are either dropped or routed to a dead-letter topic for manual reconciliation.",
-      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
       "evidence": "production",
       "status": "active",
       "phase_added": "define",
@@ -106,7 +130,11 @@
       "type": "recommendation",
       "topic": "idempotent pipeline design",
       "content": "Data pipelines must be idempotent: running the same pipeline twice with the same input produces the same output without duplicates. Implement with: write to a staging table, then MERGE/upsert to the target (not INSERT). Use partition overwrite for append-only tables. Idempotency enables safe retries after partial failures, which occur in approximately 5-10% of batch runs.",
-      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
       "evidence": "production",
       "status": "active",
       "phase_added": "define",
@@ -120,7 +148,11 @@
       "type": "estimate",
       "topic": "Parquet vs CSV storage savings",
       "content": "Columnar formats (Parquet, ORC) reduce storage by 75-90% compared to CSV/JSON for analytical workloads, and query performance improves 10-100x due to column pruning and predicate pushdown. A 100 GB CSV dataset typically compresses to 5-15 GB in Parquet with Snappy compression. Always use Parquet or ORC for data lake storage, never raw CSV.",
-      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
       "evidence": "tested",
       "status": "active",
       "phase_added": "define",
@@ -134,7 +166,11 @@
       "type": "constraint",
       "topic": "PII handling in data pipelines",
       "content": "PII must be classified, tagged, and handled according to data governance policy at ingestion time, not after the fact. Apply column-level encryption or tokenization for sensitive fields (SSN, email, phone). Implement row-level access controls in the warehouse. Maintain a data catalog that tracks PII lineage from source to all downstream tables. GDPR right-to-erasure requires the ability to delete a user across all derived datasets.",
-      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
       "evidence": "documented",
       "status": "active",
       "phase_added": "define",
@@ -148,7 +184,11 @@
       "type": "factual",
       "topic": "exactly-once semantics cost",
       "content": "Exactly-once processing in streaming systems (Kafka transactions, Flink checkpointing) adds 10-30% throughput overhead compared to at-least-once. At-least-once with idempotent consumers (using unique event IDs and upsert writes) achieves the same end result with lower complexity. True exactly-once is only required when side effects cannot be made idempotent (sending emails, charging payments).",
-      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
       "evidence": "tested",
       "status": "active",
       "phase_added": "define",
@@ -169,7 +209,12 @@
       "timestamp": "2025-01-01T00:00:00.000Z",
       "conflicts_with": [],
       "resolved_by": null,
-      "tags": ["data-engineering", "dbt", "transformation", "analytics-engineering"]
+      "tags": [
+        "data-engineering",
+        "dbt",
+        "transformation",
+        "analytics-engineering"
+      ]
     }
   ]
-}
+}

package/packs/frontend.json

@@ -8,7 +8,11 @@
       "type": "constraint",
       "topic": "Core Web Vitals thresholds",
       "content": "Google Core Web Vitals targets for good UX: LCP (Largest Contentful Paint) under 2.5s, INP (Interaction to Next Paint) under 200ms, CLS (Cumulative Layout Shift) under 0.1. These directly affect search ranking. Measure with field data (CrUX, RUM) not just lab data (Lighthouse), since field p75 is what Google uses.",
-      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
       "evidence": "documented",
       "status": "active",
       "phase_added": "define",
@@ -22,7 +26,11 @@
       "type": "recommendation",
       "topic": "JavaScript bundle size budget",
       "content": "Initial JavaScript bundle should be under 150 KB compressed (gzip) for mobile-first applications. Total page weight including images should be under 1.5 MB. Every 100 KB of JavaScript adds approximately 350ms parse/compile time on median mobile devices. Use bundle analyzer (webpack-bundle-analyzer, source-map-explorer) in CI to enforce budgets.",
-      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
       "evidence": "tested",
       "status": "active",
       "phase_added": "define",
@@ -36,7 +44,11 @@
       "type": "constraint",
       "topic": "WCAG 2.1 AA compliance",
       "content": "WCAG 2.1 Level AA is the legal standard in the US (ADA), EU (EAA 2025), and Canada (AODA). Key requirements: color contrast ratio 4.5:1 for normal text and 3:1 for large text, all interactive elements keyboard-accessible, form inputs have visible labels, images have alt text, focus indicators visible, no content reliant solely on color.",
-      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
       "evidence": "documented",
       "status": "active",
       "phase_added": "define",
@@ -50,7 +62,11 @@
       "type": "factual",
       "topic": "SSR vs CSR tradeoffs",
       "content": "Server-Side Rendering (SSR) provides faster First Contentful Paint and better SEO but increases server load and Time to Interactive (hydration cost). Client-Side Rendering (CSR) has faster subsequent navigations but a blank page until JS loads. Use SSR/SSG for content-heavy, SEO-critical pages; CSR for authenticated app-like interfaces behind login.",
-      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
       "evidence": "documented",
       "status": "active",
       "phase_added": "define",
@@ -64,7 +80,11 @@
       "type": "risk",
       "topic": "third-party script performance",
       "content": "Third-party scripts (analytics, ads, chat widgets) are the leading cause of performance regression. A single poorly-written third-party script can add 500ms-2s to page load. Load all third-party scripts with async or defer. Set performance budgets that include third-party weight. Use a tag manager with server-side option to control loading.",
-      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
       "evidence": "production",
       "status": "active",
       "phase_added": "define",
@@ -78,7 +98,11 @@
       "type": "recommendation",
       "topic": "image optimization pipeline",
       "content": "Serve images in WebP or AVIF format (30-50% smaller than JPEG). Use srcset with 2-4 size variants for responsive images. Lazy-load images below the fold with loading='lazy'. Set explicit width and height attributes to prevent CLS. Automate optimization in the build pipeline or use an image CDN (Cloudinary, imgix, Cloudflare Images).",
-      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
       "evidence": "tested",
       "status": "active",
       "phase_added": "define",
@@ -92,7 +116,11 @@
       "type": "recommendation",
       "topic": "state management selection criteria",
       "content": "Use local component state (useState/signals) for UI-only state. Use URL state (query params, path) for shareable/bookmarkable state. Use server state libraries (TanStack Query, SWR) for API data with caching. Use global state (Zustand, Redux, or context) only for truly cross-cutting client state (auth, theme, feature flags). Most applications over-use global state.",
-      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
       "evidence": "documented",
       "status": "active",
       "phase_added": "define",
@@ -106,7 +134,11 @@
       "type": "risk",
       "topic": "layout shift from web fonts",
       "content": "Custom web fonts cause either FOIT (Flash of Invisible Text) or FOUT (Flash of Unstyled Text), both contributing to CLS. Mitigate with font-display: swap, preload critical fonts with <link rel='preload'>, subset fonts to used character ranges (Latin subset is ~30 KB vs 200 KB for full Unicode), and use size-adjust to match fallback metrics.",
-      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
       "evidence": "tested",
       "status": "active",
       "phase_added": "define",
@@ -120,7 +152,11 @@
       "type": "factual",
       "topic": "code splitting impact",
       "content": "Route-based code splitting typically reduces initial bundle size by 40-60%. Dynamic import() splits a module into a separate chunk loaded on demand. For React, use React.lazy() with Suspense boundaries. Split at route boundaries first, then heavy component boundaries (charts, editors, maps). Avoid splitting components under 30 KB as the HTTP overhead negates the benefit.",
-      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
       "evidence": "tested",
       "status": "active",
       "phase_added": "define",
@@ -134,7 +170,11 @@
       "type": "constraint",
       "topic": "keyboard navigation requirements",
       "content": "Every interactive element must be reachable and operable via keyboard alone. Tab order must follow visual reading order. Focus must be visible (minimum 2px outline, 3:1 contrast ratio against adjacent colors). Custom components (dropdowns, modals, tabs) must implement ARIA roles and keyboard patterns from WAI-ARIA Authoring Practices. Test by unplugging the mouse.",
-      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
       "evidence": "documented",
       "status": "active",
       "phase_added": "define",
@@ -162,7 +202,11 @@
       "type": "recommendation",
       "topic": "error boundaries and fallbacks",
       "content": "Wrap major UI sections in error boundaries that catch render errors and display a fallback UI instead of a white screen. Log caught errors to your observability stack. Provide a retry mechanism in the fallback. Without error boundaries, a single failing component crashes the entire page. Test error boundaries by deliberately throwing in development.",
-      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
       "evidence": "documented",
       "status": "active",
       "phase_added": "define",
@@ -172,4 +216,4 @@
       "tags": ["frontend", "error-handling", "resilience", "react"]
     }
   ]
-}
+}

package/packs/hackathon-best-ai.json

@@ -0,0 +1,179 @@
+{
+  "name": "Hackathon: Best Use of AI",
+  "description": "Scoring rubric and seed claims for the 'Best Use of AI' hackathon category. Features a unique ai_leverage sub-score rewarding quality AI-assisted research over shallow generation.",
+  "version": "1.0.0",
+  "claims": [
+    {
+      "id": "hai-001",
+      "type": "constraint",
+      "topic": "AI leverage scoring",
+      "content": "AI leverage sub-score = (claims_from_ai_assisted_research / total_claims) * quality_multiplier. Quality multiplier = average evidence tier of AI-assisted claims. Weight: 30%. Rewards using AI for deep research, not shallow claim generation.",
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
+      "evidence": "documented",
+      "status": "active",
+      "phase_added": "define",
+      "timestamp": "2026-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["hackathon", "scoring", "ai-leverage", "best-ai"]
+    },
+    {
+      "id": "hai-002",
+      "type": "constraint",
+      "topic": "evidence tier scoring",
+      "content": "Evidence tier sub-score uses weighted sum normalized to 0-100. Weight: 20%. AI-assisted claims should produce higher evidence tiers — web and documented, not just stated.",
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
+      "evidence": "documented",
+      "status": "active",
+      "phase_added": "define",
+      "timestamp": "2026-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["hackathon", "scoring", "evidence-tier", "best-ai"]
+    },
+    {
+      "id": "hai-003",
+      "type": "constraint",
+      "topic": "type diversity scoring",
+      "content": "Type diversity sub-score = (distinct_types / 6) * 100. Weight: 20%. Best AI use means leveraging AI for diverse research outputs — not just generating a list of facts.",
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
+      "evidence": "documented",
+      "status": "active",
+      "phase_added": "define",
+      "timestamp": "2026-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["hackathon", "scoring", "type-diversity", "best-ai"]
+    },
+    {
+      "id": "hai-004",
+      "type": "constraint",
+      "topic": "corroboration scoring",
+      "content": "Corroboration sub-score = witnessed_claims / total_claims * 100. Weight: 15%. AI can find cross-references humans miss — high corroboration signals effective AI-human collaboration.",
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
+      "evidence": "documented",
+      "status": "active",
+      "phase_added": "define",
+      "timestamp": "2026-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["hackathon", "scoring", "corroboration", "best-ai"]
+    },
+    {
+      "id": "hai-005",
+      "type": "constraint",
+      "topic": "challenge depth scoring",
+      "content": "Challenge depth sub-score = (challenge_claims + resolved_conflicts) / total_claims * 100. Weight: 15%. Best AI use includes AI-assisted devil's advocate — challenging claims and finding counter-evidence.",
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
+      "evidence": "documented",
+      "status": "active",
+      "phase_added": "define",
+      "timestamp": "2026-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["hackathon", "scoring", "challenge-depth", "best-ai"]
+    },
+    {
+      "id": "hai-006",
+      "type": "recommendation",
+      "topic": "AI collaboration patterns",
+      "content": "Effective AI research patterns: (1) AI finds sources, human validates and elevates evidence tier. (2) AI generates initial claims, human challenges and refines. (3) AI identifies conflicts between sources, human resolves. (4) AI drafts recommendations, human grounds in business context.",
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
+      "evidence": "stated",
+      "status": "active",
+      "phase_added": "define",
+      "timestamp": "2026-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["hackathon", "ai-patterns", "collaboration", "best-ai"]
+    },
+    {
+      "id": "hai-007",
+      "type": "risk",
+      "topic": "AI slop detection",
+      "content": "Risk of AI 'slop': bulk-generated low-quality claims that look comprehensive but lack depth. Signals: uniform evidence tiers, generic topics, no conflicts or challenges, repetitive phrasing across claims.",
+      "source": { "origin": "research", "artifact": null, "connector": null },
+      "evidence": "stated",
+      "status": "active",
+      "phase_added": "research",
+      "timestamp": "2026-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["hackathon", "gaming", "ai-slop", "risk"]
+    },
+    {
+      "id": "hai-008",
+      "type": "recommendation",
+      "topic": "MCP connector usage",
+      "content": "Best AI use should leverage MCP connectors: web search for real-time data, GitHub for code context, Confluence/Jira for organizational knowledge. Connector diversity signals sophisticated AI orchestration.",
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
+      "evidence": "stated",
+      "status": "active",
+      "phase_added": "define",
+      "timestamp": "2026-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["hackathon", "mcp-connectors", "ai-orchestration", "best-ai"]
+    },
+    {
+      "id": "hai-009",
+      "type": "recommendation",
+      "topic": "human judge criteria",
+      "content": "Human judges for 'Best Use of AI' score on: (1) human-AI synergy — did the team direct AI effectively or just let it run? (2) evidence elevation — did AI help reach higher evidence tiers? (3) creative prompting — did the team use novel approaches to extract insight?",
+      "source": { "origin": "research", "artifact": null, "connector": null },
+      "evidence": "stated",
+      "status": "active",
+      "phase_added": "research",
+      "timestamp": "2026-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["hackathon", "human-judging", "criteria", "best-ai"]
+    },
+    {
+      "id": "hai-010",
+      "type": "factual",
+      "topic": "HackEval precedent",
+      "content": "HackEval keeps AI as assistant, not decision-maker: structured rubrics with blind scoring to reduce bias, but final decisions remain human. AI Judge (Devpost) takes the opposite approach with full automation. The wheat hackathon model should be the middle ground.",
+      "source": {
+        "origin": "research",
+        "artifact": "https://www.scribd.com/document/973181548/HackEval-Full-Pitch",
+        "connector": null
+      },
+      "evidence": "web",
+      "status": "active",
+      "phase_added": "research",
+      "timestamp": "2026-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["hackathon", "precedent", "hackeval", "ai-judging"]
+    }
+  ]
+}