FG-0701 Structured History System
Description
Maintain a structured, versioned record of project history including plans, decisions, and health metrics. The history system serves as the institutional memory of the collaboration. It records what happened and why: the decisions made, the alternatives considered, and the lessons learned. When context is lost (as it inevitably is in AI collaboration), the history system provides recovery.
Implementation
Create a structured project history system with clear organization. Include mechanisms for quick scanning of current state, tracking of active and completed work, and archival of deferred plans. Ensure entries are structured for fast retrieval. Update at session end and use as a primary input during context recovery.
Success Indicators
- The history system accurately reflects current project state
- Context recovery starts with history review
- Decision rationale is preserved and accessible
- The history system is updated consistently, not sporadically
Failure Modes
- History not updated: becomes stale and untrustworthy
- History too detailed: quick scanning is impossible
- History maintained by one person: single point of failure
- History disconnected from actual work: a separate document nobody reads
Sub-Methods 3
Every history document gets machine-readable frontmatter with standardized fields: plan name, status, owner, key decision, and date. This enables fast scanning: agents can read frontmatter (under 50 tokens) to determine relevance before committing to reading the full document (500+ tokens). Frontmatter is the index layer of the history system.
Track every plan through explicit lifecycle states: active, complete, deferred, archived. State transitions are documented with timestamps and rationale. The lifecycle ensures nothing is silently abandoned: deferred plans have documented reasons, completed plans have summaries, and archived plans remain accessible.
Maintain bidirectional references between the history system and the actual work (code commits, deployed artifacts, published content). If the history says a plan is complete, the corresponding artifacts should exist. If artifacts exist without history entries, the history has gaps. Regular cross-reference audits catch drift.