Search Initialization Deferral Implementation Plan
For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
Goal: Delay non-essential search initialization work until the user opens search, reducing startup cost while preserving the same search experience once used.
Architecture: Keep MkDocs Material search feature enabled, but move any custom search-adjacent enhancement work or expensive search-related fetch behavior out of the initial page path where possible. The plan should prefer delaying enhancement and initialization hooks, not rewriting core Material search internals.
Tech Stack: MkDocs Material, vanilla JavaScript, existing search UI, event-driven lazy initialization
Task 1: Identify what search work actually happens before user interaction
Files:
- Inspect: mkdocs.yml
- Inspect: docs/javascripts/extra.js
- Inspect: any scripts touching search UI or search_index.json
Step 1: Write the failing test
Manual failing criteria: - Search-related resources initialize or fetch before the user opens the search UI. - Custom code may be doing work around the search component too early.
Step 2: Run verification to confirm failure
Use browser Network/Performance reasoning from current project context to identify whether early search work is caused by: - core MkDocs Material search bundle - custom site code - both
Expected: FAIL because search work is currently on the startup path.
Step 3: Write minimal implementation strategy
Determine the narrowest safe deferral approach: - If only custom search-adjacent code exists, defer that code until search opens. - If Material core preloads unavoidable search assets, do not hack internals unsafely; instead defer only custom enhancement work and document remaining constraint.
Step 4: Run verification to confirm understanding
Expected: clear attribution of what can and cannot be deferred safely.
Step 5: Commit
git add <only files changed if instrumentation or comments were needed>
git commit -m "chore: document search initialization constraints"
Task 2: Defer custom search enhancement work until search is opened
Files: - Modify: exact custom JS file(s) only if they touch search behavior or UI - Verify: search dialog behavior on any page
Step 1: Write the failing test
Manual failing criteria: - Search-related custom logic runs before the user opens search. - Opening search later should still behave identically after deferral.
Step 2: Run verification to confirm failure
Expected: FAIL because custom logic currently runs too early.
Step 3: Write minimal implementation
- Add lazy one-time initializer triggered by user opening search (
__search, search button, or search component visibility) - Keep all existing functionality once search is opened
- Avoid modifying MkDocs Material bundle directly
- Avoid breaking keyboard shortcuts, search suggestions, or highlight behavior
Step 4: Run verification to confirm it passes
Expected: - No regression in search open behavior - First open may initialize lazily but remains acceptable - No repeated initialization on later opens
Step 5: Commit
git add <exact modified JS files>
git commit -m "perf: defer custom search initialization until open"
Task 3: Verify search UX remains unchanged after lazy init
Files: - Verify only unless regression found
Step 1: Write failing verification checklist
Failure conditions: - Search dialog no longer opens instantly enough - Search suggestions/highlighting break - Search initializes multiple times - Keyboard-triggered search breaks
Step 2: Run verification
Test: - click search icon - use keyboard shortcut if supported by theme - type query - inspect search results, suggest, highlight behavior
Step 3: Minimal implementation if needed
Only fix regressions caused by deferral. No unrelated cleanup.
Step 4: Re-run verification
Expected: search experience remains functionally unchanged after opening.
Step 5: Commit
git add <only files changed during regression fix>
git commit -m "fix: preserve search behavior after lazy initialization"
Plan complete and saved to docs/plans/2026-03-07-search-init-deferral-plan.md. Two execution options:
1. Subagent-Driven (this session) - I dispatch fresh subagent per task, review between tasks, fast iteration
2. Parallel Session (separate) - Open new session with executing-plans, batch execution with checkpoints
Which approach?