summaryrefslogtreecommitdiffstats
path: root/docs/superpowers/plans
diff options
context:
space:
mode:
authorDanilo M. <danix@danix.xyz>2026-08-11 11:33:10 +0200
committerDanilo M. <danix@danix.xyz>2026-08-11 11:33:10 +0200
commit694ec02eb652fcfdbf65c27f68f4607f88615f76 (patch)
treeebadaf56a43071878428344ce3bad274470d581c /docs/superpowers/plans
parent00c029a819eca601e9ac58e5c236d667505ac566 (diff)
downloadqtmaildir-694ec02eb652fcfdbf65c27f68f4607f88615f76.tar.gz
qtmaildir-694ec02eb652fcfdbf65c27f68f4607f88615f76.zip
docs: specify item 63, sent mail, in its own design file
The backlog entry could not be planned because it turned on a fact about the user's mail rather than a design choice. Measured against the real database: no `sent` tag exists at all, so the XS branch is dead. Every account keeps sent mail in a folder, and the folders disagree across three shapes, with one account having no sent folder whatsoever. That rules out a `<maildir>/Sent` convention and forces a per-account key. Decisions recorded: a per-account `sent` key composed at run time rather than a shipped [queries] entry, which cannot narrow to the selected account and goes stale when an account is added; an account without the key omitted silently, as `drafts` already is; all-accounts combines and one account scopes through the existing wrap; and recipients on the card in a Sent view, since the sender is the user on every row. Three constraints came from probing rather than memory. A bracketed provider path contains `[` and `]`, which are Xapian syntax, so quoting is load-bearing and the composed query returns its real count only because each path is quoted. notmuch has get_authors and no recipients call at any level, so the To summary must be folded per message in the worker, under the same thread-ownership rule as walkReplies. And GMime's internet_address_list_parse returns NULL for an empty string, which is a crash if unguarded; it also parses a comma inside a quoted display name correctly, so comma-splitting is out. Size revised M, up from S: the recipients half is a new ThreadSummary field, a worker-side per-message walk, the first GMime address parsing in this codebase, and a card that has to know which view it is in. The spec lives in its own file rather than inline. The backlog is past four thousand lines and its job is to say what is open and how big, which a hundred lines of design buries. The entry keeps the finding and the size and points at the spec, following item 53. "Adding to this document" now states the split rule so the next specified item does not land inline again. Account keys and folder names in the spec are placeholders. The counts and the folder shapes are the real measurement and are what the design turns on. Backlog item 63.
Diffstat (limited to 'docs/superpowers/plans')
-rw-r--r--docs/superpowers/plans/2026-08-03-post-0.1.0-usability.md60
1 files changed, 45 insertions, 15 deletions
diff --git a/docs/superpowers/plans/2026-08-03-post-0.1.0-usability.md b/docs/superpowers/plans/2026-08-03-post-0.1.0-usability.md
index 844217e..534dc6e 100644
--- a/docs/superpowers/plans/2026-08-03-post-0.1.0-usability.md
+++ b/docs/superpowers/plans/2026-08-03-post-0.1.0-usability.md
@@ -119,7 +119,7 @@ taking that too literally.
| 60 | Next thread dead-ends on the last reply of an expanded thread | defect | XS | **done**; already fixed by 5487d58, see below |
| 61 | `test_mainwindow` fails intermittently, about 1 run in 20 | testing | S | open; predates the card list, reproduced on f72dba9 |
| 62 | No config option for the date format on a card | presentation | XS | **done** 2026-08-11 |
-| 63 | No way to see sent mail, and no filter for it | workflow | S | open |
+| 63 | No way to see sent mail, and no filter for it | workflow | M | open; specified 2026-08-11 in `specs/2026-08-11-sent-mail-design.md` |
| 64 | The Sync button carries a mailbox icon, not a refresh one | presentation | XS | **done** 2026-08-11 |
| 65 | No full code review and optimization pass | correctness | ? | open, unspecified |
@@ -4141,20 +4141,33 @@ defaults change and it is XS. If it is a path, `Account` needs a `sent` key
beside `drafts`, and the query has to be composed per account, which is where
the S comes from.
-**Approach, pending that decision.** Ask the user first which their setup
-already produces. Their mail is filtered outside qtmaildir (`assets/mailsync.sh`
-is `mbsync` plus `notmuch new`), so the answer is a property of their existing
-filters, not something to design here.
-
-**Constraints.**
-
-- **Do not invent a tag qtmaildir applies itself.** v1 is read-and-organize;
- nothing here sends mail, so nothing here can know a message was sent except by
- where it landed or what tagged it.
-- If it becomes a per-account key, it composes with `scopedQuery()` and must not
- bypass it, or a Sent view in one account shows another account's mail.
-
-**Size: S**, and XS if the answer is "it is a tag".
+### Answered and specified 2026-08-11
+
+**It is a PATH, not a tag**, so the XS branch above is dead. Measured against
+the user's own database: no `sent` tag exists at all, every account keeps sent
+mail in a folder, and the folders disagree across three shapes, with one
+account having no sent folder whatsoever. That is what forces a per-account key
+rather than a `<maildir>/Sent` convention.
+
+The design is at `docs/superpowers/specs/2026-08-11-sent-mail-design.md`; read
+that rather than this entry, which records only the finding. It carries the
+measured folder table, the user's four decisions, and the constraints, of which
+three are worth knowing before opening it: the bracketed provider paths contain `[` and `]`
+and are Xapian syntax, so quoting is load-bearing; notmuch has no recipients
+call at any level, so the To summary is folded per message in the worker under
+the thread-ownership rule; and GMime's address parser returns NULL for an empty
+string.
+
+One thing settled there that reverses nothing: item 2 refused a `To:` line on a
+thread header and that ruling stands. It was scoped to a MIXED conversation,
+where the union of recipients misdescribes itself as "To:". A Sent view is
+one-directional, so the ambiguity it avoided is absent and recipients on the
+card are well posed.
+
+**Size: M**, revised up from S. The query half is the S scoped here; the
+recipients half is a new `ThreadSummary` field, a worker-side per-message walk,
+the first GMime address parsing in this codebase, and a card that has to know
+which view it is in.
## 64. The Sync button carries a mailbox icon, not a refresh one
@@ -4234,3 +4247,20 @@ the same shape: **Observed** (what the user saw), **Cause** (the code, with file
and line, verified not assumed), **Approach**, **Constraints**, and
**Verification** where it is not obvious. Do not renumber. Do not delete: mark
`dropped` with a reason.
+
+**A fully specified item goes in its own file under `docs/superpowers/specs/`,
+not inline here.** This document is a backlog: its job is to say what is open,
+how big it is, and what decides whether it can be picked up. A design that runs
+to a hundred lines buries that under itself, and this file is already past four
+thousand.
+
+The split is by depth, not by size on the day. An entry stays here while it
+records an observation, a cause and an approach. It moves out once it carries
+decisions the user made, measured evidence, and constraints that have to be read
+before writing code. Items 53 and 63 are the pattern: the entry keeps the
+finding and the size, and points at the spec with one line saying to read that
+instead. Carry the two or three constraints a reader needs in order to decide
+whether to open the spec at all, and leave the rest there.
+
+Name the spec `<date>-<name>-design.md`, and state in its header which backlog
+items it resolves, so the numbering stays traceable in both directions.