threadlight-demo-data-factory

Files (2)

• SKILL.md
• README.md · references/generators/

SKILL.md (first lines)

# Threadlight Demo Data Factory

## Presenter-ready incumbent data

For an explicitly selected presenter-ready profile, consume the process-owned
`specs/presenter-contract.json` and
[incumbent adoption map](../threadlight-deploy/references/presenter-adoption.md).
Retain existing producers and data; adoption is not permission to run seed/reset.
This selected-profile rule takes precedence over the generic reset examples below:
never wipe retained receipts, reset consumed approvals/operation IDs, or clear
UNKNOWN effects. Ordinary authorized corrections remain in scope; expired source
or authorization does not grant a new write. Preparation requires the designated
producer and a distinct synthetic revision with new lawful operation intent.
Reads must not refresh data. Exercise the day-after case: expiry denies new work
while the shell and historical reads remain available only under their own
contract, authorization and retention. Treat malformed configuration separately
from valid-but-expired data; do not force full regeneration or extend leases.

Generate per-domain synthetic demo data + idempotent reset/seed scripts for
a threadlight process. The output drives both the mock MCP server (via
`threadlight-mcp-aca` Option D) and the workspace UI (via
`threadlight-workspace-ui`) — every demo surface reads the same seed.

> **Why a separate skill?** `threadlight-mcp-aca` knows how to *serve* mock
> data via FastMCP; `threadlight-design` knows how to *declare* what
> entities and shapes are needed. This skill bridges them: it generates
> the actual JSON files (with realistic distributions, golden cases, and
> reset semantics) that the MCP server returns and the workspace renders.

## When to Use

- Process spec has at least one system marked `availability: mock` in § 5
- Process spec has § 11d Demo Data populated
- Demo needs reset-to-pristine for live recovery (every customer-facing
  demo does)
- Pilot is the canonization opportunity for an industry's realism rules

## When NOT to Use

- Customer's real backend is already accessible (no mocks needed)
- Demo data is so tiny it's hand-authored faster (e.g. 3 records total)
- Process talks only to public APIs (no synthetic data needed)

---

## Industry canons — anchor pilot pattern

Per-industry realism rules live in
`threadlight-design/references/data-realism/{industry}.md` (one of:
`fsi.md` · `retail.md` · `telco.md` · `mfg.md`). A canon is **only as
credible as the pilot it's been anchored against** — generic vocabulary
lists are aspirational; rules referenced from a *shipped* pilot's seed
JSON are testable.

| Industry | Canon file | Anchor pilot status |
|----------|-----------|---------------------|
| FSI | `data-realism/fsi.md` | **Anchored** to reusable financial-services realism patterns (PCI-DSS PAN masking · MCC anchors · Reg E/Z timer math · Fed holiday list · CNP fraud signals · worked examples). Compliance golden cases are aspirational pending future pilots. |
| Retail | `data-realism/retail.md` | Aspirational — awaiting PIM / returns-triage pilot. |
| Telco | `data-realism/telco.md` | Aspirational — awaiting a future telco operations pilot. |
| Mfg | `data-realism/mfg.md` | Aspirational — awaiting supplier-risk / shift-handover pilot. |

**The anchor-pilot rule.** When you generate seed data for a pilot,
mine the produced JSON for new realism rules and fold them back into
the canon as an "Anchor pilot" subsection with a worked-example table
(canon section → pilot file/field → worked value). The FSI canon's
`### Anchor-pilot worked example` table is
the template — copy that shape for sibling pilots.

**Honesty rule.** When the shipped pilot violated the canon (e.g.
real merchant names slipping through), document it in a `### Traps`
subsection with a "Don't / Do" table, NOT silently. The next pilot's
generator should reject the v3-style anti-pattern up front.

---

## Input contract / Output artifacts

**Input contract**:

- `specs/SPEC.md` § 4 **Data Models** — entity schemas
- `specs/SPEC.md` § 5 **System Integrations** — which systems are `mock`
- `specs/SPEC.md` § 11d **Demo Data (Realism rules)** — required:
  - Per-entity volumes
  - Distribution rules
  - Named golden cases
  - Reset semantics (`idempotent` / `append-only` / `none`)
  - Industry realism reference (e.g. `industry: fsi-banking` → loads
    `threadlight-design/references/data-realism/fsi.md`)
- `threadlight-design/references/data-realism/{industry}.md` — the
  per-industry rule book (universal rules + industry-specific overrides)

**Output**:

```
specs/sample-data/
├── {entity1}.json       # Generated, includes _meta block
├── {entity2}.json
└── README.md            # Generation date + golden case list

scripts/
├── seed_data.py         # Faker-driven generator (regenerates JSON files)
├── reset_data.py        # Wipes Cosmos + reloads from JSON
├── pyproject.toml       # uv-managed (faker, azure-cosmos, etc.)
└── README.md            # How to run + golden case scripts

src/mcp/data/            # COPIED from specs/sample-data/ at deploy time
├── {entity1}.json       # (handled by threadlight-deploy / threadlight-mcp-aca)
└── {entity2}.json
```

---

## The realism stack

```
Universal rules
   ↓ (always applied)
Industry rules (e.g. fsi.md)
   ↓ (industry-specific overrides)

From aiappsgbb/threadlight-skills, MIT.

More from aiappsgbb/threadlight-skills