claw/docs/superpowers/plans/2026-04-20-deterministic-keyword-scoring-refinement-plan.md

Deterministic Keyword Scoring Refinement Plan

Date: 2026-04-20 Design: 2026-04-20-deterministic-keyword-scoring-refinement-design.md

Plan Intent

Close the 9 deterministic dispatch ambiguity gaps by bounded manifest keyword refinement and dry-run verification.

Fixed Inputs

1. tests/fixtures/generated_scene/scene_skill_102_deterministic_invocation_readiness_2026-04-20.json
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/*/scene.toml

Allowed Files

1. examples/scene_skill_102_final_materialization_2026-04-19/skills/*/scene.toml
2. tests/fixtures/generated_scene/deterministic_keyword_scoring_refinement_2026-04-20.json
3. tests/fixtures/generated_scene/scene_skill_102_deterministic_invocation_readiness_after_keyword_refinement_2026-04-20.json
4. docs/superpowers/reports/2026-04-20-deterministic-keyword-scoring-refinement-report.md

Forbidden Files

1. src/compat/scene_platform/dispatch.rs
2. src/compat/scene_platform/resolvers.rs
3. src/generated_scene/analyzer.rs
4. src/generated_scene/generator.rs
5. generated scripts/*
6. tests/fixtures/generated_scene/scene_execution_board_2026-04-18.json

Phase 0: Freeze Gap Set

Tasks

1. Load readiness gaps from the parent readiness asset.
2. Confirm the fixed gap set is exactly 9 ambiguous dispatch entries.

Acceptance Criteria

1. No additional gap categories are pulled into scope.
2. sweep-012-scene remains excluded.

Phase 1: Refine Manifest Keywords

Tasks

1. For each fixed gap, identify direct collision partner.
2. Narrow include keywords to distinctive full phrases.
3. Remove broad standalone collision tokens where they create ties.
4. Add explicit exclude keywords only when a pair is mutually exclusive.

Acceptance Criteria

1. The fixed 9 scenes retain non-empty include keywords.
2. No generated script is changed.

Phase 2: Dispatch Dry-Run Verification

Tasks

1. Re-run dispatch dry-run for all 101 complete packages.
2. Verify the fixed 9 gaps uniquely select their expected scene by full-name sample.
3. Check that no previously-ready scene regresses into ambiguity or no-match.

Acceptance Criteria

1. dispatchReady = 101 or all residual gaps are explicitly justified.
2. ambiguous = 0 unless escalated to a separate runtime scoring plan.

Phase 3: Publish Report

Tasks

1. Publish refinement JSON.
2. Publish post-refinement readiness JSON.
3. Publish report.

Acceptance Criteria

1. Report states before/after ready and ambiguous counts.
2. Report states whether runtime scoring changes are needed.

Stop Statement

Stop after refinement assets and report are published. Do not start browser execution, runtime dispatch implementation, or sweep-012-scene recovery under this plan.