[OCaml] High Intensity Training Online
docs document request stream workflow
Describe REQUESTS.org as a flat, newest-first stream with tagged headings, and drop the Dispatch and refile steps. Document the closed tag vocabulary (kind, scope, optional impact, doctrine) and the new lifecycle tools: list, log, set-result, check, show, retag, cancel, and block.
.kiro/skills/fracas/SKILL.md
@@ -8,9 +8,14 @@
8
8
Use this skill when the user asks to capture feature requests or to
9
9
track a feature in `REQUESTS.org`.
10
10
11
Added:
`REQUESTS.org` is a flat stream. Each request is a top-level heading.
12
Added:
The newest request comes first. There are no container or topical
13
Added:
headings. Scope, impact, and kind are expressed as tags on each
14
Added:
heading, not by position.
15
Added:
11
16
Keep the session open across prompts. Treat each prompt as a separate
12
Removed:
feature request. Capture each request under `* Dispatch`. Do not merge
13
Removed:
requests. Do not build, test, commit, or start an agent.
17
Added:
feature request. Do not merge requests. Do not build, test, commit, or
18
Added:
start an agent.
14
19
15
20
The current prompt is the feature request:
16
21
@@ -24,7 +29,7 @@
24
29
This skill provides dedicated Emacs Model Context Protocol (MCP)
25
30
tools. Use them for every interaction with `REQUESTS.org`. Do not edit
26
31
the file as raw text. Do not use shell or file tools to capture,
27
Removed:
refile, change status, or verify an entry.
32
Added:
change status, log, or verify an entry.
28
33
29
34
The dedicated tools avoid a security prompt. The generic `eval-elisp`
30
35
tool passes its code through the Emacs security form walker. The
@@ -47,8 +52,8 @@
47
52
(load "/home/blendux/git/hito/.kiro/skills/fracas/fracas-tools.el" nil t)
48
53
```
49
54
50
Removed:
Confirm the tools are present. This expression returns the six FRACAS
51
Removed:
tool names:
55
Added:
Confirm the tools are present. This expression returns the thirteen
56
Added:
FRACAS tool names:
52
57
53
58
```elisp
54
59
(seq-filter (lambda (name) (string-prefix-p "fracas-" name))
@@ -61,50 +66,104 @@
61
66
62
67
### The FRACAS tools
63
68
64
Removed:
- `fracas-inspect` — return the file's TODO keyword sequence and
65
Removed:
whether a `Dispatch` heading exists. Read-only.
66
Removed:
- `fracas-capture` — create a TODO request under `Dispatch`. Records
67
Removed:
the capture time as an inactive `SCHEDULED` timestamp and assigns an
68
Removed:
Org ID.
69
Added:
- `fracas-inspect` — return the file's TODO keyword sequence and the
70
Added:
closed tag vocabulary. Read-only.
71
Added:
- `fracas-list` — list the top-level request entries, newest first,
72
Added:
with each entry's Org ID, title, state, `SCHEDULED` time, and tags.
73
Added:
Takes an optional `state` or `tag` filter. Read-only.
74
Added:
- `fracas-capture` — create a TODO request as a top-level heading at
75
Added:
the top of the stream. Applies tags, records the capture time as an
76
Added:
inactive `SCHEDULED` timestamp, wraps the body to 72 columns, and
77
Added:
assigns an Org ID.
69
78
- `fracas-set-status` — set the TODO keyword of an entry. Rejects
70
79
`DONE`.
71
Removed:
- `fracas-complete` — set an entry to `DONE`. Confirms Org inserted
72
Removed:
the `CLOSED` timestamp. Never writes the timestamp itself.
73
Removed:
- `fracas-refile` — move a completed entry under a top-level heading.
80
Added:
- `fracas-cancel` — set an entry to `CANCELLED` with a required
81
Added:
reason.
82
Added:
- `fracas-block` — set an entry to `BLOCKED` with a required reason.
83
Added:
- `fracas-check` — manage a request's checkbox list to split a complex
84
Added:
task into sub-tasks. Add an item, toggle one, or list them. A `[/]`
85
Added:
cookie tracks progress.
86
Added:
- `fracas-log` — append a timestamped progress note to an entry's
87
Added:
`:LOGBOOK:` drawer. Append-only.
88
Added:
- `fracas-retag` — replace an entry's tags with a validated set from
89
Added:
the closed vocabulary.
90
Added:
- `fracas-set-result` — write the structured `- result ::` line
91
Added:
(commit hash and test recap) for an entry.
92
Added:
- `fracas-complete` — set an entry to `DONE`. Records the result
93
Added:
evidence, then confirms Org inserted the `CLOSED` timestamp. Never
94
Added:
writes the timestamp itself.
95
Added:
- `fracas-show` — return the full content of an entry: heading, state,
96
Added:
tags, timestamps, body, logbook, checklist, and result. Read-only.
74
97
- `fracas-verify` — return the heading, TODO state, `CLOSED`
75
Removed:
timestamp, and outline path of an entry. Read-only.
98
Added:
timestamp, and tags of an entry. Read-only.
76
99
77
Removed:
Use the Emacs MCP `org-*` tools for tasks the FRACAS tools do not
78
Removed:
cover:
100
Added:
Use `fracas-show` to read an entry's full content and `fracas-retag`
101
Added:
to re-tag it. These are the sanctioned tools for those actions,
102
Added:
because the Emacs MCP `org-*` tools cannot operate on this file.
79
103
80
Removed:
- Use `org-get-node` or `org-search` to read headings and content.
81
Removed:
- Use `org-capture` to create the `Dispatch` heading, or a top-level
82
Removed:
section, when it does not exist.
104
Added:
## The tag vocabulary
83
105
84
Removed:
## Step 1 — Capture under Dispatch
106
Added:
Every request carries one kind tag and one scope tag. An impact tag is
107
Added:
optional and marks an exception. Add the `doctrine` flag when the
108
Added:
request touches or deviates from Heavy Duty doctrine. The vocabulary is
109
Added:
closed; `fracas-capture` rejects any other tag. The tags are short and
110
Added:
bare, with no axis prefix. The three axes use distinct words, so a
111
Added:
bare tag stays unambiguous.
85
112
86
Removed:
Run `fracas-inspect` first. Read the TODO keyword sequence. Check
87
Removed:
whether a `Dispatch` heading exists.
113
Added:
Kind — the change type. Choose one:
88
114
89
Removed:
If `Dispatch` does not exist, create it with the Emacs MCP
90
Removed:
`org-capture` tool. Add `* Dispatch` as a top-level heading at the top
91
Removed:
of the file.
115
Added:
- `feat` — a new capability.
116
Added:
- `fix` — a defect repair.
117
Added:
- `refactor` — a change that keeps behaviour.
118
Added:
- `chore` — maintenance or tooling.
119
Added:
- `docs` — documentation only.
92
120
121
Added:
Scope — the layer the change touches. Choose one:
122
Added:
123
Added:
- `core` — pure domain (`hito.core`).
124
Added:
- `app` — service, ports, adapters (`hito.app`).
125
Added:
- `web` — Dream and dream-html (`hito.web`).
126
Added:
- `ui` — visual style, layout, interaction.
127
Added:
128
Added:
Impact — an optional exception flag. Add one only when it applies:
129
Added:
130
Added:
- `trivial` — a trivial change, such as a cosmetic or one-line fix.
131
Added:
- `major` — a potential major rework.
132
Added:
133
Added:
Leave the impact tag off for an ordinary request.
134
Added:
135
Added:
Infer the tags from the request text at capture time. You may re-tag
136
Added:
an entry later, with `fracas-retag`, as the feature shape changes.
137
Added:
138
Added:
## Step 1 — Capture at the top of the stream
139
Added:
140
Added:
Run `fracas-inspect` first. Read the TODO keyword sequence and the tag
141
Added:
vocabulary.
142
Added:
93
143
Run `fracas-capture` with these arguments:
94
144
95
145
- `root` — the project directory.
96
146
- `title` — a short imperative title under 60 characters.
97
147
- `body` — the full request text.
148
Added:
- `tags` — the inferred tags: one kind, one scope, an optional impact
149
Added:
(`trivial` or `major`), plus optional `doctrine`.
98
150
151
Added:
The tool inserts the entry as a top-level heading at the top of the
152
Added:
file, so the newest request is first. It records the capture time as
153
Added:
an inactive `SCHEDULED` timestamp, applies the tags, wraps the body to
154
Added:
72 columns, and returns the new entry's Org ID. Report the Org ID.
155
Added:
99
156
Keep the request text unchanged. If the text holds separate ideas,
100
Removed:
format the body as a list.
157
Added:
format the body as a list. Pass the body as plain text; do not
158
Added:
pre-wrap it.
101
159
102
Removed:
The tool records the capture time as an inactive `SCHEDULED` timestamp
103
Removed:
and returns the new entry's Org ID and outline path. Report the
104
Removed:
outline path.
105
Removed:
106
160
## Step 2 — Track the status
107
161
162
Added:
Find the entry first. Run `fracas-list` to get each entry's Org ID,
163
Added:
title, state, and tags. Pass a `state` or `tag` filter to narrow the
164
Added:
list, for example `IN-PROGRESS`. Use the Org ID for every later call.
165
Added:
Do not match an entry by its title text.
166
Added:
108
167
Read the current status with `fracas-verify` before you change a
109
168
keyword. Use one keyword from the sequence that `fracas-inspect`
110
169
returned.
@@ -115,12 +174,56 @@
115
174
- `IN-PROGRESS` — Start work.
116
175
- `TESTING` — Run tests. The tests do not pass.
117
176
- `TESTED` — Tests pass. No commit exists.
118
Removed:
- `BLOCKED` — Work cannot continue. State the cause of the block.
119
Removed:
- `CANCELLED` — Stop work on purpose.
177
Added:
- `BLOCKED` — Work cannot continue. Use `fracas-block` with a reason.
178
Added:
- `CANCELLED` — Stop work on purpose. Use `fracas-cancel` with a
179
Added:
reason.
120
180
121
181
Change the keyword only after you observe the current status. Run
122
182
`fracas-verify` after the change to confirm the keyword.
123
183
184
Added:
#### Cancel or block with a reason
185
Added:
186
Added:
Record a required reason when you cancel or block a request, so the
187
Added:
decision is never silent. Use `fracas-cancel` for the `CANCELLED`
188
Added:
transition and `fracas-block` for the `BLOCKED` transition. Do not use
189
Added:
`fracas-set-status` for these two transitions. Each tool needs a
190
Added:
`reason` and writes it to the entry.
191
Added:
192
Added:
The file owns the TODO sequence. The `#+TODO:` line in the file
193
Added:
preamble declares it. The tools read that sequence; they never define
194
Added:
their own. To change the keywords, edit the `#+TODO:` line.
195
Added:
196
Added:
### Split a complex task with a checklist
197
Added:
198
Added:
Run `fracas-check` to break one request into sub-tasks that share the
199
Added:
request. Use it when a request is large enough to track in parts, but
200
Added:
not large enough to become its own stream entries.
201
Added:
202
Added:
- `action` `add` — append an unchecked item. Needs `item`.
203
Added:
- `action` `toggle` — flip a matching item done or undone. Needs
204
Added:
`item`.
205
Added:
- `action` `list` — return the items and their state.
206
Added:
207
Added:
The tool keeps the items in a `Checklist [/]:` block in the request
208
Added:
body. The `[/]` cookie tracks completed items against the total. The
209
Added:
items stay inside the one request; they are not separate stream
210
Added:
entries and they have no independent TODO keyword. For genuinely
211
Added:
independent work, capture a new request instead.
212
Added:
213
Added:
### Record progress in the logbook
214
Added:
215
Added:
Run `fracas-log` to add a progress note during an agentic session:
216
Added:
217
Added:
- `root` — the project directory.
218
Added:
- `id` — the Org ID of the entry.
219
Added:
- `note` — the progress note.
220
Added:
221
Added:
The tool appends a timestamped item to the entry's `:LOGBOOK:`
222
Added:
drawer. The logbook is append-only. It never rewrites an earlier note
223
Added:
or the request body.
224
Added:
225
Added:
### Complete with result evidence
226
Added:
124
227
For `DONE`, use `fracas-complete`, not `fracas-set-status`. Set `DONE`
125
228
only when all of these are true:
126
229
@@ -129,29 +232,19 @@
129
232
- The files have the required format.
130
233
- A commit exists.
131
234
132
Removed:
`fracas-complete` sets `DONE`, lets Org's configured logging add the
133
Removed:
`CLOSED` timestamp, and confirms the timestamp. Do not add or edit the
134
Removed:
timestamp yourself. Refile the entry next, under Step 3.
235
Added:
Run `fracas-complete` with these arguments:
135
236
136
Removed:
## Step 3 — Refile on completion
137
Removed:
138
Removed:
Keep the request under `* Dispatch` while its status is open,
139
Removed:
`BLOCKED`, or `CANCELLED`. When its status becomes `DONE`, move the
140
Removed:
entry out of `Dispatch`.
141
Removed:
142
Removed:
Read the top-level headings with `org-search` or
143
Removed:
`org-get-node`. Select the section that best matches the request. If
144
Removed:
no section matches, create a short, consistent top-level section with
145
Removed:
the Emacs MCP `org-capture` tool.
146
Removed:
147
Removed:
Run `fracas-refile` with these arguments:
148
Removed:
149
237
- `root` — the project directory.
150
238
- `id` — the Org ID of the entry.
151
Removed:
- `target` — the top-level heading name.
239
Added:
- `commit` — the commit hash for the completed work.
240
Added:
- `tests` — a short test recap, for example `215 pass`.
152
241
153
Removed:
Run `fracas-verify` to confirm the new location. Report the new
154
Removed:
outline path.
242
Added:
The tool writes a `- result :: commit=… tests=…` line, sets `DONE`,
243
Added:
lets Org's configured logging add the `CLOSED` timestamp, and confirms
244
Added:
the timestamp. Do not add or edit the timestamp yourself. The entry
245
Added:
stays where it is in the stream; there is no refile step. Use
246
Added:
`fracas-set-result` on its own to record the result line before
247
Added:
completion.
155
248
156
249
Record each prompt as its own request. If you cannot complete a
157
250
request, record the request and the failure.