74 lines
3.5 KiB
Markdown
74 lines
3.5 KiB
Markdown
# 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`.
|
|
```
|