design-data-contract

name	design-data-contract
description	Define file ownership boundaries — which files the user owns, which the system manages, and which are hybrid with shared access.

/design-data-contract - Data Ownership Design

When to Use

• After /design-identity and /design-skills (need to know what files exist and who writes them)
• When domain-input/data-contract.md needs to be filled
• Recommended for ALL OSes — even simple ones benefit from explicit ownership

Inputs

• Auto-loaded: domain-input/identity-model.md (what context files exist)
• Auto-loaded: domain-input/domain-workflow.md (what gets produced and tracked)
• Auto-loaded: output/designs/skill-designs.md (which skills read/write which files)

Process

Step 1: Inventory All Persistent Files

List every file the OS will contain that persists between sessions:

Context files: [from identity-model.md]
Config files: [defaults, overrides]
Output files: [reports, artifacts, briefings]
Data files: [trackers, pipelines, histories]
Templates: [scaffolding, artifact templates]
Batch files: [state, input, prompt]

Step 2: Classify Each File

For each file, ask the designer:

1. Who creates it? User fills it in / System generates it / Both
2. Who updates it? User only / System only / Both (how?)
3. What happens if the system overwrites it? Catastrophic (user data lost) / Annoying (revert) / Fine (it's ephemeral)

Classification rules:

• User-owned: User creates AND user is the primary updater. System may read but NEVER write. Loss = catastrophic.
• System-managed: System creates AND updates. User may read. Loss = regenerable.
• Hybrid: Both create/update. The system APPENDS; the user CURATES. Needs merge semantics.

Step 3: Define the Golden Rule

Ask the designer: "When the user asks to change a system default (like scoring weights or output format), where should that change go?"

The answer must be ONE specific file (the user's override file). The Golden Rule is: "When the user asks to customize [X], ALWAYS write to [user-file], NEVER to [system-file]."

Step 4: Design Hybrid File Semantics

For each hybrid file:

1. What does the system write? (append new entries, update status fields)
2. What does the user edit? (curate entries, add notes, reorder)
3. How are conflicts prevented? (staging area → merge script, or append-only)
4. Is merge idempotent? (running twice produces same result)

Step 5: Map Enforcement Points

For each skill, verify it respects the contract:

• Skills that READ user-owned files: [list]
• Skills that WRITE to system-managed files: [list]
• Skills that APPEND to hybrid files: [list]
• Any skill that would WRITE to a user-owned file → redesign or add confirmation

Output

Write the data contract to domain-input/data-contract.md.

Tell the designer:

Data contract defined:
- User-owned: [N] files — [list]
- System-managed: [N] files — [list]
- Hybrid: [N] files — [list]
- Golden Rule: "[the rule]"

Key design decision: [the most consequential classification choice]

Next: Run /design-artifact-pipeline if the OS produces non-text deliverables.
Or skip to /generate-os if infrastructure design is complete.

Quality Checks

Good data contract:

• Every persistent file is classified (no ambiguity)
• The Golden Rule is specific and testable
• Hybrid files have clear append/curate semantics
• No skill violates the contract (verified against skill designs)
• User can update system defaults without fear

Bad data contract:

• Some files not classified
• Golden Rule is vague ("be careful with user data")
• Hybrid files have no merge strategy
• Skills claim to "respect" the contract but actually auto-write to user files