build-log

Maintain {{build_log_dir}} as a write-once series of numbered entries (NN_kebab_topic.md) recording phase completions and gate results with their numerical evidence. The build log is the raw "methods" material for the eventual paper and the project's replay memory after long gaps — every entry must be worth citing in one of those two roles.

When to use

The threshold is deliberately high. Open an entry only for:

• Phase completion — all of a phase's modules and tests green, gate passed.
• Fixing a gate result — a correctness-gate tolerance update, a first successful end-to-end run of new machinery, a first result curve.
• Documenting a decision's implementation — the decision itself goes in {{decision_log}}; the build-log entry carries its execution and numerical proof (comparison tables, figures, before/after numbers).

The practical test: would the paper's methods section, or a future you reconstructing the project, cite this entry? If no — do not open one.

When NOT to use

• A single module was added → git log + the module's docstring suffice.
• A decision was just written → wait; open the entry when its first implementation + evidence exist.
• Transient exploratory probe → notebook (project-layout).
• Refactor / cleanup / docstring pass → the commit message is the record.
• Anything git already records well (commit messages, PR descriptions).

Numbering and filename

Find the last number: ls {{build_log_dir}} | grep -E '^[0-9]{2}_' | sort | tail -1. New entry = next number, NN_kebab_topic.md, topic short: module or main deliverable (e.g. 09_baseline_comparison.md).

Required structure (in order)

# <Module or milestone title>

**Date**: YYYY-MM-DD
**Phase**: <N> (short scope)
**Status**: ✅ / 🟡 + one-sentence summary
**Test total**: N passed, M skipped   (from real test-runner output, if applicable)

## Related artifacts

- [path](relative/path) — one-sentence description (evidence dirs, notebooks, decision entries)

## Why this exists            <!-- or: Final configuration / Decision rationale -->

Why it was built or measured, which alternative lost, which reference it rests on.

## What was implemented

| File | Public API | Responsibility |
| --- | --- | --- |
| [`path`](relative/path) | `fn(args) -> ret` | one sentence |

## Tests / evidence

- `tests/test_x.py` — N tests, what they pin down.
- Numerical results as tables (sweep tables, before/after), not prose.

## References

- Spec section, predecessor entry, decision numbers, external sources actually used.

Rules

1. Write-once. Entries are immutable evidence; corrections and follow-ups are a new entry that references the old one. The single allowed retro-edit: marking the previous entry's "next step" pointer as done.
2. Numbers, not adjectives. Never "works" / "ready" — write the test count, the gate output, the measured value. A claim without a number or an artifact link is filler.
3. Tables over paragraphs — mandatory for implemented-module inventories and numerical results.
4. Relative, clickable links to every artifact named — paths a reader can follow from the file's location.
5. The why-section carries the rationale — not "added X" but "X solved <problem> because <reason>, over <alternative>".
6. Status markers: ✅ completed, 🟡 in progress, ⬜ not started (optionally ⚠ at-risk, ❌ blocked). Do not invent alternatives.
7. Entries link their evidence in {{evidence_dir}} — an entry claiming a run that has no evidence directory is treating "it ran fine" as evidence, which the evidence-convention skill forbids.

Configuration

• {{build_log_dir}} — the entry directory (default docs/build_log/).
• {{decision_log}}, {{evidence_dir}} — for cross-links.

Provenance & maintenance

Generalized from a 20+-entry build log in a working computational-research repository (high-bar entry criteria, header block, artifact list, why-section, implementation table, write-once discipline); see the pack's examples/ directory for the worked exemplar mapping. The structure block mirrors the exemplar's entry template with domain content removed; the "would the paper cite it" test is verbatim exemplar practice.

Re-verify in your project:

• ls {{build_log_dir}} | grep -E '^[0-9]{2}_' | sort | tail -3 — numbering is contiguous and kebab-cased.
• grep -L '## References' {{build_log_dir}}/*.md — entries missing a references section (should print nothing).
• git log --follow --oneline -- {{build_log_dir}}/<oldest entry> — old entries should show no post-creation substantive edits (write-once check).