---
id: LSN-0016
ticket: studio-docs-import
title: Studio docs import pattern
created: 2026-03-26
tags:
  - studio
  - migration
  - discussion-framework
  - import-pattern
---

## Context

This lesson summarizes the completed migration of `docs/studio` into `discussion/`.

The original migration control artifacts were:

- `AGD-0001`
- `DEC-0001`
- `PLN-0001`

Those workflow files are being deleted during housekeeping. The index remains the permanent historical record.

## Key Decisions

### Domain documentation import should preserve retained truth instead of reconstructing deleted history

**What:** The `docs/studio` migration imported only retained artifacts, rewrote them into framework-native templates, turned retained `learn` documents into legacy lessons, kept `specs` outside `discussion/`, and promoted imported open agendas into their own new discussions.
**Why:** Reconstructing deleted decisions or plans would fabricate workflow history. The retained source set already contained the truth that mattered: one open agenda, zero retained decisions, zero retained plans, and a didactic learn corpus.
**Trade-offs:** This approach requires explicit editorial normalization and separate migration bookkeeping, but it yields a canonical framework surface without inventing missing history.

## Patterns and Algorithms

- Import only currently retained domain artifacts.
- Rewrite imported material into native framework templates.
- Turn retained `learn` material into legacy lessons under the migration discussion directory.
- Split retained open agendas into new discussions rather than leaving them nested inside the migration discussion.
- Keep `specs` as external normative references.
- Use housekeeping to delete completed migration control artifacts after their durable lesson is recorded.

## Pitfalls

- Recreating deleted decisions or plans from README summaries.
- Treating imported legacy lessons as if they came from framework-native execution rather than backfill.
- Leaving completed migration control artifacts in place after the durable pattern is already preserved.

## Takeaways

- The migration pattern is now reusable for other domains: retained agendas become new discussions, retained learn becomes legacy lessons, and completed migration control artifacts are disposable after housekeeping.
- Legacy source attribution for imported content remains in the imported lessons themselves; this lesson captures the migration pattern rather than one domain-specific document.