Engineering Intelligence

Engineering Intelligence

Format and criteria for capturing decisions, anomalies, and findings during development.

Captures go to github.com/tiagokrebs/claude-agentic-platform-engineering-intelligence, cloned locally at ~/claude-agentic-platform-engineering-intelligence. They are written automatically by the architect (decisions) and reviewer (anomalies, findings) — never by the developer manually.

---

Capture Types

decision

A design choice where the reasoning isn't obvious from the code. Capture when:

• Two or more viable approaches were considered and one was chosen
• The choice would likely be revisited or made differently by a mid-dev without this context
• The constraint driving the decision is not visible in the code

Do not capture: choices covered by an ADR, choices dictated by the existing skill library, obvious framework defaults.

anomaly

Behavior that contradicts reasonable expectations. Capture when:

• An edge case caused a bug or near-miss that wasn't obvious from reading the code
• Debugging required more than a straightforward investigation
• The fix is simple but the root cause is non-obvious

Do not capture: standard bugs fixed with expected solutions, anything a mid-dev would diagnose in under 10 minutes from error output alone.

finding

A pattern or constraint a mid-dev might not know and would likely get wrong on first attempt. Capture when:

• A good practice was applied that isn't documented in the skills library
• A constraint (platform, runtime, infra) shaped the solution in a non-obvious way
• The same class of problem is likely to recur

Do not capture: anything already in php-node-conventions, git-workflow, or adr-format skills. Anything a quick search would immediately resolve.

---

File Format

---
type: decision | anomaly | finding
date: YYYY-MM-DD
tags: [comma, separated, tags]
project: <project name or "general">
---

# <Short title — what it is, not what happened>

## Context
One paragraph. What was being worked on, what situation triggered this.

## What Was Found / Decided
The core content. Be specific — include code snippets, commands, or config if they make it clearer.

## Why It Matters
Why a mid-level developer needs to know this. What goes wrong without this knowledge.

## Related
- ADR-NNN (if applicable)
- Skill: <skill-name> (if applicable)
- EI: <filename> (if applicable)

---

File Naming

YYYY-MM-DD-<type>-<short-slug>.md

Examples:

2026-03-21-decision-client-db-isolation-strategy.md
2026-03-21-anomaly-php-fpm-pool-config-silent-fail.md
2026-03-21-finding-pino-err-field-serialization.md

Save to engineering-intelligence/ in the EI repo. Run scripts/push-ei.sh after writing.