Story: Tooling documentation
Table of Contents
This page documents a story in Sprint 18. It captures the goal, current status, acceptance criteria, and the tasks that compose it.
Goal
The developer tooling — ores.compass, ores.codegen, ores.lisp,
ores.sql, and the standalone scripts in scripts/ — is unreachable from
the architecture pages. There is no "Tooling" layer in
Knowledge, and the component overviews that do exist vary widely in
depth. The ores.compass overview describes architecture but gives no
per-command guidance; ores.sql lists entry points without describing
what any script does; the standalone scripts in scripts/ are
undocumented entirely.
This story makes the tooling reachable and useful:
- A new
* Toolingsection in Knowledge provides a single entry point, with aDeveloper scriptsknowledge doc cataloguing the standalonescripts/scripts and linking out to each tool's component overview. - The ores.compass overview gains one section per command pillar (Locate, Search, Scaffold, Fleet, Goto, Backlog), each with a prose description of purpose and behaviour, and a table of related recipes.
- The ores.sql overview gains a
* Scriptssection with a subsection per script (lifecycle scripts + utility scripts), each with a purpose paragraph and a table of related recipes. - The ores.lisp and ores.codegen overviews are reviewed: gaps filled, wired into the new Tooling section, and confirmed navigable from the architecture pages.
Status
| Field | Value |
|---|---|
| State | DONE |
| Parent sprint | Sprint 18 |
| Now | Nothing. |
| Waiting on | — |
| Next | — |
| Last touched | 2026-05-29 |
Acceptance
- Knowledge has a
* Toolingsection linking to: the developer scripts doc, ores.compass, ores.codegen, ores.lisp, and ores.sql. - A
Developer scriptsknowledge doc exists underdoc/knowledge/architecture/cataloguing every standalone script inscripts/by purpose group, with links toores.sqlandores.compassfor their respective script families. - ores.compass component overview has a section per command pillar, each with a prose paragraph and a recipe table.
- ores.sql component overview has a
* Scriptssection with a subsection per script and a recipe table where applicable. - ores.lisp and ores.codegen overviews are complete and linked from the Tooling section.
- The site builds clean after all changes.
Tasks
| Task | State | Start | End | Description |
|---|---|---|---|---|
| Task: Add Tooling section to knowledge.org and developer scripts doc | DONE | Add * Tooling section to knowledge.org; write Developer scripts knowledge doc cataloguing scripts/ and linking to tool component overviews. | ||
| Task: Overhaul ores.compass component overview | DONE | Extend the component overview with a section per command pillar (Locate, Search, Scaffold, Fleet, Goto, Backlog), each with a prose description and a recipe table. | ||
| Task: Add scripts section to ores.sql component overview | DONE | Add * Scripts section with a subsection per lifecycle and utility script, purpose paragraph, and recipe table where applicable. | ||
| Task: Review and link ores.lisp and ores.codegen overviews | DONE | Review both overviews for gaps, wire into the new Tooling section in knowledge.org, and confirm all tools are navigable from the architecture pages. | ||
| Task: Standardise script naming to snake_case | DONE | Rename parse-test-results.sh and convert-to-unix.sh to snake_case to match all other scripts in scripts/. |
Decisions
- Tooling section in knowledge.org, not a separate index page. A new
* Toolingsection alongside Domain and Architecture is the lightest viable change: no new files, immediate discoverability, consistent with the existing structure. - Developer scripts doc under architecture, not a new top-level
folder. The scripts doc is reference material that fits the existing
doc/knowledge/architecture/pattern. Adoc/tooling/top-level directory would be a larger structural change with no clear benefit at this stage. - Four tasks, not one. Each task targets a different component and can be reviewed and merged independently. The Tooling section task (T1) is a prerequisite for the others only in the sense that it creates the entry point; the component overhaul tasks are otherwise independent.
Out of scope
- Documenting domain-component scripts (e.g. per-service migration scripts) — those belong in their own component overviews.
- Automated script documentation generated from source comments.
- Documenting
build/scripts/(CI/build infrastructure scripts) — a separate story if needed.