# Hybrid Synthesis: Task File Logging vs. Git-as-Log

Generated: 2026-02-17

## Thesis

The real question is not where to log but what to log where. Git already captures the what and when of every code change with 97% traceability; the task file should capture only what git structurally cannot -- decisions with rationale and rejected alternatives -- while metrics should be derived mechanically from git at episodic generation time, never hand-written by agents.

## The Incorrect Framing

Both Position A (richer task-file logging) and Position B (accept git as the log) treat "the log" as a monolithic thing that belongs in one place. The audit data reveals why both fail in isolation:

- Position A fails because agents do not actually do it. 58% of task files have two or fewer Updates entries (created + completed). This is not a discipline problem. It is a budget problem. Every Write call costs context tokens, and context is the scarcest resource in the system. Enforcing richer Updates via a hard gate would mean agents spend 5-10% of their context budget on bookkeeping rather than building. At scale with autonomous agents, this degrades throughput with no proportional gain in learning quality.

- Position B fails because git commits are semantically flat. A commit message says "T-092: Add Tier 0 enforcement hook" but does not say why blocking-with-approval was chosen over warning-only, or why only catastrophic rm targets are flagged instead of all rm -rf. The rationale, the rejected alternatives, the design tradeoffs -- these are invisible in git. And these are precisely what episodic memory needs to enable future agents to avoid re-litigating settled decisions.

## The Synthesis: Separation of Concerns by Information Type

Three types of information are generated during task execution. Each has a natural home:

**1. Code changes and timeline: Git (already working)**
What files changed, when, in what order, how many lines. Git captures this with mechanical precision and 97% traceability. The episodic generator already mines git for commit counts, lines added/removed, and files changed. This should remain the sole source of truth for metrics. The 16% episodic inaccuracy on commit counts is a generator bug (race conditions between skeleton generation and enrichment), not an argument for duplicating metrics in the task file.

**2. Decisions and rationale: Task file (upgrade from Updates to Decisions section)**
The task file should carry a lightweight Decisions section, not a chronological Updates log. The difference matters. A decision entry is: what was decided, why, what alternatives were rejected. This is the one thing git cannot capture -- the design space that was explored and narrowed. T-097 demonstrates this perfectly: its task file records the MODIFIED GO decision with full rationale and three rejected alternatives. Its git commits say only "T-097: Deep reflection." Without the task file, the reasoning is lost forever.

The key move: replace the Updates section's role as a "log everything" receptacle with a focused Decisions record. Updates remain for status transitions (auto-generated by the task-update agent, zero cost). Decisions are written only when a non-obvious choice is made -- perhaps 1-3 per task, costing under 1% of context budget.

**3. Synthesized learning: Episodic memory (dual-source generation)**
The episodic generator should pull from both sources. From git: timeline, metrics, files changed, commit messages. From the task file: decisions with rationale, acceptance criteria outcomes, and the task description for context. The generator already does the git mining (lines 83-97 of episodic.sh). The improvement is to also parse a structured Decisions section rather than trying to grep for challenge keywords in free-text Updates.

## Enforcement Gradient

This synthesis calls for a soft enforcement model, not hard gates:

- **Automated (zero cost):** Status transitions in Updates are already auto-generated by the task-update agent. Git metrics are already auto-mined at episodic generation. No agent effort required.
- **Prompted (near-zero cost):** At task completion time, the update-task agent prompts: "Were any non-obvious decisions made? Record them before closing." This is a reminder, not a gate. If the agent has nothing to record, it skips. If it does, it writes a structured decision entry.
- **Audited (post-hoc):** The audit agent can flag completed tasks with zero Decisions entries when the git history shows 3+ commits or touches 5+ files. This catches tasks that were complex enough to likely involve decisions but recorded none. It does not block; it flags for enrichment.

No hard gate blocks task completion for missing Updates. The 58% thin-file rate proves hard enforcement would create make-work, not learning.

## What This Means for the Template

The default task template changes from:

```markdown
## Updates
[Chronological log -- every action, every output, every decision]
```

To:

```markdown
## Decisions
[Non-obvious choices made during this task. Format:
- **Decision:** What was chosen
- **Rationale:** Why
- **Alternatives rejected:** What else was considered]

## Updates
[Auto-generated status transitions -- do not manually edit]
```

This is a smaller surface area with higher signal density. Agents write less, episodic memory gets more.

## Scale Analysis

At 1000 tasks with multiple autonomous agents:

- **Git-as-metrics scales perfectly.** It is already the bottleneck-free path. Mining git log for a task ID is O(commits), which stays fast with conventional repo sizes.
- **Decisions-in-task-file scales well.** Most tasks have 0-3 decisions. The write cost is bounded and proportional to actual complexity, not prescribed by template.
- **Chronological Updates do not scale.** They require agent discipline that demonstrably erodes, create context budget pressure that compounds, and produce low-signal-density text that the episodic generator struggles to parse.

## Constitutional Alignment

- **Antifragility:** Decisions with rejected alternatives are the highest-value learning artifacts. They tell future agents not just what worked, but what was considered and dismissed. This is the raw material for pattern recognition across tasks.
- **Reliability:** Git provides the auditable mechanical record. Decisions provide the auditable reasoning record. Together they cover the full audit surface without redundancy.
- **Usability:** Agents write less (1% context cost vs. 5%+). The template is smaller. The prompt at completion is optional. The hard gate is gone. This is measurably more pleasant to use.
- **Portability:** Both git and markdown task files are provider-neutral. No lock-in to any agent platform, LLM provider, or tooling ecosystem.

## Recommendation

Adopt the three-layer separation: git owns metrics and timeline, task files own decisions and rationale, episodic generation merges both sources mechanically. Remove the expectation that Updates is a chronological work log. Retain it only as an auto-populated status-transition record. Add a Decisions section with a prompted (not gated) workflow. Fix the episodic generator's commit-count accuracy bug separately -- it is a mechanical defect, not an architectural one.
