Skip to content

Repository First Data Strategy

Purpose

This document defines the recommended data strategy for the Applied Value Library.

The Applied Value Library will contain actively managed patterns, practices, products, platforms, playbooks, proof artifacts, and performance measures. These items require consistent metadata, ownership, maturity tracking, supportability tracking, repeatability tracking, commercialization readiness, dependencies, relationships, evidence, and status.

Recommendation

Use a repository-first, schema-governed, database-ready strategy.

The near-term authoritative source should be structured YAML files stored in the repository. Generated CSV indexes can support review, filtering, and lightweight spreadsheet consumption. A database such as Supabase should be introduced only when workflow, querying, integration, or multi-user maintenance requirements exceed what repository-governed YAML can support efficiently.

1. YAML as Source of Truth

Use one YAML file per library item or one YAML file per curated collection where the collection is small and tightly related.

Benefits:

  • version controlled;
  • reviewable through pull requests;
  • compatible with existing repository governance;
  • friendly to LLM ingestion;
  • portable across tools;
  • easy to generate Markdown, CSV, JSON, and website content from.

2. Generated CSV Indexes

Generate CSV indexes from YAML metadata for review and operational tracking.

Suggested indexes:

  • patterns.index.csv
  • practices.index.csv
  • products.index.csv
  • platforms.index.csv
  • proof.index.csv
  • performance-measures.index.csv
  • library-items.index.csv

CSV should be treated as generated derivative output unless explicitly designated otherwise.

3. Generated Markdown Pages

Generate human-readable Markdown pages from YAML records for publication, review, or static-site use.

Markdown should not become the authoritative source where structured YAML exists.

4. Database Integration When Needed

A database such as Supabase should be considered when any of the following become material:

  • multi-user editing outside GitHub;
  • workflow queues and approval states;
  • relational queries across patterns, practices, products, proof, and performance measures;
  • web application integration;
  • partner or customer-facing catalogs;
  • dashboard reporting;
  • ownership group workflows;
  • evidence management;
  • access control beyond repository permissions;
  • API-based consumption by Alescent applications.

Supabase Readiness

The metadata model should be designed so it can later map cleanly into relational tables.

Candidate tables:

  • library_items
  • item_relationships
  • item_domains
  • item_priorities
  • item_owners
  • item_evidence
  • patterns
  • practices
  • products
  • platforms
  • proof_artifacts
  • performance_measures
  • commercialization_status
  • review_events

Guardrails

  • Do not start with a database merely because the model is relational.
  • Do not use CSV as the authoritative structure if nested metadata, relationships, or class-specific fields matter.
  • Do not allow website or deck content to become the source of truth for library metadata.
  • Keep YAML schemas strict enough for validation and loose enough to evolve.
  • Treat generated CSV, Markdown, and website pages as derivative assets.