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:

  1. A new * Tooling section in Knowledge provides a single entry point, with a Developer scripts knowledge doc cataloguing the standalone scripts/ scripts and linking out to each tool's component overview.
  2. 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.
  3. The ores.sql overview gains a * Scripts section with a subsection per script (lifecycle scripts + utility scripts), each with a purpose paragraph and a table of related recipes.
  4. 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 * Tooling section linking to: the developer scripts doc, ores.compass, ores.codegen, ores.lisp, and ores.sql.
  • A Developer scripts knowledge doc exists under doc/knowledge/architecture/ cataloguing every standalone script in scripts/ by purpose group, with links to ores.sql and ores.compass for 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 * Scripts section 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 * Tooling section 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. A doc/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.

Emacs 29.1 (Org mode 9.6.6)