Method

1. Nothing missed by default. A positive-trigger layer in the commit hook overrides [no-log] tags when a commit exceeds 200 LOC, touches sensitive paths, or carries architecture-flavored keywords. Author judgment slips on what is “trivial” about a third of the time; the system catches it.
2. AI-author + human-annotator. Every AI-written log entry has a sibling .human.mdx slot, rendered side-by-side. Empty slots render as “REVIEW NEEDED” — the absence is visible, not silent.
3. Cross-repo aggregation. Five projects (this hub plus four satellite repos) feed one portfolio timeline via pull-on-demand. No sync, no second source of truth.
4. Tiered decision capture. Decisions are recorded with templates scaled to weight (Tier 1 substantial → 8-slot MBA-grade template; Tier 2 notable → 6-slot; Tier 3 trivial → no template). Plus a learning-gap kind for what I didn't initially understand — the growth artifact most systems omit.

Adapted from established frameworks. The point is to use templates that have been load-bearing in real organizations, not to invent new slots.

• Tier 1 — substantial (architecture, vendor, monetization, security, data model, major refactor)

  8 slots: Context & constraints · Goals ranked · Options considered (≥3 incl. “do nothing”) with Cost/Reversibility/Risk/Evidence each · Trade-off accepted · Pre-mortem (3 failure scenarios at 6 months) · Decision criteria to flip · Success measure · Reversal plan.

  Authoring time: 20–30 min when done thoroughly. Target: 3–5 entries per month.

• Tier 2 — notable (feature direction, UX call, dependency upgrade)

  6 slots: Context · Options considered (≥2) · Chosen + Why · Trade-off · Reversibility · Verified by. ~5–10 min.

• Tier 3 — trivial (renames, lint, formatting, dep bumps with no behavior change)

  No decision entry. Just commit.

Three log kinds carry the AI engineer's differentiating signal:

decision

ADR-style record of an option-weighing moment. Tiered. Required fields include reversibility (Bezos two-way / one-way door framing).

discussion

Conversation that surfaced options — with Claude.ai, with a person, brainstorm. Captures what I rejected from AI's default suggestion.

learning-gap

What I didn't initially understand, where the gap came from, what clicked, what's still confused. Paired with wiki entries to track the growth of a mental model over time.

The hook script, install kit, and CLAUDE.md snippet are all open. One-line install bootstraps the dual-write convention plus the positive-trigger hook on any git repo.

The system was built incrementally and documented as it shipped. The post below records the actual sequence — what was tried, what broke, what shipped.

• Michael Nygard, Documenting Architecture Decisions, 2011 — the ADR pattern.
• Jeff Bezos, 1997 shareholder letter — two-way / one-way door framing for reversibility.
• Gary Klein, “Performing a Project Premortem,” Harvard Business Review, 2007.
• Atlassian DACI — decision-roles framework (used in lightweight form for solo work).
• Andy Grove, High Output Management, 1983 — structured information capture as management leverage.
• Salvatore Sanfilippo (antirez) — devlog tradition for high-signal individual engineering writing.
• Obsidian / Logseq — linked atomic notes (the [[wiki-link]] syntax is adapted from these).

• Not a CMS. Logs are MDX files; the rendering layer just reads them.
• Not a sync system. The hub pulls satellite logs on demand; no second source of truth.
• Not bureaucracy. Tier 3 is “just commit, no entry” — most commits stay there.
• Not a substitute for code review. It records reasoning; it doesn't evaluate it.