# Knowledge Funnel Demo — Poetry to uv Migration Journey

This Markdown file mirrors `poetry-to-uv-migration-process-journey.html`. It explains the full process as executed while removing user-, host-, session-, and secret-specific details.

## Funnel view

Each layer condensed the available information into a more focused and reusable artifact.

| Stage | Condensed focus | Output |
|---|---|---|
| 1. Research intake | Broad migration domain | HTML source |
| 2. Risk extraction | Backend choice, lock strategy, groups versus extras, source mapping, cleanup discipline | Decision set |
| 3. Migration contract | Audit -> dry-run -> apply -> review -> validate -> cleanup | Skill + script |
| 4. Transfer packaging | Reusable agent handoff | JSON + ZIP |
| 5. Eval design pivot | Measure planning quality instead of runner shape | Shared-runner design |
| 6. Eval harness | Fixture projects, assertions, output contract | TOML + JSON + MD |
| 7. Explainability close-out | Static website and Markdown handoff | HTML + MD |

## Sequenced execution

### Phase 1 — The migration domain was mapped from a research source

The process started with a local research document about moving Poetry-managed projects to uv. That source was mined for hazards rather than treated as a direct rewrite recipe.

Key findings carried forward:

1. Preview the migration before editing files.
2. Preserve the current build backend for higher-risk packaged projects.
3. Treat dependency groups and extras as different concepts.
4. Review private source mappings manually.
5. Replace operational Poetry commands across docs, CI, Docker, and scripts.
6. Keep Poetry artifacts until parity is proven.

Relevant cleaned document:

- `poetry-to-uv-migration-session-record.cleaned.md`

### Phase 2 — The research became a reusable migration contract

The broad findings were distilled into a safe, repeatable operating contract for one project at a time.

Core decisions:

1. Classify the project before choosing a migration path.
2. Make backend strategy explicit instead of implicit.
3. Preserve lock intent first for lower-risk cutovers.
4. Validate behavior, not just file diffs.

Primary artifacts described in this phase:

- `SKILL.md`
- `README.md`
- workspace registration docs

### Phase 3 — The contract became a runnable helper with rollback and reports

The migration workflow was encoded into a companion script so the cutover becomes inspectable and reversible.

Expected run artifact structure:

```text
.apocrypha/poetry-to-uv/<run-id>/
  before-report.txt
  after-report.txt
  dry-run-output.txt | apply-output.txt
  managed-files.txt
  created-files.txt
  changes.diff
  backup/
```

Primary artifacts described in this phase:

- `migrate.sh`
- before and after evidence
- rollback-first operation

### Phase 4 — The migration system was packaged for agent-to-agent handoff

Once the skill and script existed, they were wrapped into portable bundles with metadata and transfer instructions.

Artifacts described:

- `poetry-to-uv-migration-agent-bundle.json`
- `poetry-to-uv-migration-skill.zip`
- `poetry-to-uv-migration-scripts.zip`

### Phase 5 — The eval approach moved from imitation to the shared runner model

The first draft mirrored a working example, but the final design pivoted to the shared runner model so the workflow matches the supported long-term interface.

Design change:

| Earlier idea | Final shape |
|---|---|
| Bespoke runner scaffold | Shared runner CLI |
| Useful for understanding the example | Correct long-term interface |
| Too specific | Reusable across skills |

Relevant cleaned document:

- `poetry-to-uv-migration-eval-handoff.cleaned.md`

### Phase 6 — The skill gained a repeatable, assertion-based eval suite

The final harness uses synthetic Poetry fixtures and grades migration plans against the skill's highest-risk decision points.

Eval cases:

| Case | What it tests |
|---|---|
| `simple-app-dev-group` | dry-run-before-apply sequencing, operational Poetry sweep, validation steps, delayed cleanup |
| `packaged-cli-private-index` | backend preservation, extras and entry points, source mapping, operational rewrites, packaging validation |
| `monorepo-multi-package` | one-project-at-a-time scope control and avoidance of blanket root-wide migration |
| `library-groups-dynamic-deps` | groups-versus-extras safety, locked-version preservation, dependency source risk, publish-path validation |

Expected eval output structure:

```text
evals/workspace/
  iteration-N/
    benchmark.json
    eval-*/with_skill/outputs/MIGRATION_PLAN.md
    eval-*/with_skill/grading.json
    eval-*/without_skill/...
```

Primary artifacts described:

- `skill-eval.toml`
- `Makefile`
- `evals.json`
- `poetry-to-uv-migration-skill-eval-bundle.zip`

### Phase 7 — The execution trail was condensed into a clean static handoff

This final step reviewed the session record and eval handoff together, then rebuilt the path as one static HTML page plus one Markdown mirror. This phase is included here intentionally so the narrative ends at the current deliverable.

Results:

1. The website is self-contained and static.
2. The Markdown copy preserves the same sequence without presentation markup.
3. User-, host-, session-, and secret-specific details have been removed.

Final artifacts:

- `poetry-to-uv-migration-process-journey.html`
- `poetry-to-uv-migration-process-journey.md`

## Bundle contents

The cleaned export folder contains the website and Markdown documents below; it
also references additional artifact types and transfer bundles that are
described by the narrative but not included in this folder.

### Website

1. `index.html`
2. `poetry-to-uv-migration-process-journey.html`
3. `poetry-to-uv-migration-research-2026.html`

### Markdown documents

1. `README.md`
2. `poetry-to-uv-migration-process-journey.md`
3. `poetry-to-uv-migration-session-record.cleaned.md`
4. `poetry-to-uv-migration-eval-handoff.cleaned.md`

### Referenced artifact types

1. `SKILL.md`
2. `migrate.sh`
3. `skill-eval.toml`
4. `Makefile`
5. `evals.json`

### Transfer artifacts described

1. `poetry-to-uv-migration-agent-bundle.json`
2. `poetry-to-uv-migration-skill.zip`
3. `poetry-to-uv-migration-scripts.zip`
4. `poetry-to-uv-migration-skill-eval-bundle.zip`

## Net result

The journey moved in a strict sequence:

1. Broad migration knowledge became a safety-focused workflow.
2. The workflow became runnable.
3. The runnable workflow became transferable.
4. The transfer became measurable.
5. The measured system is now documented in one clean handoff.