Decision Record

A record of each of the important decisions that were made in the process of designing and implementing this project.

Decisions should be listed in a table with each decision taking up one row. The table structure is:

brief summary: preferably three or less sentences describing the decision.
reasoning: preferably three or less sentences providing the reason ‘why’ the decision was made. What is the driving cause behind the decision e.g. cost, benefits, disadvantages, speed, timing, labour, insufficient skills?

The table should be provided in markdown table format. Each new decision should be appended to the end of the table.

Decision Table

Brief Summary	Reasoning
Record all decisions.	Gives insights into the development process.
Card ids are the kind prefix and the slug. Serial numbers were removed from the Kanban system.	A serial number had to be reassigned every time the cards were reordered, and numbers collided between kinds. The documentation shortcodes select cards by filename pattern, so the prefix and slug already identify a card uniquely across all stages.
A card’s status is the stage folder that contains it; there is no `status` field.	Moving a file between stages with `git mv` is the status change, and the file’s version history is the history of the board. A front matter field could disagree with the file’s location, which would leave two sources of truth.
Priority and kind are components of the card filename, and the kind is confirmed by the archetype the card was created from.	Fourteen kinds stored in three stages would need forty-two folders, so folders cannot carry the kind. Stage is the one fact the folder does carry, and the shortcodes match filenames.
New cards are always created in `01-to-do`.	All new work starts there, so the tool needs no stage parameter and cannot put a card in the wrong place.
The theme is a git submodule published on its own `features` branch, and the parent repository records the submodule pointer.	The theme is used by more than one project, so it needs its own history and remote. Recording the pointer in the parent pins the site to the exact theme build it was published with.
HTML validity is checked by `html-validate` with the `html-validate:standard` preset.	The recommended preset reported 45,732 problems, almost all stylistic preferences such as trailing slashes on void elements, which are valid in HTML5. That volume buries real defects, so the preset was narrowed to conformance with the standard, which reported 32 problems that were all fixed.
The HTML validation runs after the build and before the Pages artifact is uploaded.	Markup that fails validation must not be published. A failure stops the deployment and leaves the previously published site live.
Hugo’s pagination redirect stubs and the pages under `dashboard/raw` are excluded from validation.	Hugo writes the pagination stubs with a `head` and no `body`, so nothing in the theme can change them. The raw pages exist to present odd markup to the stylesheet, and correcting them would destroy the test they provide.
Dashboard section pages list links to the scratch pages instead of embedding them.	Embedding a whole page in a card nested `main`, `nav` and `footer` landmarks inside the listing page, which is invalid and duplicated the landmarks. A list of links gives the reader the same information.
Card partials show `.Description`, falling back to a plainified `.Summary`.	Hugo provides no summary fallback for `Description`, so cards without one embedded their body, and the headings in that body repeated their ids across a single listing page. Plainifying the fallback removes the ids.
Markdown render hooks must not trim the whitespace in front of an attribute.	Trimming glued an attribute to its tag name, producing `<atitle="...">`, `<thclass="...">` and `<tdclass="...">`. The reports all came from two hooks, so the rule is stated where the hooks are written.
Generated CSS and Hugo build output are not versioned.	`assets/css/main.css`, `hugo_stats.json`, `assets/jsconfig.json`, `public/`, `resources/` and `.hugo_build.lock` are all reproducible from the theme source, the config and the scripts. Committing them doubles the size of every change and invites stale output being published.
Only the `posts` branch publishes.	Work in progress can then be pushed without deploying, and there is one deployment path to reason about.
The Hugo cache in the publish workflow is keyed on the Hugo version, the pinned theme commit and a hash of the site configuration.	A warm cache shortens the build, so the key has to change exactly when a build input changes: the toolchain, the theme, or the configuration.
Prose is formatted by Prettier at a print width of 80 with `proseWrap` set to `always`, running on staged files.	One formatter for every text format removes formatting arguments from review, and fixed wrapping keeps content diffs small and readable.
Media is versioned with Git LFS, tracked extension by extension.	The repository stays small and cloneable, and a new image format is added to the tracking rules at the moment it is first used.
`cmd/kan` is a Go program in the repository, run with `go run` and covered by `go test`.	A scaffolder needs the Hugo archetype rules, which are in the repository, and Go is already required by the theme’s tooling. Installing a compiled binary on a machine is a separate action that requires the owner’s approval.
Documentation and task tracking live in the content tree, and documents generate their tables from the cards.	Documents that are retyped from the data go stale. Reading the cards at build time keeps the documentation and the board in agreement, and puts both under the same review as the code.