claw/docs/superpowers/plans/2026-04-20-final-skill-human-readable-index-plan.md

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.