Structured hint and help system for CLI guidance

[djdarcy]

Structured hint and help system for CLI guidance

Summary

Create a reusable, templatized hint/help infrastructure for providing contextual guidance to users — error recovery suggestions, usage tips, quantifier recommendations, and progressive feature discovery.

Currently, hints are ad-hoc strings scattered across the codebase (e.g., the "Missing bounds" error in find_matches(), the quantifier suggestion in #53). As the tool grows more quantifiers (#51 solve), output modes (#55 formatting), and features, a structured system will keep hints consistent, maintainable, and context-aware.

Motivation

Multiple upcoming features need hints:

• Quantifier UX: helpful hints for does_exist + --limit N for bounded for_any enumeration #53: "Tip: Use for_any to find all matches" when does_exist returns one result
• Sequence enumeration without comparison (for_any expr) #36/Add solve quantifier for expression evaluation and algebraic solving #51: "Use solve to compute a value, or verify to check truthiness" when quantifier doesn't fit
• Configurable output formatting for expression results #55: Format option suggestions when output looks wrong
• General: Progressive disclosure — show new users basic tips, show advanced users feature tips

Without a system, each feature reinvents hint formatting, placement, and deduplication.

Prior Art

A templatized help system already exists in C:\code\modified_datetime_fix\local\folder_datetime_fix\help_lib\. Key components worth adapting:

Core pattern (HelpContent dataclass):

@dataclass
class HelpContent:
    id: str                     # 'quantifier.does_exist_multi_var'
    command: str                # Example command template with {prog}, {vars}
    description: str            # What the hint explains
    category: str               # 'quantifier', 'format', 'iteration', etc.
    contexts: Set[str]          # When to show: {'error', 'verbose', 'help'}
    priority: int               # Display order (lower = higher priority)
    variables: Dict[str, str]   # Template variable defaults

Useful patterns from that system:

1. Context-aware display — same hint shown/hidden based on context (error recovery, --verbose tips, --help output)
2. Template variables — hints use {prog} and {vars} placeholders, resolved at render time
3. Format separation — content doesn't know how to render itself; formatters handle text vs compact vs tutorial styles
4. Smart deduplication — tracks what's been displayed, avoids repeating the same tip in one session
5. Section-based organization — each feature area owns its hints in a separate file
6. Priority ordering — most relevant hints shown first

Source files (for reference/adaptation):

• C:\code\modified_datetime_fix\local\folder_datetime_fix\help_lib\core.py — Core classes
• C:\code\modified_datetime_fix\local\folder_datetime_fix\help_lib\formatters.py — Formatter implementations
• C:\code\modified_datetime_fix\local\folder_datetime_fix\help_lib\content_registry.py — Central registry
• C:\code\modified_datetime_fix\local\folder_datetime_fix\help\help_manager.py — Orchestrator
• C:\code\modified_datetime_fix\local\folder_datetime_fix\help\sections\ — Content sections

Proposed Design for Prime-Square-Sum

Lightweight adaptation — we don't need the full system from day one. Start with:

1. Hint registry — dictionary or simple module mapping hint IDs to templates:

   HINTS = {
       'quantifier.use_for_any': 'Tip: Use "for_any" quantifier to find all matches in the search space.',
       'quantifier.use_solve': 'Tip: Use "solve" to compute a value, or "verify" to check truthiness.',
       'quantifier.use_verify': 'Tip: Use "verify" for expressions without free variables.',
       'bounds.missing': 'Use {suggestions} to specify bounds for {vars}.',
   }

2. Context-aware display — hints only shown when relevant:

   • Error context: Shown in error messages as suggestions
   • Verbose context: Shown with --verbose as tips after results
   • Help context: Shown in --help output as examples

3. Stderr output — hints always go to stderr so they never corrupt stdout data (JSON, CSV, piped output)

4. Progressive growth — start with a few key hints, add more as features land

Example Hint Points

When	Hint	Context
does_exist finds match, 2+ free vars	"Use for_any to find all matches"	verbose, after result
for_any with no free vars, no comparison	"Use solve to compute a value"	error recovery
does_exist with bare term (no comparison)	"Use for_any to enumerate values"	error recovery
verify with free variables	"Use does_exist or for_any for expressions with variables"	error recovery
First run / new user	Random tip from pool	verbose

Acceptance Criteria

• Hint content separated from display logic
• Hints use template variables (not hardcoded command strings)
• Hints go to stderr (never corrupt stdout)
• Context-aware: different hints for error vs verbose vs help
• Easy to add new hints without modifying display logic
• Tests for hint rendering and context filtering

Related Issues

• Quantifier UX: helpful hints for does_exist + --limit N for bounded for_any enumeration #53 — Quantifier UX: helpful hints for does_exist (first consumer of this system)
• Sequence enumeration without comparison (for_any expr) #36 — Sequence enumeration (needs "use solve/verify" hints for edge cases)
• Add solve quantifier for expression evaluation and algebraic solving #51 — solve quantifier (new quantifier = new hint opportunities)
• Configurable output formatting for expression results #55 — Output formatting (format-related hints)
• Multi-level verbosity system (-v, -vv, -vvv) #31 — Multi-level verbosity (hints shown at different verbosity levels)

Analysis

See 2026-02-08__11-01-03__issue36-sequence-enumeration-and-solve-quantifier-analysis.md (Addendum: 2026-02-08 13:10) for research on the modified_datetime_fix help system and adaptation recommendations.