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

### 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`.

3.5 KiB Raw Blame History