Triple-C/container/mission-control/docs/flight-logs.md

Flight Logs

Flight logs are living records created during flight execution. They capture what actually happened—when legs started and ended, what changed, decisions made mid-flight, and any deviations or anomalies encountered.

What is a Flight Log?

A flight log is the authoritative record of a flight's execution. While the flight document describes the plan, the flight log documents reality. There is exactly one flight log per flight, updated continuously during execution.

Important: Flight logs are append-only during execution. Never delete or modify existing entries—only add new ones. This preserves the historical record and ensures nothing is lost when revisiting decisions later.

Flight Log vs. Other Artifacts

Artifact	Purpose	When Written	Updates
Flight	Plan what to do	Before execution	During planning only
Flight Log	Record what happened	During execution	Continuously
Leg	Instructions for one task	Before execution	Never (immutable)

Why Flight Logs Matter

For Current Execution

Flight logs provide:

• Continuity: When work resumes after interruption, the log shows where things stand
• Decision history: Why choices were made when the plan didn't fit reality
• Anomaly tracking: Issues that didn't block progress but need future attention

For Future Legs

When creating new legs, the flight log reveals:

• What actually worked vs. what was planned
• Decisions that affect subsequent implementation
• Discovered complexity that should inform estimates
• Patterns or anti-patterns emerging from execution

For Post-Flight Debrief

The flight log enables meaningful retrospectives by capturing:

• Actual vs. planned progression
• Root causes of deviations
• Learnings that should inform future flights

Flight Log Structure

# Flight Log: {Flight Title}

## Flight Reference
[{Flight Title}](flight.md)

## Summary
Brief overview of the flight's execution status and key outcomes.

---

## Leg Progress

### {Leg Name}
**Status**: completed | landed | in-flight | aborted
**Started**: {timestamp}
**Completed**: {timestamp}

#### Changes Made
- {Summary of what was implemented}
- {Files modified and why}

#### Notes
{Any relevant observations during execution}

---

## Decisions

Choices made during execution that weren't in the original plan.

### {Decision Title}
**Context**: Why this decision was needed
**Options Considered**: What alternatives existed
**Decision**: What was chosen
**Rationale**: Why this choice was made
**Impact**: How this affects the flight or future legs

---

## Deviations

Departures from the planned approach.

### {Deviation Title}
**Planned**: What the flight specified
**Actual**: What was done instead
**Reason**: Why the deviation was necessary
**Outcome**: Result of the deviation

---

## Anomalies

Unexpected issues or behaviors encountered.

### {Anomaly Title}
**Observed**: What happened
**Expected**: What should have happened
**Severity**: blocking | degraded | cosmetic
**Resolution**: How it was handled (or "unresolved")
**Follow-up**: Any actions needed later

---

## Session Notes

Chronological notes from each work session.

### {Date/Session Identifier}
- {Note about progress or observation}
- {Note about what was attempted}
- {Note about what was learned}

When to Update the Flight Log

Starting a Leg

Record:

• Leg name and start timestamp
• Any context carried from previous legs
• Initial observations about the task

During Execution

Record:

• Decisions that diverge from or extend the plan
• Unexpected complexity or simplicity
• Anomalies encountered (even if resolved)

Completing a Leg

Record:

• Completion timestamp
• Summary of changes made
• Files modified
• Any notes for future legs

Encountering Issues

Record immediately:

• What went wrong
• What was expected
• Severity and impact
• Resolution or workaround

Using Flight Logs When Creating Legs

When generating new legs with /leg, the flight log must be consulted to understand:

1. What's actually complete: The log shows real completion status, not just planned progress
2. Decisions made: Mid-flight decisions may change how subsequent legs should be implemented
3. Discovered context: Anomalies and deviations reveal system behavior that affects new work
4. Patterns established: Implementation approaches that worked (or didn't) inform future guidance

Example: Log Informing Leg Creation

Flight log entry:

### API Authentication Leg
**Status**: completed

#### Changes Made
- Implemented JWT auth in `src/middleware/auth.ts`
- Used `jose` library instead of planned `jsonwebtoken` (see Decisions)

#### Decisions
**JWT Library Change**
- Context: `jsonwebtoken` had CVE flagged in security scan
- Decision: Switch to `jose` library
- Impact: All subsequent auth-related code must use `jose` patterns

Impact on next leg: When creating the "Protected Routes" leg, the guidance must specify using jose patterns, not the originally planned jsonwebtoken approach. Without the flight log, this context would be lost.

Location

Flight log location is defined in .flightops/ARTIFACTS.md. The artifact system determines where and how logs are stored.

Best Practices

Keep Entries Atomic

Write entries as things happen, not in batches. Batched entries lose detail and context.

Be Factual, Not Editorial

Good: "Validation logic required 3 additional edge cases not in spec" Avoid: "The spec was incomplete and caused problems"

Link to Specifics

Reference file paths, line numbers, commit hashes when relevant. Vague entries lose value quickly.

Capture the "Why"

The code shows what changed. The log should capture why decisions were made.

Don't Duplicate the Leg

The leg document has acceptance criteria and implementation guidance. The log records completion status and what actually happened—not a copy of the plan.

Common Patterns

Discovery Pattern

When execution reveals something unexpected:

### Discovery: Rate Limiting Already Exists
**Observed**: Found existing rate limiter in `src/middleware/rateLimit.ts`
**Expected**: Needed to implement from scratch per flight spec
**Impact**: Leg `implement-rate-limiting` can be simplified to configuration
**Action**: Updated leg scope, reduced from 4 hours to 30 minutes

Blocker Pattern

When progress stops:

### Blocker: Missing API Credentials
**Observed**: Stripe API key not in environment
**Severity**: blocking
**Impact**: Cannot test payment integration
**Resolution**: Requested credentials from DevOps
**Unblocked**: {timestamp when resolved}

Adaptation Pattern

When the plan needs adjustment:

### Deviation: Schema Change
**Planned**: Add `verified` boolean to User model
**Actual**: Added `verifiedAt` timestamp instead
**Reason**: Team decided verification time is valuable data
**Outcome**: Provides more information, minor query adjustments needed

Next Steps

• Flights — Understanding flight structure and lifecycle
• Legs — How legs are created and executed
• Workflow — The complete flow from mission to completion