CLI, hooks, runners, and Python library for the Scout productivity system. Manages action items with markdown-based storage, prefix-based IDs, and event tracking.
Scout Engine provides 9 action-item management tools with complete input schemas and descriptions. Naming is verb-forward (mark-done, snooze, add-comment) and generally clear. Descriptions are present and substantive (avg ~120 chars), explaining WHAT each tool does and WHEN to use it. However, parameter descriptions lack actionable constraints (no enums for 'priority' filter, no format specs for dates/IDs), and output schemas are entirely undocumented, LLMs cannot predict response structure for chaining. Error handling is minimal; no recovery guidance. Security is reasonable (file-based, no secrets exposed), but composition shows legacy patterns: 'subject' substring matching alongside 'by_id' creates ambiguity, and comment operations (add/delete/edit) could be unified. Baseline: avg tool score 62/100.
Append a comment beneath an action item. Inserts a ` - <author>: <comment>` sub-bullet directly beneath the matched task line.
Add [#XXXX] short prefixes to action-items lines that lack them. Idempotent: re-running on a file that already has prefixes is a no-op.
Delete a comment sub-bullet beneath an action item. Removes a single ` - <author>: <text>` line attached to the matched task.
Replace the body of an existing comment beneath an action item. Preserves the ` - <author>: ` prefix and the original indent — only the body text changes.
Enumerate action items from a daily markdown file with optional filters by priority, section, and completion status.
Mark an action-item complete by ID prefix or by subject substring. Flips checkbox from [ ] to [x] or [X]. Supports --undo to reopen a completed task.
Output schemas completely undocumented. No tool declares what fields it returns, forcing LLMs to guess response structure and breaking tool chaining.
Parameter constraints missing. 'priority' in list() accepts free-form strings instead of enum {high, medium, low}. Date parameters (until in snooze) lack format specs. ID parameters lack pattern validation (2-8 [A-Z0-9]).
Dual lookup strategy (subject substring + by_id) creates ambiguity. LLMs must reason about which to use; if both match, behavior is undefined. Should deprecate 'subject' in favor of stable 'by_id'.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 62 | 2026-07-28+ | v2 |
Mint a fresh non-colliding [#XXXX] short prefix for action items.
Render action items from a daily markdown file to formatted output.
Snooze an action item until a specified date. Adds a snoozed-until marker beneath the task with the target date and optional source section kind.
Error handling absent. No guidance on what to do if task not found, file missing, or ID collision occurs. LLMs receive raw errors with no recovery path.
Comment operations (add/delete/edit) are separate tools but operate on the same resource. Consider a unified 'manage-comment' tool with an 'action' enum, or document when to use each.