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/` |