docs(projects): document taskCount and openCount - #207
Merged
Merged
Conversation
`things projects -j` has reported `taskCount` and `openCount` since the counts were added for the progress icon, but nothing said what they count, so the only documented way to find a project whose work has all landed was one `things list` per project. Document both fields in the three places project JSON is described, and add a "projects with no open to-dos" recipe for the daily reconcile. The semantics were verified against the live database rather than inferred from the column names: across 82 projects the cached counters `untrashedLeafActionsCount` and `openUntrashedLeafActionsCount` match a recount of untrashed type-0 children exactly, including to-dos filed under a heading, which carry `heading` but not `project`. Heading rows, trashed to-dos and checklist items are excluded. Three caveats are documented because each one can mislead a caller acting on the recipe: - `taskCount - openCount` is to-dos that are no longer open, which means completed or cancelled. A project whose to-dos were all cancelled matches the same filter. - The `●` icon marks any completed project under `--completed`, including one with no to-dos at all, so it is not identical to the filter there. - A repeating to-do makes a project unreachable by the filter: Things counts the hidden template row as an open to-do and it never completes, while `things list -p` hides that template, so the two disagree. No behaviour change; no Go code touched. Closes #203
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #203
What changed
Docs only.
things projects -jhas reportedtaskCountandopenCountsince the counts were added to drive the progress icon, but nothing said what they count, so the only documented way to find a project whose work had all landed was onethings listper project. This documents both fields and adds a jq recipe for the daily reconcile.internal/skill/SKILL.md— a bullet in "Output and--json", two comment lines on thethings projectsreference line, and a "projects with no open to-dos" recipe in "Common flows".docs/content/commands.md— a block in "Listing", after the paragraph about projects carryingstart/startBucket/startDate/deadline.docs/content/agents.md— a bullet in "Script it with--json" and a line in the recipe block.No new flags, no new JSON fields, no change to plain-text output, no Go code touched. The user decided to keep the existing field names rather than the
openTodoCount/completedTodoCountthe issue proposed, and to leave the●progress icon as the human-output answer.Why these semantics, and how they were verified
The fields come straight from Things' own columns
untrashedLeafActionsCountandopenUntrashedLeafActionsCount. Rather than infer the meaning from the column names, I checked them against real data withsqlite3 -readonlyon the live database and on a backup snapshot, recounting each project's children and comparing:A deliberately wrong value matched zero rows, confirming the comparison detects divergence rather than passing vacuously.
What that established, and what the docs now say:
projectNULL and points only atheading, so a correct recount has to union direct children with the children of the project's headings. Ignoring headings gives the wrong total for exactly the 7 projects here that have them.Three caveats, each documented
Each one can mislead someone acting on the recipe:
taskCount - openCountcounts to-dos that are no longer open, which means completed or cancelled. 23 projects here contain at least one cancelled to-do, so a project whose to-dos were all cancelled matches the same filter.--completedthe●icon marks any completed project, including one with no to-dos at all, so the icon and the filter are not identical there. Verified against a fixture database.things list -phides that template, so the two disagree, and that is now called out.How it was verified
make testandmake lintgreen (lint reports 0 issues; the warning names a stale sibling worktree unrelated to this change).hugobuilds the site and renders the new sections.things skill show.Rebased on
mainafter #201 (#205) landed. It also appended a bullet to the same SKILL.md list, so both bullets are kept, that one first.