# Final Skill Human-Readable Index Design

> Date: 2026-04-20
> Parent Plan: `2026-04-19-scene-skill-102-final-materialization-plan.md`

## Intent

Make the final materialized skill set usable by humans without changing canonical scene ids, generation logic, or generated scripts.

The final skill directories intentionally use stable ids such as `sweep-001-scene`, but this is not enough for review, validation, or handoff. This design adds a human-readable index and normalizes metadata for already materialized skill packages.

## Scope

This design only addresses readability and metadata.

Allowed:

1. Create `SCENE_INDEX.md` under the final materialization root.
2. Create `scene_skill_102_index.json` under the final materialization root.
3. Update existing materialized `SKILL.toml` files with `display_name`, `scene_id`, and `scene_name`.
4. Update existing materialized `SKILL.md` files with readable scene metadata.
5. Publish a superpowers report.

Forbidden:

1. Do not rerun `sg_scene_generate`.
2. Do not rename `sweep-xxx-scene` directories.
3. Do not modify generated scripts.
4. Do not modify `src/generated_scene/analyzer.rs`, `src/generated_scene/generator.rs`, or `src/generated_scene/ir.rs`.
5. Do not repair `sweep-012-scene` package generation failure.
6. Do not update the official execution board.

## Data Sources

Authoritative scene names come from:

`tests/fixtures/generated_scene/scene_execution_board_2026-04-18.json`

Materialization state comes from:

`tests/fixtures/generated_scene/scene_skill_102_final_materialization_manifest_2026-04-19.json`

Failure state comes from:

`tests/fixtures/generated_scene/scene_skill_102_final_materialization_failures_2026-04-19.json`

## Output Shape

`SCENE_INDEX.md` must include:

1. scene id;
2. scene name;
3. archetype;
4. readiness;
5. materialization status;
6. skill directory;
7. failure reason when applicable.

`scene_skill_102_index.json` must contain the same mapping in machine-readable form.

Each complete skill package should expose the readable name in `SKILL.toml` and `SKILL.md` while preserving the stable `name = "sweep-xxx-scene"` identifier.

## Completion Criteria

1. The index contains exactly 102 rows.
2. The failed `sweep-012-scene` is present and explicitly marked as failed.
3. Complete packages have readable metadata.
4. No generation or recovery work is performed.