miti99bot/docs/command-parameter-conventions.md

Command Parameter Conventions

Overview

Every Telegram command declares optional Parameters metadata. The bot reuses that string in /help and Telegram's native command menu, so it must be short, consistent, and understandable on a phone.

Treat Parameters as display syntax, not as a validation schema. Handlers remain responsible for parsing and validation.

Syntax

Meaning	Format	Example
Required value	<name>	<ticker>
Required comma-separated values	<name,...>	<option,...>
Optional value	[name]	[date]
Optional remaining text	[name...]	[target...]
Alternatives in an optional group	`[literal	literal ]`

Use only constructs required by the command. Do not introduce a formal schema language or extra punctuation without a user-facing need.

Naming

• Use lowercase snake_case.
• Prefer one descriptive noun: <ticker>, <quantity>, <champion>.
• Include units or currencies when they prevent ambiguity: <vnd_amount>, <usd_to_spend>.
• Do not add primitive types such as <quantity:number> or <date:string>.
• Keep literal subcommands bare: users, user, cmd.
• Put spaces around | in alternatives.
• Do not repeat format prose inside a placeholder.
• Show punctuation that users must type exactly when omitting it would be error-prone. <ratio(owned:new)> and <option,...> are approved compact shapes.

Examples

/stock_buy <quantity> <ticker>
/lol [date]
/trongtruonghop [target...]
/stats [users | user <username> | cmd <command_name>]
/stock_share_dividend <ratio(owned:new)> <ticker>
/random <option,...>

Change Checklist

When adding or changing a command:

1. Make Parameters match the handler's accepted argument order.
2. Keep the parameter string single-line and concise enough for Telegram's command-description limit.
3. Update handler usage and error text to use the same syntax.
4. Update registration, handler, /help, and native-menu tests.
5. Update README or feature documentation when behavior is user-visible.
6. Follow the stats migration rules in AGENTS.md when a command name changes or a command is deleted.

References

• POSIX.1-2024 utility conventions
• GNU command-line interface standards
• Microsoft command-line syntax key
• Python argparse documentation
• docopt usage-pattern grammar

The supporting project-specific analysis is in plans/reports/260721-1418-command-parameter-schema-research.md.