Next steps (handoff for new chat)

Continuation guide after the Lib DRY extraction and AI readability documentation work. Start a new chat with: “Continue from docs/NEXT_STEPS.md” and point the agent at this file.

Completed (do not redo)

DRY shared libs (code)

• lib/text_util.rb — squish, truncate, title_words, format_count

• lib/search_query.rb — catalogue query normalization

• lib/search_report.rb — IRC card builders + SearchLookup.format

• lib/cursor_agent_questions.rb — cursor-agent askQuestion parsing

• lib/directchat_session_codec.rb — session stringify/symbolize, sanitize_line

• lib/directchat_mirc_parse.rb — popup_item_line?, safe_read (catalog only; inventory keeps its own popup_item_line?)

Migrated callers: catalogue trio (auslib/qldlibrary/qldmuseum), cursor agents, directchat wire/session/dcc, TextUtil sweep across search/report modules.

AI readability docs (no code changes)

• AGENTS.md — orientation map

• lib/LIB_INDEX.md — domain → lib files

• lib/CONTRACTS.md — return shapes

• docs/PLUGIN_INDEX.md — command → plugin → lib

• docs/architecture.md — mermaid flows

• test/README.md — tests and fixtures

• .cursor/rules/rabbot.mdc — always-on Cursor rule

Large file splits (Priority 1 — done)

• lib/car_search.rb → car_search/{query,listings,details,filter}.rb

• lib/directchat_mirc_inventory.rb → directchat_mirc/{inventory_metadata,extractors,inventory_report}.rb

• lib/rabbot_db.rb → rabbot_db/{connection,migrations,channels,users,plugin_data}.rb

• lib/animal_news.rb → animal_news/{parse,format,fetch,plugin}.rb

• lib/geo_lookup.rb → geo_lookup/{geocode,place,format}.rb

• lib/ai_chat_core.rb → ai_chat_core/{context,plan}.rb

• lib/directchat_prd.rb → directchat_prd/{core,legacy_caveats,companion_bot,foundations}.rb

Priority 1 large-file splits are complete. Priority 2 lib subdirectories are complete. Priority 3 module headers in progress (cluster batches done; ~143 flat libs remain).

Theme plugin migration (S0–S12 done; phase 2 S13+)

Sprint backlog and plugin inventory: docs/THEME_MIGRATION.md.

Done (S0–S12): ThemeOutput, FloodSafeTheme, ThemePaintRules, ~96 PaintSamples, runtime wiring on ~90 plugins, progress gutter (MessageProgress, FloodSafe :auto, ReplyLayout).

Phase 2 (S13+): Clock cluster shims, irc_ping_ms for progress digit 3, replace stub samples (S4–S11) with real formatter output, colon alignment, optional progress theming and ThemeFrame doodles. See S13+ sprint table in THEME_MIGRATION.md.

Priority 1 — Large file splits (remaining)

All items done — see list above.

Priority 2 — Lib subdirectories (complete)

Prefix clusters moved into folders; re-export shims remain at old paths. Do not edit lib/vendor/.

Done

• lib/clock/ — flip, report, segment, wordnet, … (shims at clock_*.rb)

• lib/sunbus/ — gtfs, connect, format, config, … (shims at sunbus_*.rb)

• lib/directchat/ — wire, session, mesh, mirc_*, prd, … (shims at directchat_*.rb; directchat_mirc/ and directchat_prd/ stay at repo root)

• lib/ai/ — agent, access, guard, plan_session, … (shims at ai_*.rb; ai/chat_core/ context + plan)

Priority 3 — Module headers (cheap, incremental)

When touching any lib file, add a standard header:

# frozen_string_literal: true

# ModuleName — one-line purpose.
# Public: method_a, method_b
# Depends: OtherModule, rabbot_http
# Tests: test/lib/module_test.rb

Apply first to domains in Priority 1 splits and any new code.

Progress (module headers)

• Done: Priority 1 splits (car_search, rabbot_db, animal_news, geo_lookup, ai/chat_core, directchat_prd, directchat_mirc)

• Done: DRY shared libs (text_util, search_query, search_report, cursor_agent_questions, directchat session_codec + mirc_parse)

• Done: sunbus/ cluster (13 impl files + 13 shims)

• Done: directchat/ cluster (7 impl + 11 shims including prd + mirc_inventory)

• Done: ai/ cluster (19 impl + 19 shims; chat_core subtree already had headers)

• Done: clock/ cluster (8 impl + 8 shims)

• Done: rabbot_meta (5 files: agent, build, queue, plan_session, ai_cooldown)

• Done: catalogue trio (auslib, qldlibrary, qldmuseum — 9 config/search/report files)

• Done: bot/bot_console (11 files: identity, options, log_store, console facade + 7 nested)

• Done: govau cluster (9 files: config, ckan, ptv, tfnsw, routes, status, derby games)

• Remaining: flat lib files (~143) — opportunistic as you touch them

Priority 4 — Remaining DRY (low priority)

Only if touching these areas anyway:

Note: lib/directchat_mirc_inventory.rb popup_item_line? intentionally differs from lib/directchat_mirc_parse.rb — do not unify without comparing tests.

Priority 5 — Documentation maintenance

• Regenerate PLUGIN_INDEX.md when adding plugins — consider a script/generate_plugin_index.rb rake task that scans # Help: + require_relative lines.

• Extend CONTRACTS.md when adding new { error: :symbol } patterns or plugin JSON schemas.

• Add fixtures for any new HTTP-backed lib (test/README.md).

Priority 6 — Optional tooling

• script/generate_lib_index.rb — glob lib/**/*.rb → update LIB_INDEX domain tables (human review required).

• CI check: fail if new truncate_text / parse_query duplicates appear outside shared libs (grep-based lint).

Suggested order for a new session

1. Apply Priority 3 module headers when touching flat libs under lib/.

2. Update LIB_INDEX.md when paths change.

3. Run the relevant test suite for the area you change.

Key references for the agent

Scope choices from prior planning

• Lib DRY (first pass): shared helpers only — no large-file splits.

• AI readability: docs + Cursor rules only — no code refactors.

• Full phased plan (splits + subdirs + all DRY) was explicitly deferred — this file is the backlog.