| 1 | # Visualization Candidate Recall |
| 2 | |
| 3 | Default Strategist and the Quick Generate main agent read the complete Chart |
| 4 | and Table expression vocabularies before planning. |
| 5 | `visualization_recall.py validate` resolves their selected canonical |
| 6 | references. Its `recall` command remains an optional deterministic diagnostic |
| 7 | across the machine Chart and Table registries; it is not the runtime |
| 8 | capability-discovery gate and cannot replace the complete planning review. The |
| 9 | tool reads these indexes on every invocation and maintains no second category |
| 10 | or keyword index: |
| 11 | |
| 12 | - `templates/charts/chart-vocabulary.md` — planning capability map, not read by this tool |
| 13 | - `templates/charts/charts_index.json` |
| 14 | - `templates/tables/table-vocabulary.md` — planning capability map, not read by this tool |
| 15 | - `templates/tables/tables_index.json` |
| 16 | |
| 17 | Qualitative Structure does not enter recall. Default records its relationship |
| 18 | model in §IX; Quick keeps the same decision in active context. Both load |
| 19 | `executor-structure.md` and compose the shapes for the current page. |
| 20 | |
| 21 | ## Optional recall diagnostics |
| 22 | |
| 23 | Describe one page's information shape with 3-8 concise English semantic tags. |
| 24 | Translate source-language or industry terms into structural meaning first. |
| 25 | |
| 26 | ```bash |
| 27 | python3 skills/ppt-master/scripts/visualization_recall.py recall \ |
| 28 | --page P03 \ |
| 29 | --tag "time series" \ |
| 30 | --tag "three metrics" \ |
| 31 | --tag "direction over time" \ |
| 32 | --limit 6 |
| 33 | ``` |
| 34 | |
| 35 | Use `--family chart|table` only when the page semantics already make that |
| 36 | boundary certain; the default `all` preserves unified Chart/Table recall. |
| 37 | `--limit` accepts 3-8 and defaults to 6. Read the returned JSON unfiltered: |
| 38 | `tail`, `head`, `grep`, or another truncator can discard higher-ranked |
| 39 | candidates. `confidence` reports lexical strength only and never decides fit. |
| 40 | |
| 41 | At any confidence, compare the diagnostic candidates against the complete |
| 42 | planning maps already loaded. `--semantic-fallback` only exposes another |
| 43 | diagnostic payload; it never requires a selection. Retain `no-template-match` |
| 44 | when none fits. |
| 45 | |
| 46 | | Field | Contract | |
| 47 | |---|---| |
| 48 | | `page` | Input `P<NN>` page key | |
| 49 | | `family_filter` | Requested family or `all` | |
| 50 | | `semantic_tags` | Deduplicated input tags | |
| 51 | | `confidence` | Lexical recall strength; never a selection decision | |
| 52 | | `candidates` | Ranked family/key references, SVG paths, summaries, scores, and matched tags | |
| 53 | | `semantic_fallback` | Selected live catalogs, present only with `--semantic-fallback` | |
| 54 | | `no_template_match` | Explicit fallback; blocked at low/none until semantic fallback review | |
| 55 | |
| 56 | The scorer treats the key and summary Pick clause as positive evidence and the |
| 57 | Skip clause as negative evidence. A term found only in Skip cannot make a |
| 58 | candidate eligible. Unicode input is NFKC-normalized before matching. The |
| 59 | active profile owner still applies semantic judgment and prefers the most |
| 60 | specific valid information structure. |
| 61 | |
| 62 | ## Validate selected references |
| 63 | |
| 64 | Validate every selected reference before Default writes Design Spec §VII and |
| 65 | `spec_lock.md page_visualizations`, or before Quick opens it for immediate use: |
| 66 | |
| 67 | ```bash |
| 68 | python3 skills/ppt-master/scripts/visualization_recall.py validate \ |
| 69 | chart/line_chart table/record_table |
| 70 | ``` |
| 71 | |
| 72 | The command is read-only. It exits `0` when every supplied reference resolves |
| 73 | to a registered SVG and `1` otherwise. New planning supplies canonical |
| 74 | `family/key`. When validating an existing legacy mapping, opt into bare-key |
| 75 | resolution explicitly; every key must resolve uniquely: |
| 76 | |
| 77 | ```bash |
| 78 | python3 skills/ppt-master/scripts/visualization_recall.py validate \ |
| 79 | --legacy-bare pros_cons_chart |
| 80 | ``` |
| 81 | |
| 82 | A Default `no-template-match` page appears in neither §VII nor |
| 83 | `page_visualizations`; record its custom fallback in §IX. A qualitative |
| 84 | Structure is not a no-match case: describe its relationships in §IX and build |
| 85 | it without catalog lookup. |
| 86 | |
| 87 | ## Selection boundary |
| 88 | |
| 89 | - Runtime selection comes from the complete loaded Chart vocabulary and Table |
| 90 | registry; recall output is optional diagnostic evidence, while `validate` |
| 91 | resolves positive selections. |
| 92 | - Default records `Page | Family | Template | Usage` for each positive |
| 93 | selection and projects `family/key` into `page_visualizations`. |
| 94 | - Usage is one concise page-local purpose; detailed adaptation remains in §IX. |
| 95 | - Quick keeps the selected reference and purpose only in active context. |
| 96 | - Structure is a separate runtime information model, never a catalog candidate |
| 97 | or `page_visualizations` entry. |
| 98 | - Never serialize `no-template-match`, empty tables, summaries, paths, or |
| 99 | runners-up into planning artifacts. |
| 100 | - Open only the selected SVG for its mapped page. It is a flexible reference, |
| 101 | not a type, geometry, style, or native-replacement lock. |
| 102 | |
| 103 | ## Legacy compatibility |
| 104 | |
| 105 | `chart_recall.py` remains a compatibility wrapper for existing callers. It |
| 106 | uses the same scorer and live Chart/Table registries, preserves bare-key |
| 107 | validation and the historical JSON shape, and resolves live candidates to their |
| 108 | current family paths. New prompts and automation use `visualization_recall.py`. |
| 109 | |
| 110 | When `validate --legacy-bare` receives one of the 36 retired canonical Structure |
| 111 | bare keys, the shared resolver returns `kind=legacy-structure-intent`, |
| 112 | `family=structure`, and the original key without `path` or `reference`. This |
| 113 | compatibility result is a semantic hint for old `page_charts`, not a live catalog |
| 114 | entry, and never participates in recall. |
| 115 |