Stage 3 -- Review and Refine

[SorraTheOrc]

Stage 3 -- Review and Refine

Headline: The TUI wizard's Review stage displays the full palette with classification attributes, flags intensity/texture coherence outliers via median deviation, and lets the user swap, add, or remove selections before export.

Problem Statement

After selecting and auditioning sound candidates in Stages 1-2 of the TUI wizard, game developers need to review their entire palette at a glance, verify coherence across selections, and make targeted adjustments (swap, add, or remove) before committing to export.

Users

Primary: Game developers building sound palettes through the TUI wizard who need to verify palette coherence and make final adjustments before export.

User Stories

• As a game developer using the TUI wizard, I want to see all my selected sounds side-by-side with their audio characteristics (category, intensity, texture), get warnings when some sounds feel out of place compared to the rest of my palette, and easily swap or adjust individual selections before exporting.
• As a game developer with a large palette, I want to quickly identify which selections are outliers in terms of intensity or texture so I can decide whether to keep them intentionally or replace them with something more consistent.

Success Criteria

1. Palette summary table displays recipe name, seed, category, intensity, texture (comma-separated labels), and tags for each selection, ordered by manifest position.
2. Coherence check flags entries whose intensity or texture ordinal index deviates by more than 1 step from the palette median; flagged entries display a !! warning prefix.
3. If the palette has fewer than 3 entries, coherence checking is skipped with an informational message. When all entries pass coherence, a success message confirms this.
4. The user can swap a selection by re-auditioning against cached sweep candidates for that recipe; if no cached candidates exist, a clear error is shown and the original selection is preserved.
5. The user can navigate back to the Explore stage (and from there to Define) to add new recipes, with current manifest and selections preserved.
6. The user can remove a recipe from the palette (with confirmation), including both the selection and the manifest entry; removing the last entry warns that the palette is now empty.
7. A confirmation prompt is displayed before advancing to the Export stage.
8. Unit tests cover: median calculation for intensity/texture, deviation flagging logic, swap/add/remove flows, < 3 entries skip behavior, empty palette handling, and cache miss on swap.

Constraints

• Uses @inquirer/prompts (select, confirm) for all interactive prompts -- no full-screen TUI frameworks.
• Coherence checking uses a simple ordinal median deviation approach, not a statistical model.
• The texture scale is ordered alphabetically (bright, crunchy, dark, harsh, noisy, sharp, smooth, tonal, warm) rather than semantically, which may produce unintuitive coherence flags for textures that are perceptually close but alphabetically distant. This is a known simplification.
• The "add" action returns "back" to the pipeline orchestrator, which navigates to the Explore stage (not directly to Define). Reaching Define requires a second back-navigation from Explore.
• Swap depends on the sweep cache populated during Stage 2; if the cache is missing (e.g., due to a session state issue), the swap fails gracefully with an error message.

Existing State

The feature is fully implemented and tested:

• src/tui/stages/review.ts (492 lines) -- complete implementation of the Review and Refine stage including:
  • Intensity scale: subtle, soft, medium, hard, aggressive (ordinal indices 0-4)
  • Texture scale: bright, crunchy, dark, harsh, noisy, sharp, smooth, tonal, warm (ordinal indices 0-8)
  • Pure helper functions for median calculation, coherence flagging, and summary table building
  • Interactive flow with swap/add/remove/confirm/back actions
• src/tui/__tests__/review.test.ts (751 lines, 54 tests) -- comprehensive coverage of all pure helpers and interactive flows
• Pipeline integration in src/tui/index.ts (lines 109-118) dispatches to runReviewStage() with back-navigation support

Desired Change

This work item describes the completed implementation. The primary remaining action is to verify the implementation against acceptance criteria (this audit) and prepare for formal review.

Observations and improvement opportunities

1. Texture scale ordering: The texture dimension uses alphabetical ordering rather than semantic ordering. Unlike intensity (which maps naturally from low-energy "subtle" to high-energy "aggressive"), textures like "bright" and "dark" don't form a natural linear scale. This means coherence flags for texture may be unintuitive. Consider whether a perceptually-ordered texture scale would produce more meaningful coherence results in a future enhancement.

2. Sweep cache dependency on swap: The swap action depends on cached sweep results from Stage 2. If no cache exists for a recipe (which could happen if session state is corrupted or if a recipe was added outside the normal flow), the swap fails gracefully with an error. This behavior is tested but not documented in the acceptance criteria.

3. "Add" navigation path: The acceptance criterion states the user "returns to Define stage" but the implementation returns to Explore (one stage back). Reaching Define requires a second back-navigation from Explore. The acceptance criterion should be updated to accurately describe this back-one-stage navigation model.

Related Work

Related documents

• src/tui/stages/review.ts -- Implementation (492 lines)
• src/tui/__tests__/review.test.ts -- Tests (751 lines, 54 tests)
• src/tui/types.ts -- CandidateSelection, WizardSession types
• src/tui/state.ts -- WizardSession class with selection/manifest management
• src/tui/stages/explore.ts -- auditionRecipe() function called by swap action
• src/tui/index.ts -- Pipeline orchestrator with Review stage dispatch
• src/classify/types.ts -- ClassificationResult type definition (re-exported via src/classify/index.ts)
• docs/prd/CLASSIFY_PRD.md -- Classification taxonomy specification
• src/output.ts -- outputTable() for formatted display

Related work items

• TUI Wizard: Interactive Sound Palette Builder (TF-0MM7HULM506CGSOP) -- Parent epic
• TUI Foundation -- Types, Session State, CLI Entry Point (TF-0MM8S0MHO0033HYE, completed) -- Foundation dependency
• Stage 2b -- Audition and Mutation (TF-0MM8S1W4C0NQ1CW6, completed) -- Direct dependency; provides selections and auditionRecipe()
• Stage 4 -- Export via Library with Manifest (TF-0MM8S2LKQ1WM38F4, blocked) -- Downstream dependency
• End-to-End Integration and Polish (TF-0MM8S2ZOH1XPC1X6, blocked) -- Integration work depending on all stages
• Classification Engine Core & Types (TF-0MM0AJ6R01H1XLVU, completed) -- Provides ClassificationResult type
• Add automatic classification to explore sweep pipeline (TF-0MM363OCN13SPE6J, completed) -- Ensures sweep candidates carry classification data

Risks & Assumptions

• Risk: Texture coherence false positives -- The alphabetical ordering of the texture scale may flag perceptually similar textures as outliers (e.g., "bright" at index 0 vs. "dark" at index 2 are 2 steps apart but could both be appropriate in a game palette). Mitigation: document this as a known limitation; consider a perceptually-ordered scale as a future enhancement tracked in a separate work item.
• Risk: Scope creep -- Enhancements to coherence checking (multi-dimensional analysis, weighted scoring, user-adjustable thresholds) could expand scope significantly. Mitigation: record enhancement opportunities as separate work items linked to this one rather than expanding scope.
• Risk: Sweep cache staleness -- If the user modifies the manifest (adds/removes recipes) and returns to Review, the sweep cache may be stale or missing for new recipes. Mitigation: the swap action already handles missing cache gracefully with an error message.
• Risk: Empty palette state -- The user can remove all entries, leaving the palette empty. The implementation warns the user but does not prevent continued interaction. Mitigation: the confirm/swap actions are hidden from the menu when no selections exist, and the empty state is clearly communicated.
• Assumption: The auditionRecipe() function from explore.ts maintains a stable interface that review.ts depends on.
• Assumption: The ClassificationResult type (with intensity: string, texture: string[], category: string, tags: string[]) will not change during the lifecycle of this work item.

Related work (automated report)

Generated by find_related skill on 2026-03-02. Conservative relevance threshold applied.

Related work items

• Stage 2b -- Audition and Mutation (TF-0MM8S1W4C0NQ1CW6, completed) -- Direct upstream dependency. Provides the auditionRecipe() function that Review's swap action calls, and populates WizardSession.selections with the candidate data (seed, classification) that the palette summary table displays.
• Stage 4 -- Export via Library with Manifest (TF-0MM8S2LKQ1WM38F4, completed) -- Direct downstream dependency (depended-on-by). Consumes the reviewed and refined palette from this stage, promoting selections to the library and exporting WAV files with a manifest. Has an explicit wl dep relationship.
• Stage 2a -- Sweep and Ranking (TF-0MM8S1JZX1GYYQT0, completed) -- Populates the sweep cache (WizardSession.sweepCache) that Review's swap action depends on. If no cached candidates exist for a recipe, the swap fails gracefully.
• TUI Foundation -- Types, Session State, CLI Entry Point (TF-0MM8S0MHO0033HYE, completed) -- Defines the WizardSession, CandidateSelection, and PaletteManifest types that Review directly uses for state management, table building, and coherence checking.
• End-to-End Integration and Polish (TF-0MM8S2ZOH1XPC1X6, open) -- Wires all wizard stages including Review into the complete pipeline with backward navigation and error handling. Blocked by this work item among others.
• Classification Engine Core & Types (TF-0MM0AJ6R01H1XLVU, completed) -- Defines ClassificationResult (with intensity, texture, category, tags fields) that Review uses to populate the summary table and compute coherence. The ordinal scales for intensity and texture in review.ts are derived from this classification taxonomy.
• Add automatic classification to explore sweep pipeline (TF-0MM363OCN13SPE6J, completed) -- Ensures sweep candidates carry ClassificationResult data after the renderAndAnalyze() step. Without this, Review's summary table and coherence checking would have no classification attributes to display.
• Session Save/Resume (Optional) (TF-0MM8S3BDR1QMN6TZ, blocked) -- Depends on all stages being complete. Session serialization must preserve the selections and sweep cache that Review reads and modifies during swap/remove operations.
• Export stage interactive flow and orchestrator integration (TF-0MM8VSX2F0BD2BFT, completed) -- Child of Stage 4, implements the interactive export flow that runs immediately after Review confirms advancement. The runExportStage function receives the session state that Review finalizes.

Related repository files

• src/tui/stages/review.ts -- Primary implementation file (492 lines). Contains ordinal scale definitions, computeMedian(), flagCoherenceOutliers(), buildSummaryRows(), displayPaletteSummary(), and the interactive runReviewStage() flow.
• src/tui/__tests__/review.test.ts -- Test suite (751 lines, 54 tests). Covers all pure helpers (median calculation, deviation flagging, summary row building) and interactive flows (swap, remove, confirm, back, empty palette).
• src/tui/stages/explore.ts -- Contains auditionRecipe() which Review's swap action calls to present cached sweep candidates for re-selection.
• src/tui/types.ts -- Defines CandidateSelection (with classification field carrying intensity/texture data) and WizardSession types that Review operates on.
• src/tui/state.ts -- WizardSession class implementing selection management, manifest editing, and sweep cache access used by Review's swap/remove/add flows.
• src/classify/types.ts -- Defines ClassificationResult type with intensity: string, texture: string[], category: string, tags: string[] fields that Review reads for coherence checking and table display.
• docs/prd/CLASSIFY_PRD.md -- Classification taxonomy specification. Defines the semantic dimensions (category, intensity, texture, material, tags) whose values Review displays in the palette summary table and uses for coherence analysis.
• src/output.ts -- Provides outputTable() used to render the palette summary, and outputSuccess()/outputWarning() used for coherence result messages.
• src/tui/index.ts -- Pipeline orchestrator that dispatches to runReviewStage() (lines 109-118) and handles the Review stage's return value (advance, back) for stage navigation.
• docs/prd/PALLETE_PRD.md -- Future Palette PRD defining style and aesthetic coordination including intensity and texture dimensions. Conceptually related to Review's coherence checking approach but operates at a different abstraction level (style system vs. interactive wizard stage).

[SorraTheOrc]

\n\n**opencode**\n\nImplementation complete. Commit 9d40ecd on branch feature/TF-0MM8S29GD0JJ1WTC-review-and-refine. All 2300 tests pass (54 new review tests), TypeScript compiles clean. Files changed: src/tui/stages/review.ts (+380 lines), src/tui/__tests__/review.test.ts (+530 lines, 54 tests), src/tui/index.ts (updated review dispatch).

[SorraTheOrc]

\n\n**worklog**\n\nClosed with reason: Producer review complete. All 8 acceptance criteria verified against implementation. 54/54 tests pass. TypeScript compiles clean. All 3 child work items closed. Implementation: src/tui/stages/review.ts (492 lines), tests: src/tui/__tests__/review.test.ts (751 lines), orchestrator integration: src/tui/index.ts:109-118. Known limitations documented: alphabetical texture ordering may produce unintuitive coherence flags (future enhancement opportunity).