experiments in a post-browser web
docs(peek-tasks): document peek:ready / peek:triage quality markers and peek:wontfix terminal state
The peek-tasks skill now reflects the triage-pass vocabulary:
- New "Quality markers" section: every active peek:todo carries
peek:ready (scoped, queue-ready) or peek:triage (needs scoping).
Default actionable view is peek:todo ∩ peek:ready.
- New "peek:wontfix" terminal state for items closed without shipping
(analysis concluded "don't do this", or fix is blocked indefinitely).
- peek:deferred retired — Don'ts list calls this out and points to
peek:wontfix (close) or peek:triage (decision needed).
- Status transitions table updated: every transition out of peek:todo
also clears the peek:ready/peek:triage marker, so items don't carry
stale quality flags through wip → done.
- Quick recipes updated; added "close as wontfix" and "triage → ready"
flows; removed the old "Defer this" recipe.
- create_item recipe now requires a quality marker on new items.
- List recipe defaults updated: top-of-page query is
list_items({ tags: ['peek:todo', 'peek:ready'] }), not the unfiltered
todo dump.
Counts in the skill body match post-triage state (~258 todos, 53
ready, 203 triage). The bare #peek tag handling is unchanged.
+71
-22
+71
-22
.claude/skills/peek-tasks.md
+71
-22
.claude/skills/peek-tasks.md
···
31
31
Every task is a Peek item with the `peek:todo` status tag plus at
32
32
least one domain or type tag from this controlled list:
33
33
34
-
- **Status**: `peek:todo`, `peek:wip`, `peek:blocked`, `peek:deferred`, `peek:done`
34
+
- **Status**: `peek:todo`, `peek:wip`, `peek:blocked`, `peek:done`, `peek:wontfix`
35
+
- **Quality** (additive to `peek:todo`): `peek:ready`, `peek:triage`
35
36
- **Domain**: `peek:desktop`, `peek:mobile`, `peek:tauri`, `peek:atproto`, `peek:extensions`
36
37
- **Type**: `peek:bug`, `peek:feature`, `peek:test-coverage`, `peek:docs`, `peek:design`, `peek:security`, `peek:tile-arch`, `peek:meta`, `peek:tooling`, `peek:daily-use`
37
38
39
+
### Quality markers
40
+
41
+
Items in the active queue (`peek:todo`) carry one of two quality markers:
42
+
43
+
- **`peek:ready`** — scoped, queue-ready, can be picked up. Concrete bugs (clear repro or symptom) and small features with known target behavior.
44
+
- **`peek:triage`** — needs scoping conversation before work can start. Vague ideas, vocab musings, big features without scope, exploratory questions.
45
+
46
+
Use the intersection to find actionable work:
47
+
`list_items({ tags: ['peek:todo', 'peek:ready'] })`.
48
+
49
+
### `peek:wontfix` — terminal state
50
+
51
+
Closed without shipping. Use when the analysis concludes "don't do
52
+
this" (security gap is theoretical, lazy lifecycle is doing what we
53
+
want, etc.) or when a fix is blocked indefinitely on something we
54
+
won't pursue. **Don't use `peek:deferred`** — it's been retired. If
55
+
you'd reach for "deferred," the right move is either:
56
+
- Close as `peek:wontfix` if the analysis says we're not going to do it.
57
+
- Tag `peek:triage` if the path forward needs to be decided.
58
+
38
59
The bare `#peek` tag is the legacy project membership marker — leave
39
60
it alone on existing items, but **don't add `#peek` to new items**.
40
61
The `peek:*` namespace is implicit project membership.
···
52
73
53
74
- Title is what shows in lists — keep it scannable.
54
75
- Content is markdown; first line `# {title}` matches the title.
55
-
- Tags: always include `peek:todo` + at least one domain (`peek:desktop`/`peek:mobile`/etc.) + ideally one type (`peek:bug`/`peek:feature`/etc.).
76
+
- Tags: always include `peek:todo` + a quality marker (`peek:ready` or `peek:triage`) + at least one domain (`peek:desktop`/`peek:mobile`/etc.) + ideally one type (`peek:bug`/`peek:feature`/etc.).
77
+
- Quality marker: if you can write a clear "done looks like..." in the content, tag `peek:ready`. If the content is "explore X" or "build Y as example" or a one-phrase musing, tag `peek:triage`.
56
78
- Don't write to `docs/tasks.md`. Don't echo the new task back unless asked.
57
79
58
80
## List tasks
59
81
60
82
```js
61
-
// All open work in this project
83
+
// Actionable queue (default — what you usually want)
84
+
mcp__peek__list_items({ tags: ['peek:todo', 'peek:ready'] })
85
+
86
+
// Items needing scoping conversation
87
+
mcp__peek__list_items({ tags: ['peek:todo', 'peek:triage'] })
88
+
89
+
// Everything still open (ready + triage)
62
90
mcp__peek__list_items({ tags: ['peek:todo'] })
63
91
64
-
// Scoped views
65
-
mcp__peek__list_items({ tags: ['peek:todo', 'peek:desktop'] })
66
-
mcp__peek__list_items({ tags: ['peek:todo', 'peek:mobile'] })
67
-
mcp__peek__list_items({ tags: ['peek:todo', 'peek:bug'] })
92
+
// Scoped to a domain
93
+
mcp__peek__list_items({ tags: ['peek:todo', 'peek:ready', 'peek:desktop'] })
94
+
mcp__peek__list_items({ tags: ['peek:todo', 'peek:ready', 'peek:bug'] })
68
95
69
96
// In progress / blocked
70
97
mcp__peek__list_items({ tags: ['peek:wip'] })
71
98
mcp__peek__list_items({ tags: ['peek:blocked'] })
72
99
100
+
// Closed without shipping (audit trail)
101
+
mcp__peek__list_items({ tags: ['peek:wontfix'] })
102
+
73
103
// Pagination
74
104
mcp__peek__list_items({ tags: ['peek:todo'], limit: 50, offset: 0 })
75
105
```
76
106
77
107
`list_items` returns ALL items matching the tag intersection. The
78
-
queue is large (267+ `peek:todo` items as of 2026-04-29) — paginate
79
-
or narrow by domain/type tag rather than dumping everything.
108
+
queue is large (~258 `peek:todo` items as of 2026-04-29, of which
109
+
~53 are `peek:ready` and ~203 are `peek:triage`) — default to the
110
+
`peek:ready` view, paginate, or narrow by domain when broader.
80
111
81
112
## Status transitions
82
113
···
86
117
87
118
| State change | Tools |
88
119
|----------------------|------------------------------------------------------------------------------------------------|
89
-
| **todo → wip** | `untag_item(peek:todo)` + `tag_item(peek:wip)` + `record_event('started')` |
120
+
| **triage → ready** | `untag_item(peek:triage)` + `tag_item(peek:ready)` + `record_event('triaged', scope)` |
121
+
| **todo → wip** | `untag_item(peek:todo)` + `untag_item(peek:ready)` + `tag_item(peek:wip)` + `record_event('started')` |
90
122
| **wip → blocked** | `untag_item(peek:wip)` + `tag_item(peek:blocked)` + `record_event('blocked', why)` |
91
123
| **blocked → wip** | `untag_item(peek:blocked)` + `tag_item(peek:wip)` + `record_event('unblocked')` |
92
124
| **wip → done** | `untag_item(peek:wip)` + `tag_item(peek:done)` + `record_event('completed', notes)` |
93
-
| **todo → done** | `untag_item(peek:todo)` + `tag_item(peek:done)` + `record_event('completed', notes)` |
94
-
| **done → todo (revive)** | `untag_item(peek:done)` + `tag_item(peek:todo)` + `record_event('reopened', why)` |
95
-
| **defer** | `untag_item(peek:todo)` + `tag_item(peek:deferred)` + `record_event('deferred', why)` |
125
+
| **todo → done** | `untag_item(peek:todo)` + `untag_item(peek:ready/triage)` + `tag_item(peek:done)` + `record_event('completed', notes)` |
126
+
| **done → todo (revive)** | `untag_item(peek:done)` + `tag_item(peek:todo)` + `tag_item(peek:triage)` + `record_event('reopened', why)` |
127
+
| **close as wontfix** | `untag_item(peek:todo)` + `untag_item(peek:ready/triage)` + `tag_item(peek:wontfix)` + `record_event('wontfix', why)` |
96
128
97
129
Always do the untag and the tag in a pair — don't leave an item with
98
-
`peek:todo` AND `peek:done` set, or `peek:wip` AND `peek:blocked`.
130
+
`peek:todo` AND `peek:done` set, `peek:wip` AND `peek:blocked`, or
131
+
`peek:ready` AND `peek:triage`. When transitioning out of `peek:todo`,
132
+
also clear the `peek:ready`/`peek:triage` quality marker.
99
133
100
134
## Edit / update a task
101
135
···
149
183
+ manual tag/event transitions.
150
184
- **Don't add `#todo` or `#peek`** to new items — `peek:todo` already
151
185
encodes both project membership and queue status.
186
+
- **Don't use `peek:deferred`** — retired 2026-04-29. If you'd reach
187
+
for it, the right move is `peek:wontfix` (close the item) or
188
+
`peek:triage` (decision needed).
189
+
- **Don't omit the quality marker** when creating a new `peek:todo`
190
+
item — every active task should be `peek:ready` (scoped) or
191
+
`peek:triage` (needs scoping).
152
192
- **Don't create duplicate tasks.** Before `create_item`, list with
153
193
the relevant domain tag and check by title (substring match).
154
194
- **Don't leave inconsistent tag state** (`peek:wip` + `peek:done`,
···
158
198
159
199
## Quick recipes
160
200
161
-
**"Add a task: rename X to Y, peek desktop bug"**
162
-
→ `create_item({ type: 'text', title: 'Rename X to Y', content: '# Rename X to Y\n\n…', tags: ['peek:todo', 'peek:desktop', 'peek:bug'] })`
201
+
**"Add a task: rename X to Y, peek desktop bug"** (well-scoped)
202
+
→ `create_item({ type: 'text', title: 'Rename X to Y', content: '# Rename X to Y\n\n…', tags: ['peek:todo', 'peek:ready', 'peek:desktop', 'peek:bug'] })`
163
203
164
-
**"What's on my plate for desktop?"**
165
-
→ `list_items({ tags: ['peek:todo', 'peek:desktop'] })` → render as a numbered list of titles only.
204
+
**"Add a half-baked idea: maybe a tag-cluster widget?"** (needs scoping)
205
+
→ `create_item({ type: 'text', title: 'Tag-cluster widget?', content: '…', tags: ['peek:todo', 'peek:triage', 'peek:desktop'] })`
206
+
207
+
**"What's on my plate for desktop?"** (default to actionable)
208
+
→ `list_items({ tags: ['peek:todo', 'peek:ready', 'peek:desktop'] })` → render as a numbered list of titles only.
209
+
210
+
**"What's in the triage queue?"**
211
+
→ `list_items({ tags: ['peek:todo', 'peek:triage'] })`.
166
212
167
213
**"What's in flight?"**
168
214
→ `list_items({ tags: ['peek:wip'] })`.
169
215
170
216
**"Mark #3 done"**
171
-
→ resolve #3 from the prior list output → `untag_item(id, 'peek:todo')` + `tag_item(id, 'peek:done')` + `record_event(id, 'completed', notes)`.
217
+
→ resolve #3 from the prior list output → `untag_item(id, 'peek:todo')` + `untag_item(id, 'peek:ready')` (or `peek:triage`) + `tag_item(id, 'peek:done')` + `record_event(id, 'completed', notes)`.
218
+
219
+
**"Triage this — it's actually ready"**
220
+
→ resolve item → `untag_item(id, 'peek:triage')` + `tag_item(id, 'peek:ready')` + `record_event(id, 'triaged', 'scoped: <one-line plan>')`.
221
+
222
+
**"Close as wontfix — the security gap is theoretical"**
223
+
→ resolve item → `untag_item(id, 'peek:todo')` + `untag_item(id, 'peek:ready')` (or `peek:triage`) + `tag_item(id, 'peek:wontfix')` + `record_event(id, 'wontfix', 'security gap theoretical, indirection cost not justified')`.
172
224
173
225
**"Block the auth refactor — backend isn't ready"**
174
226
→ resolve item → `untag_item(id, 'peek:todo')` (or `peek:wip`) + `tag_item(id, 'peek:blocked')` + `record_event(id, 'blocked', 'backend not ready')`.
175
227
176
228
**"Open the page-host display-switch note"**
177
229
→ resolve via `list_items({ tags: ['peek:todo'] })` → reply: "It's item `<short-title>`. Pop Peek's cmd (Option+Space) and type `edit page-host display`."
178
-
179
-
**"Defer this until after the conversion"**
180
-
→ `untag_item(id, 'peek:todo')` + `tag_item(id, 'peek:deferred')` + `record_event(id, 'deferred', why)`.