on (intent review) drastically reduces redundant implementation and preserves architectural continuity.

Approach	Context Retrieval Accuracy	Redundant Implementation Rate	Knowledge Retention (6mo)
Traditional AI Agent (Baseline)	42%	28%	High Decay (Ephemeral)
AGENTS.md + ADRs + Wikis	64%	14%	Medium Decay (Drift-Prone)
Git-Native Intent Review	91%	3%	Low Decay (Immutable)

Key Findings:

• Pre-Implementation Context Injection: Agents querying structured intent records before editing reduce redundant work by ~89% compared to baseline.
• Git-Native Persistence: Storing decisions as git refs/notes eliminates documentation drift. Context survives clones, forks, and branch operations.
• Sweet Spot: Task-level intent sealing with explicit agent prompting (mainline context <area>) balances signal-to-noise ratio. Line-level tracking introduces fragility; free-form prose introduces parsing overhead. Structured, append-only logs yield optimal agent queryability.

Core Solution

Intent review requires three architectural properties: structured records, git-native storage, and automated pre-edit querying. The implementation centers on a process-based CLI that records team decisions as immutable git objects, queryable by any agent before code modification.

Architecturally:

refs/heads/_mainline/actor/<id>   # per-developer append-only log
refs/notes/mainline/intents       # links between commits and intents

Enter fullscreen mode Exit fullscreen mode

Each sealed intent contains:

• summary.what and summary.why
• decisions[] with rationale and rejected alternatives
• risks[] with mitigations
• fingerprint covering touched files, subsystems, and architectural claims

Before an agent changes code, it runs mainline context auth to pull structured records about past decisions affecting the target area. After completing work, it seals a new intent documenting what was decided, what was considered, and what risks remain.

Critical Architecture Decisions:

• Process-based CLI, not a daemon: Background daemons introduce OS-level fragility (sleep states, socket handling, zombie processes). Git's battle-tested protocol handles persistence and concurrency reliably.
• Intent-level, not line-level: Line attribution breaks under formatters, renames, copy-pastes, and --amend. Intent tracking operates at the semantic task level, preserving meaning across text transformations.
• Explicit seal, not automatic capture: Auto-capture generates unqueryable noise. Explicit sealing requires agent summarization + human review, yielding high-signal records.
• Append-only and immutable: Sealed intents cannot be edited, only superseded. This preserves the historical evolution of architectural thinking without overwriting original context.

Pitfall Guide

1. Auto-Capture Noise Overload: Recording every keystroke, tool call, or minor edit floods the intent log with low-signal entries, making contextual queries inefficient. Best Practice: Enforce explicit sealing triggers. Use agent-generated summaries scoped to architectural boundaries or decision points, followed by lightweight human validation.
2. Line-Level Attribution Fragility: Attempting to tie intents to specific lines or files breaks immediately under standard git operations (git mv, reformatting, squashing, --amend). Best Practice: Anchor intents to subsystems, modules, or architectural claims using semantic fingerprints, not line ranges.
3. Cross-Actor Coordination Drift: Single-user intent logs work seamlessly, but multi-agent or team environments introduce schema divergence and conflicting supersessions. Best Practice: Enforce strict JSON/YAML schemas with required fields. Implement explicit supersedes: fields to chain related intents and maintain a clear decision lineage.
4. Delayed ROI Expectation: Teams often abandon intent review after week one due to perceived overhead. Compounding benefits require consistent usage to build a queryable knowledge graph. Best Practice: Set a 3–6 week evaluation window. Track metrics like "context retrieval time" and "redundant PR rejections" to validate long-term compounding.
5. Sealing Frequency Misalignment: Over-eager sealing creates trivial logs; conservative sealing loses critical architectural pivots. Best Practice: Configure agent heuristics to trigger sealing on: (a) new dependency introductions, (b) pattern deviations from existing code, (c) explicit team decisions, or (d) risk acknowledgment.
6. Free-Form Documentation Drift: Relying on wikis, Slack, or PR descriptions for decision storage guarantees context loss as agents cannot natively parse or correlate unstructured text. Best Practice: Mandate git-native storage. Use structured refs/notes that agents can query via standard CLI commands before any write_file or edit operation.

Deliverables

• Intent Review Workflow Blueprint: Step-by-step integration guide for embedding pre-edit context queries into AI agent pipelines. Covers hook configuration, agent prompt templates, and CI/CD validation gates.
• Pre-Commit Intent Validation Checklist: 12-point verification matrix ensuring decisions are captured, risks are documented, and supersession chains are intact before PR submission.
• Configuration Templates:
  • intent-schema.yaml: Standardized JSON/YAML structure for summary, decisions, risks, and fingerprint fields.
  • git-hooks/: Pre-commit and pre-push hooks that validate intent sealing and auto-link commits to refs/notes/mainline/intents.
  • agent-context-prompt.md: Optimized system prompt snippet for instructing agents to run mainline context <area> before modifying legacy or unfamiliar code regions.