learn

/learn

Delegate to learning-curator.

Triggers (any one makes the task "notable")

• Investigation took > 30 min

• 2 fix attempts before success

• Surprised by behaviour
• Found a non-obvious gotcha
• Made a non-trivial trade-off
• Bootstrapped something new (test framework, CI, infrastructure)

Process

1. Read the last commit + PR description + investigation file (if exists).

2. Extract:

   • What we expected
   • What actually happened
   • Why
   • What we'd do differently

3. Tag with relevant types.

4. Resolve the canonical learnings path. docs/learnings/ is gitignored (forge-dogfood publish-hygiene rule), so its single source of truth is the main checkout's docs/learnings/ tree — not the working directory. /pickup-task hydrates worktrees by cp -r from the main checkout (skills/pickup-task/SKILL.md lines 47–53), and /learn must mirror that contract on the write side. See spec/SPEC.md §Learnings store for the canonical-store rule and why.

   Resolve the main checkout's absolute path via git rev-parse --git-common-dir (which always resolves to the main checkout's .git from anywhere — main or worktree). Compare against pwd -P so symlinked paths (e.g. macOS /var ↔ /private/var) don't trigger a spurious double-write:

   GIT_COMMON_DIR="$(git rev-parse --git-common-dir)"
   MAIN_ROOT="$(cd "$(dirname "${GIT_COMMON_DIR}")" && pwd -P)"
   PWD_REAL="$(pwd -P)"
   QUARTER="2026-Q2"   # or current quarter, e.g. "$(date -u +%Y)-Q$((($(date -u +%m)-1)/3+1))"
   SLUG="kebab-case-slug-from-title"
   mkdir -p "${MAIN_ROOT}/docs/learnings/${QUARTER}"
   

5. Refuse on collision. If ${MAIN_ROOT}/docs/learnings/${QUARTER}/${SLUG}.md already exists, stop and surface the conflict — pick a different slug, or Edit the existing learning instead of writing a new one. Do not silently overwrite a prior learning.

6. Write the canonical record first to the main checkout's absolute path using the Write tool. This is the load-bearing write; do not skip it even on errors elsewhere: