agent-observations · git:20260408.61db2e8 · 2026-04-08 · sha256 84181ea0248d673a
agent-observations git:20260408.61db2e8A
Immutable. This exact content never changes and is served at /api/v1/blob/84181ea0248d673a.
---
description: Mandatory agent observation logging — anomalies, recommendations, and critical findings must be disclosed before commit
globs: "src/**"
alwaysApply: false
---
# Agent Observation Logs — Mandatory Disclosure System
## Purpose
During any task, you will encounter information the user needs to know. **You MUST proactively disclose these findings.** Silence is a violation.
> **Observation logs vs. task logs:** Task logs (`docs/task/logs/`) record *what was done* (completed work). Observation logs record *what was discovered* — findings, risks, and anomalies that the user needs to know about, regardless of whether they're related to completed work.
---
## Directory Structure
```
docs/agent-observations/
├── critical.md
├── recommendations.md
├── anomalies.md
└── closed/
├── critical.md
├── recommendations.md
└── anomalies.md
```
- **Root files** = open/in-progress items only.
- **Closed files** = append-only resolved archives.
---
## The Three Observation Logs
### 1. `critical.md` — Blocking Issues
Data inconsistencies, security misconfigurations, broken assumptions, regression risks, data corruption.
### 2. `recommendations.md` — Improvement Suggestions
Follow-up tasks, optimization opportunities, architectural improvements.
### 3. `anomalies.md` — Inconsistencies & Drift
Doc/code divergence, unused components, mismatched config values.
---
## Entry Format
```markdown
| {date} | {source} | {observation} | {impact} | {action} | Open |
```
---
## When to Write Observations
### During Implementation (MANDATORY)
1. Data consistency — check for order meta integrity, duplicate transaction IDs
2. Code/doc alignment — verify docs match actual behavior
3. Assumption validation — confirm WooCommerce API behavior matches expectations
4. Side effects of changes — check for webhook processing regressions
5. Things outside your task scope — security concerns, deprecated API usage
### During Planning / During Reporting
Log anything unexpected, cross-post findings.
---
## The Observation Gate — BLOCKING
Before you commit:
1. Review your work.
2. Classify observations.
3. Append entries.
4. If no observations: `Observations: none.`
**Silence is a violation. CRITICAL — NO SKIPPING.**
---
## Closing Observations — Move to `closed/`
1. Remove row from root file.
2. Append to `closed/` file with `Closed` status and date/reason.
3. Critical: only user can authorize closing. Recommendations/anomalies: you may close if fixed.
---
## Cross-References
- **Reports:** cross-post findings.
- **Plans:** read logs first.
- **Execution:** check for relevant items.
- **Task Documentation:** observation gate runs BEFORE docs.
---
## Enforcement Summary
| Situation | Action |
|---|---|
| Broken/dangerous | Append to `critical.md` immediately |
| Improvement suggestion | Append to `recommendations.md` before commit |
| Inconsistency | Append to `anomalies.md` before commit |
| No observations | State "Observations: none" |
| Generating report | Cross-post to observation logs |
| Creating plan | Read observation logs first |
| About to commit | Verify logged or "none" |
| Resolved | Move root → `closed/` |