# Standardized Agent Telemetry Protocol

This protocol defines the **WHAT-WHY-HOW-LEARNINGS** communication standard for
autonomous agents. It eliminates unstructured conversational filler and ensures
every completion report and pull request provides verified empirical evidence and
captures reusable operational memory.

## Governing principle

**"The model proposes, but the engine measures."**
An agent must never claim completion based on internal heuristics or theoretical
assumptions. Verification requires concrete CLI execution evidence with explicit
exit codes and metric outputs.

## Telemetry structure

When reporting task completion or generating pull request bodies, format the
output using these four distinct sections:

### 1. WHAT (System Modifications)
Itemize physical repository deltas. Do not use speculative language. Mirror the
factual `git status` / `git diff` state:
- **Modified Components**: Relative paths of modified files.
- **Added Assets**: Relative paths of newly created modules, tests, or configurations.
- **Removed Assets**: Deprecated files, removed functions, or deleted packages.

### 2. WHY (Context & Architectural Intent)
Articulate the underlying rationale and business justification:
- **Problem Statement**: Explicit description of the bug, requirement, or performance bottleneck.
- **Requirement Traceability**: Reference to specification issue, plan bead, or task ticket.
- **Design Justification**: Why this approach was selected over alternative implementations.

### 3. HOW (Technical Implementation & Verification Evidence)
Detail the mechanical execution and empirical proof of correctness:
- **Implementation Details**: Summary of algorithmic changes, API updates, or data structures.
- **Deterministic Verification Evidence**:
  - Exact command(s) executed (e.g. `pytest tests/unit/test_auth.py -v`).
  - Terminal exit code (must be 0).
  - Test runner output metrics (e.g. `38 passed, 0 failed, 100% pass rate in 1.4s`).
- **Static Analysis & Type Checks**:
  - Linter/type checker commands and output (e.g. `ruff check src/` -> clean).

### 4. LEARNINGS & ARCHITECTURAL GOTCHAS
Capture operational traps, latent technical debt, and environment quirks:
- **Operational Traps**: Version sensitivities, platform discrepancies, race conditions.
- **Uncovered Debt**: Missing mocks, tight couplings, or obsolete patterns uncovered.
- **Repository Gotchas**: When a new trap or quirk is discovered, persist it to
  `docs/gotchas/<slug>.md` so subsequent sessions load it into context.
- **Upstream Dependencies**: Follow-up tasks or recommendations.

## Markdown template for PRs and task reports

```markdown
### 1. WHAT (System Modifications)
- **Modified**: `src/auth/session.py`
- **Added**: `tests/unit/test_session_refresh.py`
- **Removed**: None

### 2. WHY (Context & Architectural Intent)
- **Problem**: Concurrent session refresh requests cause race conditions and invalid tokens.
- **Traceability**: Closes #142 (Task T-3).
- **Design Justification**: Implemented in-process locking with Redis token leases.

### 3. HOW (Technical Implementation & Verification Evidence)
- **Implementation**: Wrapped refresh logic in distributed mutex with 5s expiry.
- **Verification Commands Executed**:
  - `pytest tests/unit/test_session_refresh.py` (Exit Code: 0, 12 passed in 0.8s)
  - `ruff check src/auth/` (Exit Code: 0, clean)

### 4. LEARNINGS & ARCHITECTURAL GOTCHAS
- **Operational Trap**: Redis cluster failover resets key TTL in mock environment.
- **Indexed Gotcha**: Saved to `docs/gotchas/redis-mock-cluster-ttl.md`.
```