task-logbook

Task logbook

Concepts

Keep the detailed append-only record in the logbook. If a coordinating issue exists, publish significant updates as comments and maintain its body as the current summary.

Location and Naming

• Store logbooks under .agents/logbooks/<topic>.md.
• Use a short, stable topic slug. Including the GitHub issue number is often a good choice.
• Link to the coordinating GitHub issue or PR near the top of the logbook when one exists.

Logbook

New logbooks are Markdown files with YAML frontmatter.

Logbook Template

---
topic:
issue:
description:
author:
---

# <Topic>: Task Logbook

## Scope
- Goal:
- Primary metric(s):
- Constraints:
- Coordinating issue/PR:

## Baseline
- Date:
- Code refs:
- Baseline numbers:

## Entry Log
### YYYY-MM-DD HH:MM - <short label>
- Hypothesis:
- Commit Hash:
- Command:
- Config:
- Result:
- Interpretation:
- Next action:

When code changes affect reproducibility, make a lightweight WIP commit and record its hash. Stage only the files needed for the result. Apply the full commit workflow when promoting the work to a production PR.

For a research series, use one short experiment ID consistently in logbook entries, W&B runs, and issue comments.

Use the requesting user as author. Omit issue when none exists.

Write Rules

• Append entries; do not rewrite history except to fix formatting or broken links or to add a coordinating issue reference.
• Each non-trivial result needs exact commands, hash, config, key output, and the decision it caused.
• Record failures and negative results with enough detail to avoid rediscovery.
• Prefer terse tables for comparable numeric results.
• Link large artifacts, W&B runs, dashboards, pinned GitHub paths, etc., instead of pasting dense output.
• Keep claims scoped and falsifiable.
• Label major claims when useful:
  • exploratory: single run or weak evidence.
  • replicated: repeated and consistent.
  • stable: held across relevant shape, seed, hardware, or workflow variants.