claw/docs/superpowers/specs/2026-04-20-final-skill-human-readable-index-design.md

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.