bots-garden/mini-me · 2026-09-15-diataxis-docs.md

⑂ main

2026-09-15-diataxis-docs.md · 50 lines · 4.1 KBmarkdown    Blame HistoryRaw
   1# Handoff — 2026-09-15 — Diátaxis documentation bootstrap (agent "riker")
3## Where it stopped
5`docs/` exists with a complete bilingual four-quadrant structure (`docs/en/`, `docs/fr/`, identical file names). Every page is "complete, not finished": usable now, open to growth. All relative links resolve (checked with a shell loop over `](…)` targets). Nothing committed — the whole repository is untracked apart from two old commits.
7## Filing plan that was applied (compass)
9| Topic | Quadrant | File (both languages) |
10|-------|----------|-----------------------|
11| First session with DMR | Tutorial | `tutorials/getting-started.md` |
12| Run on llama.cpp | How-to | `how-to/run-with-llama-cpp.md` |
13| Host in an editor (ACP/Zed) | How-to | `how-to/use-from-an-editor.md` |
14| Add a skill | How-to | `how-to/add-a-skill.md` |
15| Long session inside the window | How-to | `how-to/manage-the-context-window.md` |
16| Start a new session (`/new`) | How-to | `how-to/start-a-new-session.md` — written by the other agent (bob) |
17| CLI flags, env vars, banner, exit codes | Reference | `reference/cli.md` |
18| Slash commands and keys | Reference | `reference/slash-commands.md` — bob edited the `/new` row after me |
19| YAML keys, defaults, validation errors | Reference | `reference/configuration.md` |
20| Built-in tools | Reference | `reference/tools.md` |
21| Skill file format | Reference | `reference/skill-format.md` |
22| ACP surface | Reference | `reference/acp.md` |
23| One loop, two front ends | Explanation | `explanation/architecture.md` |
24| Providers | Explanation | `explanation/providers.md` |
25| Context compression | Explanation | `explanation/context-compression.md` |
27The skill's mandatory language question was not asked (user unavailable); "Both" was taken from the methodical-dev convention. If the user wants a single language, delete the other tree and the selector in `docs/README.md`.
29## Traps found (documented, not fixed — no Go changes were in my scope)
311. **Shipped skills are invisible.** `skills.List` globs `<skillsDir>/*.md`; the examples are `skills/<name>/SKILL.md`. Banner shows `skills: 0`, `read_skill` is never declared. Either flatten the files or teach the loader to read `*/SKILL.md`. The docs describe the current behaviour and tell the user to flatten.
322. **`go test ./...` fails** in `mm/internal/skills`: `TestShippedSkillsHaveDescriptions` hard-codes `../../../demo/skills`, a path from the project this code was extracted from. Fix the path (and the layout above) or the quality gate will never be green.
333. The tutorial's banner line was captured verbatim from a real run; it now includes `"/new" to start a new session.` because bob changed `agent.go`. If the banner text changes again, update both tutorials.
344. `agent.yaml` calls the agent "Bob", ACP `agentInfo.name` is `bob` / version `0.11.0`, the binary is `mm`. The docs use `mm` for the binary and quote the ACP values as-is.
36## Not verified
38- No model server in the sandbox: step 3 of the tutorial (a real generation) was written from the code paths, not observed. The banner and `-h` output were observed.
39- `docs/diagrams/packages.drawio` was created by bob; I linked it from both indexes and both architecture pages without validating its content.
41## Suggested next increments
43- A how-to for `editTools: false` (bash-only A/B mode) once someone has actually run it.
44- A reference page for the engine's runtime messages (`[watchdog: …]`, `Retrying without streaming`) — currently only mentioned in passing.
45- Explanation of the loop detector once its thresholds (history 10, threshold 3, set in `main.go`) are considered stable.
46- bob updated `reference/slash-commands.md` and `reference/acp.md` in both languages for `/new` (row, ACP section, `available_commands_update`) after I wrote them; at the end of my session they were consistent with the code. Re-check only if `/new` changes again.
48## Addendum (same day, orchestrator)
50The Zed snippet in `how-to/use-from-an-editor.md` (EN + FR) was missing `"type": "custom"`; the user confirmed Zed needs it. Fixed in both pages. Any future editor how-to must include that key.

💾 Saved. d722711 k33g 4h ago	1	# Handoff — 2026-09-15 — Diátaxis documentation bootstrap (agent "riker")
	2
	3	## Where it stopped
	4
	5	`docs/` exists with a complete bilingual four-quadrant structure (`docs/en/`, `docs/fr/`, identical file names). Every page is "complete, not finished": usable now, open to growth. All relative links resolve (checked with a shell loop over `](…)` targets). Nothing committed — the whole repository is untracked apart from two old commits.
	6
	7	## Filing plan that was applied (compass)
	8
	9	\| Topic \| Quadrant \| File (both languages) \|
	10	\|-------\|----------\|-----------------------\|
	11	\| First session with DMR \| Tutorial \| `tutorials/getting-started.md` \|
	12	\| Run on llama.cpp \| How-to \| `how-to/run-with-llama-cpp.md` \|
	13	\| Host in an editor (ACP/Zed) \| How-to \| `how-to/use-from-an-editor.md` \|
	14	\| Add a skill \| How-to \| `how-to/add-a-skill.md` \|
	15	\| Long session inside the window \| How-to \| `how-to/manage-the-context-window.md` \|
	16	\| Start a new session (`/new`) \| How-to \| `how-to/start-a-new-session.md` — written by the other agent (bob) \|
	17	\| CLI flags, env vars, banner, exit codes \| Reference \| `reference/cli.md` \|
	18	\| Slash commands and keys \| Reference \| `reference/slash-commands.md` — bob edited the `/new` row after me \|
	19	\| YAML keys, defaults, validation errors \| Reference \| `reference/configuration.md` \|
	20	\| Built-in tools \| Reference \| `reference/tools.md` \|
	21	\| Skill file format \| Reference \| `reference/skill-format.md` \|
	22	\| ACP surface \| Reference \| `reference/acp.md` \|
	23	\| One loop, two front ends \| Explanation \| `explanation/architecture.md` \|
	24	\| Providers \| Explanation \| `explanation/providers.md` \|
	25	\| Context compression \| Explanation \| `explanation/context-compression.md` \|
	26
	27	The skill's mandatory language question was not asked (user unavailable); "Both" was taken from the methodical-dev convention. If the user wants a single language, delete the other tree and the selector in `docs/README.md`.
	28
	29	## Traps found (documented, not fixed — no Go changes were in my scope)
	30
	31	1. Shipped skills are invisible. `skills.List` globs `<skillsDir>/.md`; the examples are `skills/<name>/SKILL.md`. Banner shows `skills: 0`, `read_skill` is never declared. Either flatten the files or teach the loader to read `/SKILL.md`. The docs describe the current behaviour and tell the user to flatten.
	32	2. `go test ./...` fails in `mm/internal/skills`: `TestShippedSkillsHaveDescriptions` hard-codes `../../../demo/skills`, a path from the project this code was extracted from. Fix the path (and the layout above) or the quality gate will never be green.
	33	3. The tutorial's banner line was captured verbatim from a real run; it now includes `"/new" to start a new session.` because bob changed `agent.go`. If the banner text changes again, update both tutorials.
	34	4. `agent.yaml` calls the agent "Bob", ACP `agentInfo.name` is `bob` / version `0.11.0`, the binary is `mm`. The docs use `mm` for the binary and quote the ACP values as-is.
	35
	36	## Not verified
	37
	38	- No model server in the sandbox: step 3 of the tutorial (a real generation) was written from the code paths, not observed. The banner and `-h` output were observed.
	39	- `docs/diagrams/packages.drawio` was created by bob; I linked it from both indexes and both architecture pages without validating its content.
	40
	41	## Suggested next increments
	42
	43	- A how-to for `editTools: false` (bash-only A/B mode) once someone has actually run it.
	44	- A reference page for the engine's runtime messages (`[watchdog: …]`, `Retrying without streaming`) — currently only mentioned in passing.
	45	- Explanation of the loop detector once its thresholds (history 10, threshold 3, set in `main.go`) are considered stable.
	46	- bob updated `reference/slash-commands.md` and `reference/acp.md` in both languages for `/new` (row, ACP section, `available_commands_update`) after I wrote them; at the end of my session they were consistent with the code. Re-check only if `/new` changes again.
	47
	48	## Addendum (same day, orchestrator)
	49
	50	The Zed snippet in `how-to/use-from-an-editor.md` (EN + FR) was missing `"type": "custom"`; the user confirmed Zed needs it. Fixed in both pages. Any future editor how-to must include that key.