# Final Skill Human-Readable Index Plan

> Date: 2026-04-20
> Parent Plan: `2026-04-19-scene-skill-102-final-materialization-plan.md`
> Design: `2026-04-20-final-skill-human-readable-index-design.md`

## Plan Intent

Add human-readable lookup and metadata to the final materialized skill set so reviewers can identify which `sweep-xxx-scene` skill maps to which business scene.

## Fixed Inputs

1. `tests/fixtures/generated_scene/scene_execution_board_2026-04-18.json`
2. `tests/fixtures/generated_scene/scene_skill_102_final_materialization_manifest_2026-04-19.json`
3. `tests/fixtures/generated_scene/scene_skill_102_final_materialization_failures_2026-04-19.json`
4. `examples/scene_skill_102_final_materialization_2026-04-19`

## Allowed Files

1. `examples/scene_skill_102_final_materialization_2026-04-19/SCENE_INDEX.md`
2. `examples/scene_skill_102_final_materialization_2026-04-19/scene_skill_102_index.json`
3. `examples/scene_skill_102_final_materialization_2026-04-19/skills/*/SKILL.toml`
4. `examples/scene_skill_102_final_materialization_2026-04-19/skills/*/SKILL.md`
5. `docs/superpowers/reports/2026-04-20-final-skill-human-readable-index-report.md`

## Forbidden Files

1. `src/generated_scene/analyzer.rs`
2. `src/generated_scene/generator.rs`
3. `src/generated_scene/ir.rs`
4. `tests/fixtures/generated_scene/scene_execution_board_2026-04-18.json`
5. generated `scripts/*`
6. existing materialization manifest and failures assets

## Phase 0: Freeze Metadata Boundary

### Tasks

1. Confirm final materialization root exists.
2. Confirm official board has 102 scene mappings.
3. Confirm this plan does not repair failed packages.

### Acceptance Criteria

1. Scope is metadata/index only.
2. Stable `sweep-xxx-scene` ids are preserved.

## Phase 1: Build Human-Readable Mapping

### Tasks

1. Load scene id and scene name from official board.
2. Load materialization status from final materialization manifest and failures asset.
3. Produce 102 mapping rows.

### Acceptance Criteria

1. Row count is 102.
2. `sweep-012-scene` is included and marked failed.

## Phase 2: Publish Index Assets

### Tasks

1. Write `SCENE_INDEX.md`.
2. Write `scene_skill_102_index.json`.

### Acceptance Criteria

1. Index files are present.
2. Index files include scene id, scene name, archetype, readiness, status, and skill directory.

## Phase 3: Normalize Skill Metadata

### Tasks

1. For each complete package, update `SKILL.toml` readable fields while preserving `[skill].name`.
2. For each complete package, update `SKILL.md` readable summary.
3. Skip failed packages that lack required files.

### Acceptance Criteria

1. Complete packages expose readable scene names.
2. Failed packages remain explicit failures.
3. Generated scripts are not modified.

## Phase 4: Publish Report

### Tasks

1. Publish human-readable index report.
2. State materialized package count and skipped failed package count.

### Acceptance Criteria

1. Report explains how to find scene-to-skill mapping.
2. Report states that no generation or recovery was performed.

## Stop Statement

Stop after index assets, metadata normalization, and report are published. Do not start static/mock validation or `sweep-012-scene` recovery under this plan.