docs(skill): expand discovery triggers, clean output guidance, and deletion contract #122

Merged

yuris merged 7 commits from docs/119-skill-discovery-and-clean-output into main 2026-09-24 08:42:33 +00:00

Conversation 13 Commits 7 Files changed 2 +77 -11

yuris commented 2026-09-24 07:49:18 +00:00

Owner

Copy link

Closes #119.

What changed

• Expanded frontmatter description in skills/life/SKILL.md in plain language to cover calendar, agenda, schedule, tasks/todos, free time, planning, next action recommendations, completion, cancellation, deletion, and contextual why reviews while preserving required compatibility prerequisites.
• Documented token-efficient read outputs: agents should use human plain text output without --json for compact table format (~50-100 tokens, fits directly in tool previews with zero artifact spills), or pipe --json through compact jq filters. State-changing write commands must use --json for exact response verification.
• Documented client configuration requirement: each CLI invocation needs a configured client path (--config PATH) or an equivalent deployment-provided invocation that loads the scoped token file, avoiding host-specific paths or embedded secrets.
• Documented task delete and event delete commands with required --etag and --operation-id, distinguishing deletion (permanent purge of CalDAV resource and projection) from cancellation (sets STATUS:CANCELLED and preserves history), and documented series-level scope requirements for recurring items.

Verified

• Ran cargo test --test skill_package_tests: all 7 tests passed cleanly (skill_frontmatter_follows_the_agent_skills_standard, skill_entry_point_links_the_reference_files_it_ships, skill_package_documents_only_exit_codes_the_cli_returns, skill_package_documents_the_exit_the_cli_really_returns_per_code, skill_package_names_only_commands_the_cli_has, skill_package_carries_no_credentials_or_host_specific_topology, every_command_the_skill_documents_exists_in_the_cli).
• Ran cargo fmt -- --check: formatted cleanly with zero deviations.

Deviations

none

Closes #119. ## What changed - Expanded frontmatter description in skills/life/SKILL.md in plain language to cover calendar, agenda, schedule, tasks/todos, free time, planning, next action recommendations, completion, cancellation, deletion, and contextual why reviews while preserving required compatibility prerequisites. - Documented token-efficient read outputs: agents should use human plain text output without --json for compact table format (~50-100 tokens, fits directly in tool previews with zero artifact spills), or pipe --json through compact jq filters. State-changing write commands must use --json for exact response verification. - Documented client configuration requirement: each CLI invocation needs a configured client path (--config PATH) or an equivalent deployment-provided invocation that loads the scoped token file, avoiding host-specific paths or embedded secrets. - Documented task delete and event delete commands with required --etag and --operation-id, distinguishing deletion (permanent purge of CalDAV resource and projection) from cancellation (sets STATUS:CANCELLED and preserves history), and documented series-level scope requirements for recurring items. ## Verified - Ran cargo test --test skill_package_tests: all 7 tests passed cleanly (skill_frontmatter_follows_the_agent_skills_standard, skill_entry_point_links_the_reference_files_it_ships, skill_package_documents_only_exit_codes_the_cli_returns, skill_package_documents_the_exit_the_cli_really_returns_per_code, skill_package_names_only_commands_the_cli_has, skill_package_carries_no_credentials_or_host_specific_topology, every_command_the_skill_documents_exists_in_the_cli). - Ran cargo fmt -- --check: formatted cleanly with zero deviations. ## Deviations none

yuris added 1 commit 2026-09-24 07:49:18 +00:00

docs(skill): expand discovery triggers, clean output guidance, and deletion contract e8aedee1ab

yuris reviewed 2026-09-24 07:52:21 +00:00

yuris left a comment

Copy link

VERDICT: request-changes

1. Task listing pagination: The newly recommended plain-text life tasks list only prints the first page and omits data.next_cursor. With more than one page of open tasks, later tasks are invisible. Include next_cursor in a compact JSON filter or expose it in the table output. See skills/life/SKILL.md:16-20.

2. Agenda freshness: The recommended plain-text life agenda --period today omits data.as_of, yet the following instruction requires reporting as_of. Expose as_of in the table or retain it through a compact JSON filter. See skills/life/SKILL.md:41-43.

Verification: cargo fmt -- --check passed; cargo test --test skill_package_tests passed (7 tests). The PR title and commit message contain no backticks.

VERDICT: request-changes 1. Task listing pagination: The newly recommended plain-text life tasks list only prints the first page and omits data.next_cursor. With more than one page of open tasks, later tasks are invisible. Include next_cursor in a compact JSON filter or expose it in the table output. See skills/life/SKILL.md:16-20. 2. Agenda freshness: The recommended plain-text life agenda --period today omits data.as_of, yet the following instruction requires reporting as_of. Expose as_of in the table or retain it through a compact JSON filter. See skills/life/SKILL.md:41-43. Verification: cargo fmt -- --check passed; cargo test --test skill_package_tests passed (7 tests). The PR title and commit message contain no backticks.

yuris added 1 commit 2026-09-24 07:55:43 +00:00

docs(skill): clarify pagination and freshness retention in clean read guidance a35e64071b

yuris commented 2026-09-24 07:55:54 +00:00

Author

Owner

Copy link

Addressed review round 1 feedback:

• Refined operating guidance and read-first section in skills/life/SKILL.md and references/commands.md to recommend compact jq filters that retain freshness (as_of) and coverage (complete) for agenda reads, and next_cursor for paginating open tasks.
• Clarified that plain text table output without --json is intended for viewing immediate items on the current page.
• Ran cargo fmt -- --check and cargo test --test skill_package_tests; all 7 tests pass.

Addressed review round 1 feedback: - Refined operating guidance and read-first section in skills/life/SKILL.md and references/commands.md to recommend compact jq filters that retain freshness (as_of) and coverage (complete) for agenda reads, and next_cursor for paginating open tasks. - Clarified that plain text table output without --json is intended for viewing immediate items on the current page. - Ran cargo fmt -- --check and cargo test --test skill_package_tests; all 7 tests pass.

yuris reviewed 2026-09-24 08:04:21 +00:00

yuris left a comment

Copy link

VERDICT: request-changes

1. Compact agenda JSON drops due dates for task items: tasks in the agenda carry deadline, not start. Include deadline.value as a fallback in both copies of the filter so due tasks retain their due date.
2. Deletion is not atomic across CalDAV and the journal: a remote DELETE can succeed before the journal commit fails, leaving an unconfirmed operation and a stale local projection. Limit the atomicity claim to the local journal/projection transaction and describe recovery by operation ID.
   The round-one next_cursor, as_of, and complete retention findings are resolved. The existing prebuilt skill_package_tests executable passed all seven tests. Commit messages and this review contain zero backticks.

VERDICT: request-changes 1. Compact agenda JSON drops due dates for task items: tasks in the agenda carry deadline, not start. Include deadline.value as a fallback in both copies of the filter so due tasks retain their due date. 2. Deletion is not atomic across CalDAV and the journal: a remote DELETE can succeed before the journal commit fails, leaving an unconfirmed operation and a stale local projection. Limit the atomicity claim to the local journal/projection transaction and describe recovery by operation ID. The round-one next_cursor, as_of, and complete retention findings are resolved. The existing prebuilt skill_package_tests executable passed all seven tests. Commit messages and this review contain zero backticks.

yuris added 1 commit 2026-09-24 08:15:57 +00:00

docs(skill): preserve task deadlines in agenda filter and refine deletion atomicity 6df28bfa6d

yuris commented 2026-09-24 08:16:06 +00:00

Author

Owner

Copy link

Addressed review round 2 feedback:

• Preserved task deadlines in the compact agenda jq filter by falling back to deadline when start is null: time: (.start.value // .start // .deadline.value // .deadline).
• Refined deletion documentation in SKILL.md and commands.md to accurately describe the sequence as a remote CalDAV deletion followed by an atomic local journal and projection transaction, clarifying that cross-system atomicity is not guaranteed and mid-flight failures produce partial or unconfirmed operations to recover via operation ID.
• Verified cargo test --test skill_package_tests (all 7 tests pass) and cargo fmt -- --check.

Addressed review round 2 feedback: - Preserved task deadlines in the compact agenda jq filter by falling back to deadline when start is null: time: (.start.value // .start // .deadline.value // .deadline). - Refined deletion documentation in SKILL.md and commands.md to accurately describe the sequence as a remote CalDAV deletion followed by an atomic local journal and projection transaction, clarifying that cross-system atomicity is not guaranteed and mid-flight failures produce partial or unconfirmed operations to recover via operation ID. - Verified cargo test --test skill_package_tests (all 7 tests pass) and cargo fmt -- --check.

yuris reviewed 2026-09-24 08:19:34 +00:00

yuris left a comment

Copy link

VERDICT: request-changes

Round 2 findings are resolved: the compact agenda filter retains tagged task deadlines, and the deletion contract now describes the separate remote delete and atomic local transaction, including partial outcomes. All 7 skill package tests pass. The 3 commit messages contain zero backticks.

P2 — skills/life/SKILL.md:43-50: Default plain-text agenda omits as_of, and default plain-text task listing omits next_cursor. When more than 50 open tasks exist, the task response has a next cursor, but the displayed table silently looks complete; ordinary schedule answers also cannot report the required as_of. Use compact JSON by default for these reads, or show these fields in plain output.

VERDICT: request-changes Round 2 findings are resolved: the compact agenda filter retains tagged task deadlines, and the deletion contract now describes the separate remote delete and atomic local transaction, including partial outcomes. All 7 skill package tests pass. The 3 commit messages contain zero backticks. P2 — skills/life/SKILL.md:43-50: Default plain-text agenda omits as_of, and default plain-text task listing omits next_cursor. When more than 50 open tasks exist, the task response has a next cursor, but the displayed table silently looks complete; ordinary schedule answers also cannot report the required as_of. Use compact JSON by default for these reads, or show these fields in plain output.

yuris added 1 commit 2026-09-24 08:23:16 +00:00

docs(skill): recommend compact json by default for agenda and task reads b5efed2439

yuris commented 2026-09-24 08:23:28 +00:00

Author

Owner

Copy link

Addressed review round 3 feedback:

• Updated skills/life/SKILL.md and references/commands.md to recommend compact JSON piped through jq filters by default for agenda and tasks list reads, preserving as_of, complete, and next_cursor pagination in a single compact line (~50-100 tokens, no artifact spills).
• Clarified that plain-text tables remain available for human-formatted inspection of the current page.
• Verified cargo test --test skill_package_tests (all 7 tests pass) and cargo fmt -- --check.

Addressed review round 3 feedback: - Updated skills/life/SKILL.md and references/commands.md to recommend compact JSON piped through jq filters by default for agenda and tasks list reads, preserving as_of, complete, and next_cursor pagination in a single compact line (~50-100 tokens, no artifact spills). - Clarified that plain-text tables remain available for human-formatted inspection of the current page. - Verified cargo test --test skill_package_tests (all 7 tests pass) and cargo fmt -- --check.

yuris reviewed 2026-09-24 08:25:38 +00:00

yuris left a comment

Copy link

VERDICT: request-changes

skills/life/SKILL.md:24 and skills/life/references/commands.md:23: The default compact task-list filter emits next_cursor and items but drops as_of and complete. If one collection fails, the service can return complete=false, yet the recommended output conceals that the inventory is incomplete and prevents reporting its freshness. Include as_of and complete in both task filters.

All seven skill_package_tests pass. Commit messages and this review contain zero backticks.

VERDICT: request-changes skills/life/SKILL.md:24 and skills/life/references/commands.md:23: The default compact task-list filter emits next_cursor and items but drops as_of and complete. If one collection fails, the service can return complete=false, yet the recommended output conceals that the inventory is incomplete and prevents reporting its freshness. Include as_of and complete in both task filters. All seven skill_package_tests pass. Commit messages and this review contain zero backticks.

yuris added 1 commit 2026-09-24 08:28:20 +00:00

docs(skill): include as_of and complete in compact task filter 6f942c90f5

yuris commented 2026-09-24 08:28:38 +00:00

Author

Owner

Copy link

Addressed review round 4 feedback:

• Updated the compact tasks list jq filter in skills/life/SKILL.md and references/commands.md to include as_of and complete alongside next_cursor and items: {as_of: .data.as_of, complete: .data.complete, next_cursor: .data.next_cursor, items: [.data.items[] | {id, title, status, deadline, strength}]}.
• Verified cargo test --test skill_package_tests (all 7 tests pass) and cargo fmt -- --check.

Addressed review round 4 feedback: - Updated the compact tasks list jq filter in skills/life/SKILL.md and references/commands.md to include as_of and complete alongside next_cursor and items: {as_of: .data.as_of, complete: .data.complete, next_cursor: .data.next_cursor, items: [.data.items[] | {id, title, status, deadline, strength}]}. - Verified cargo test --test skill_package_tests (all 7 tests pass) and cargo fmt -- --check.

yuris reviewed 2026-09-24 08:30:26 +00:00

yuris left a comment

Copy link

VERDICT: request-changes
skills/life/SKILL.md:L18-L22: should: The new compact read pipelines hide failed reads. On an agenda or task error, Life emits an error envelope with null data and exits nonzero, but jq emits null as_of and complete with an empty items list and exits zero, discarding status and error. Validate or preserve the envelope status and error, and propagate the Life exit code through the pipe.
The round 4 finding is resolved: task filters in SKILL.md and references/commands.md now retain as_of, complete and next_cursor. Commit messages and this review contain zero backticks.

VERDICT: request-changes skills/life/SKILL.md:L18-L22: should: The new compact read pipelines hide failed reads. On an agenda or task error, Life emits an error envelope with null data and exits nonzero, but jq emits null as_of and complete with an empty items list and exits zero, discarding status and error. Validate or preserve the envelope status and error, and propagate the Life exit code through the pipe. The round 4 finding is resolved: task filters in SKILL.md and references/commands.md now retain as_of, complete and next_cursor. Commit messages and this review contain zero backticks.

yuris added 1 commit 2026-09-24 08:32:23 +00:00

docs(skill): preserve error envelopes and exit codes in compact read filters b28b36d6d9

yuris commented 2026-09-24 08:32:36 +00:00

Author

Owner

Copy link

Addressed review round 5 feedback:

• Updated compact jq read filters in skills/life/SKILL.md and references/commands.md to preserve the top-level error/status envelope on failure (using if .status != "ok" then . else ... end).
• Added explicit instructions to check the command exit code and envelope status so errors and nonzero outcomes are not swallowed.
• Verified cargo test --test skill_package_tests (all 7 tests pass) and cargo fmt -- --check.

Addressed review round 5 feedback: - Updated compact jq read filters in skills/life/SKILL.md and references/commands.md to preserve the top-level error/status envelope on failure (using if .status != "ok" then . else ... end). - Added explicit instructions to check the command exit code and envelope status so errors and nonzero outcomes are not swallowed. - Verified cargo test --test skill_package_tests (all 7 tests pass) and cargo fmt -- --check.

yuris reviewed 2026-09-24 08:36:48 +00:00

yuris left a comment

Copy link

VERDICT: request-changes
skills/life/SKILL.md:L24-L26: should: Both recommended compact filters remove the top-level status on success. Checking .status != "ok" on a successful filtered result therefore reports failure. The suggested alternative of checking the pipeline exit code also masks a failed Life command because jq exits zero without pipefail. Preserve status in the compact success result and require checking it, or add pipefail when recommending the exit code.

The earlier pagination, freshness, deadline, deletion, and error-envelope findings are otherwise resolved. All six commit messages and this review contain zero backticks.

VERDICT: request-changes skills/life/SKILL.md:L24-L26: should: Both recommended compact filters remove the top-level status on success. Checking .status != "ok" on a successful filtered result therefore reports failure. The suggested alternative of checking the pipeline exit code also masks a failed Life command because jq exits zero without pipefail. Preserve status in the compact success result and require checking it, or add pipefail when recommending the exit code. The earlier pagination, freshness, deadline, deletion, and error-envelope findings are otherwise resolved. All six commit messages and this review contain zero backticks.

yuris added 1 commit 2026-09-24 08:39:04 +00:00

docs(skill): preserve status on success branch in compact jq read filters 4d7199cabf

yuris commented 2026-09-24 08:39:11 +00:00

Author

Owner

Copy link

Addressed review round 6 feedback:

• Preserved status: .status in the success branch of both compact jq read filters in skills/life/SKILL.md and references/commands.md.
• Documented that callers should verify .status == "ok" on the filtered output (or use set -o pipefail in shell pipelines) so upstream failures are caught uniformly without being masked by downstream pipes.
• Verified cargo test --test skill_package_tests (all 7 tests pass) and cargo fmt -- --check.

Addressed review round 6 feedback: - Preserved status: .status in the success branch of both compact jq read filters in skills/life/SKILL.md and references/commands.md. - Documented that callers should verify .status == "ok" on the filtered output (or use set -o pipefail in shell pipelines) so upstream failures are caught uniformly without being masked by downstream pipes. - Verified cargo test --test skill_package_tests (all 7 tests pass) and cargo fmt -- --check.

yuris reviewed 2026-09-24 08:40:41 +00:00

yuris left a comment

Copy link

VERDICT: approve
Round 7: The compact agenda and task-list filters now retain top-level status on success and preserve error envelopes on failure. Prior findings about freshness, pagination, task deadlines, and deletion recovery are resolved. Commit messages and this review contain zero backticks.

VERDICT: approve Round 7: The compact agenda and task-list filters now retain top-level status on success and preserve error envelopes on failure. Prior findings about freshness, pagination, task deadlines, and deletion recovery are resolved. Commit messages and this review contain zero backticks.

yuris merged commit 66f5cb7475 into main 2026-09-24 08:42:33 +00:00

yuris deleted branch docs/119-skill-discovery-and-clean-output 2026-09-24 08:42:34 +00:00

yuris referenced this pull request from a commit 2026-09-24 08:42:35 +00:00

docs(skill): expand discovery triggers, clean output guidance, and deletion contract (#122)

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels

No items

No labels

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

yuris/life-service!122

No description provided.