Reasoning and Handoff

Reasoning logs and handoff envelopes are the mechanisms that preserve decision context as work moves between agents. This page explains how agents record decisions and transfer structured context.

Reasoning Log

Every non-trivial decision is recorded with structured metadata for auditability and traceability:

Field	Description
Decision	What was decided
Principle Applied	Which design principle or ADR guided the decision
Alternatives Considered	Other options that were evaluated
Justification	Why this option was chosen over others
Confidence	High, Medium, or Low, indicating certainty

The reasoning log prevents decisions from becoming tribal knowledge. When a new team member joins or requirements change, the log explains what was decided and why.

Handoff Envelope

When work moves between phases (e.g., specify to plan), context is transferred via a structured envelope (ADR 0003):

Relevant Artifacts

Paths to files the next phase should read: spec.md, plan.md, ADRs, tasks.md.

Inherited Assumptions

Decisions and assumptions from the current phase that carry forward and need validation.

Pending Decisions

Open questions or decisions that the next phase needs to resolve before proceeding.

Discarded Information

Context that was considered but explicitly excluded from the handoff, with rationale.

Why Clean Context Matters

Each phase starts with clean context and reads artifacts from disk. This isolation prevents assumption contamination from previous phases.

Phase Cleanup Points

Phase transitions include structured cleanup points that preserve decisions while resetting context. See Context Management for the full cleanup sequence.

Artifacts as Source of Truth

The framework relies on disk artifacts as the canonical source of design decisions. See Context Management for the complete artifact authority model.

End-to-End Traceability

flowchart LR
  vision["Business Vision"] --> epics["Epics"]
  epics --> features["Features"]
  features --> stories["User Stories"]
  stories --> tasks["Tasks"]
  tasks --> branches["Branches"]
  branches --> prs["Pull Requests"]
  prs --> code["Code"]

Work items include hierarchy and tags (copilot-generated, ai-model:MODEL). Tasks reference requirements (FR-XXX) and conformance criteria (CC-XXX). PRs reference tasks (Closes #N). Every line of code is traceable back to a business requirement.

Context Management: Technical details of memory and session management
Comprehension Checkpoints: How understanding is verified at each phase
Impact Classification: Determines the level of reasoning documentation required